Documentación de la plantilla

Descripción

Plantilla para organizar proyectos que usan Python e incorporar mejores prácticas relacionadas con:

• Version control: Git (libro: Pro Git, tutorial: Getting Git Right: Learn Git with Tutorials, News and Tips)
• Project management, Virtual environments y Dependencies management: uv
• Static typing: Ty
• Code formatting, Linting y Style enforcement: Ruff
• Package vulnerability analysis: pip-audit
• Commit management: prek, Commitizen
• Documentation: MkDocs, Material for MkDocs, Google docstrings
• Environmental variables y .env files: Pydantic-Settings
• Logging: Loguru
• Debugging: The Python Debugger (tutorial: Python Debugging With Pdb), IceCream
• Testing: pytest (tutorial: Effective Python Testing With Pytest), pytest-cov

Opcionalmente:

• nb: Python notebooks: marimo, (ver página Notebooks para más detalles)
• dvc: Data version control: DVC, (ver página Data version control para más detalles)

¡Atención!

Es conocido que DVC puede presentar problemas de compatibilidad cuando se usa en WindowsOS. Se recomienda revisar la documentación oficial de DVC, particularmente las siguientes páginas:

• Installation on Windows
• How to Run DVC on Windows

Si va a utilizar esta práctica opcional, es preferible usar MacOS o LinuxOS para evitar inconvenientes.

Estructura

El proyecto usa la siguiente estructura de carpetas y archivos:

Estructura de carpetas y archivos del proyecto

Carpetas

A continuación se describe el propósito de cada una de las carpetas:

.github/

Carpeta para almacenar los archivos que configuran las GitHub Actions. Estos archivos están escritos en formato YAML y permiten automatizar tareas como la integración continua, el despliegue continuo, la gestión de incidencias, entre otras.

En principio no es necesario que modifique estos archivos, pero si desea personalizar las acciones automatizadas del proyecto, puede hacerlo editando los archivos dentro de esta carpeta o creando nuevos archivos según sus necesidades.

data/

Carpeta para almacenar los archivos de datos (e.g. archivos .txt, .csv, .parquet, .xlsx, ...). Dentro de la carpeta se pueden crear sub-carpetas para almacenar los datos en distintos estados (e.g. crudos (raw), pre-procesados, procesados, ...).

Esta carpeta NO debe estar versionada con Git, y por defecto, está incluida en el archivo .gitignore del proyecto.

Se incluye una sub-carpeta especial (querys/) destinada a almacenar los querys (e.g. archivos .sql, .graphql .gql) que se utilizan para generar los datos. Esta sub-carpeta si se debe versionar en Git, y por defecto, el .gitignore del proyecto está configurado para que así sea.

Para hacer versionamiento de los archivos de datos y/o modelos del proyecto, que sean necesarios para asegurar la reproducibilidad del mismo, y se almacenen dentro de esta carpeta, se debe hacer uso lo explicado en la opción relacionada con Data version control.

docs/

Carpeta para almacenar y gestionar la documentación del proyecto. Se administra usando MkDocs, Material for MkDocs y Google docstrings.

notebooks/

Carpeta para almacenar los cuadernos (notebooks usando marimo) que utilice en el proyecto.

Para gestionar (i.e. crear, editar y eliminar) cuadernos (notebooks), se debe hacer uso lo explicado en la opción relacionada con Notebooks.

outputs/

Carpeta para almacenar los archivos de resultados (e.g. archivos .pdf, .png, .txt, .csv, .parquet, .xlsx, ...). Dentro de la carpeta se pueden crear sub-carpetas para almacenar distintos tipos de resultados (e.g. informes, gráficos, resultados, ...).

Esta carpeta NO debe estar versionada con Git, y por defecto, está incluida en el archivo .gitignore del proyecto.

Si se generan informes, se recomienda que en ellos incluya el tag que identifica la versión del proyecto que permite reproducirlos. De esta manera, en cualquier otro momento, será posible recrear los datos, los modelos y el código que permiten llegar a los mismos resultados.

src/

Carpeta para almacenar el código (i.e. archivos .py). Dentro de la carpeta se pueden crear sub-carpetas para organizar el código adecuadamente.

tests/

Carpeta para almacenar las pruebas del proyecto (i.e. archivos .py). Dentro de la carpeta se pueden crear sub-carpetas para organizar las pruebas adecuadamente. Las pruebas se deben escribir usando pytest.

Archivos

A continuación se describe el propósito de algunos de los archivos más importantes del proyecto:

.env.private

Archivo para almacenar las variables de entorno privadas del proyecto. Este archivo NO debe estar versionado con Git, y por defecto, está incluido en el archivo .gitignore del proyecto.

Para más información sobre el uso de variables de entorno en el proyecto, consulte el archivo src/tutorial.py.

.env.public

Archivo para almacenar las variables de entorno públicas del proyecto. Este archivo SI debe estar versionado con Git.

Para más información sobre el uso de variables de entorno en el proyecto, consulte el archivo src/tutorial.py.

.gitignore

Archivo para especificar los archivos y carpetas que Git debe ignorar al momento de hacer seguimiento de los cambios en el proyecto. Este archivo es fundamental para evitar que archivos temporales, archivos de configuración local o archivos generados automáticamente se incluyan en el control de versiones.

El archivo .gitignore del proyecto ya incluye las configuraciones necesarias para ignorar las carpetas data/ y outputs/, entre otros archivos y carpetas comunes que no deben ser versionados.

pre-commit-config.yaml

Archivo para configurar los hooks de prek en el proyecto. Este archivo define una serie de reglas y herramientas que se ejecutan automáticamente antes de realizar un commit en Git, con el fin de asegurar la calidad del código y mantener un estándar consistente en el proyecto.

El archivo pre-commit-config.yaml del proyecto ya incluye configuraciones para varias herramientas útiles, tales como: "formateadores" de código, linters y verificadores de seguridad.

Para más información sobre el uso de pre-commit en el proyecto, consulte Uso y Flujo de trabajo.

CHANGELOG.md

Archivo para llevar un registro de los cambios realizados en el proyecto a lo largo del tiempo. Este archivo sigue el formato de Keep a Changelog y ayuda a los desarrolladores y usuarios a entender la evolución del proyecto, facilitando la identificación de nuevas características, correcciones de errores y cambios importantes entre versiones.

Este archivo se actualiza automáticamente al hacer commits usando la instrucción just bump-code-version (o su alias just b). Para más información sobre el uso de just en el proyecto, consulte Uso y Flujo de trabajo.

justfile

Archivo para almacenar las tareas automatizadas del proyecto usando just. Este archivo contiene las instrucciones para ejecutar tareas comunes del proyecto, como instalar dependencias, ejecutar pruebas, generar documentación, entre otras.

Para más información sobre el uso de just en el proyecto, consulte Uso y Flujo de trabajo.

mkdocs.yml

Archivo para configurar la documentación del proyecto usando MkDocs y Material for MkDocs. Este archivo define la estructura, el tema, las extensiones y otras opciones relacionadas con la generación de la documentación del proyecto.

Para más información sobre el uso de MkDocs en el proyecto, consulte Uso y Flujo de trabajo.

pyproject.toml

Archivo para gestionar las dependencias y la configuración del proyecto usando uv. Este archivo define las librerías necesarias para el desarrollo y la ejecución del proyecto, así como otras configuraciones relacionadas con el entorno de desarrollo.

Para más información sobre el uso de uv en el proyecto, consulte Uso y Librerías adicionales.

README.md

Archivo para proporcionar una descripción general del proyecto, incluyendo su propósito, características principales, instrucciones de instalación y uso, entre otros detalles relevantes. Este archivo es lo primero que los usuarios y colaboradores ven al acceder al repositorio del proyecto.

El archivo README.md del proyecto (i.e. este archivo) ya incluye información básica sobre la plantilla y un enlace a la documentación completa en línea.

requeriments-dev.txt, requeriments-docs.txt, requeriments-tests.txt y requeriments.txt

Archivos para listar las dependencias del proyecto. Aunque el proyecto usa uv para gestionar las dependencias, estos archivos pueden ser útiles para herramientas o servicios que esperan encontrar archivos requirements.txt en el proyecto (e.g. GitHub Actions).

uv.lock

Archivo generado automáticamente por uv para asegurar que las dependencias del proyecto se instalen de manera consistente en diferentes entornos. Este archivo registra las versiones exactas de las librerías instaladas en el proyecto, incluyendo sus dependencias y sub-dependencias.

No es necesario modificar este archivo manualmente, ya que se actualiza automáticamente al instalar o actualizar las dependencias del proyecto usando uv.

Uso

Para instalar la plantilla y empezarla a usar en un nuevo proyecto, debe tener instalado previamente en su equipo, Git (versión >= 2.52.0), uv (versión >= 0.9.26) y just (versión >= 1.46.0).

¡Atención!

El proyecto incluye algunas funcionalidades que requieren un shell (sh) compatible con Unix (e.g. MacOS, LinuxOS).

Al instalar Git en WindowsOS, es posible instalar adicionalmente Git Bash, lo que proporciona un shell compatible con Unix. Si realiza esta instalación adicional y configura su sistema para usar Git Bash como shell predeterminado, tal como lo explica la documentación de la instalación de just, no debería tener inconvenientes al usar el proyecto en WindowsOS.

Si se le presentan errores, le agradecemos lo reporte para buscar soluciones.

Posteriormente, siga los pasos descritos a continuación:

1. Cree un nuevo repositorio a partir de esta plantilla (template) con el nombre de su nuevo proyecto. Asegúrese de marcar la opción Include all branches.

2. Clone el nuevo repositorio en su equipo local.

3. Instale el proyecto, ejecutando:

   just set-dev-env
   

   Si desea usar algunas de las librerías que proporcionan prácticas opcionales, ejecute:

   just set-dev-env <práctica opcional> # (1)!
   

   1. Debe reemplazar <práctica opcional> por el código de la práctica opcional. Por ejemplo: "--extra dvc" o "--extra nb".

   Si desea usar más de una práctica opcional, simplemente repita <práctica opcional>, separado por un espacio, las veces que necesite al final de la instrucción.

4. En el proyecto se usan prek hooks para automatizar la verificación del código antes de los commits y los pushs. La librería ya está incluida en las dependencias necesarias para contribuir al proyecto, sin embargo, es necesario configurar la herramienta usando las siguientes instrucciones:

   just install-prek-hooks
   

5. Consulte el archivo src/tutorial.py para conocer cómo usar las variables de entorno, el log y cómo hacer debugging fácilmente.

6. Consulte el archivo docs/tutorial.md para conocer las capacidades instaladas para documentar el proyecto. Para visualizar en limpio la documentación, ejecute:

   just serve-docs
   

   Esto le permitirá ver en el explorador la versión final de la documentación y hará que esta se actualice en línea en la medida que realice cambios.

7. Consulte la sección sobre Flujo de trabajo para conocer las recomendaciones para hacer un desarrollo ordenado y eficiente usando la plantilla.

¡Eso es todo!, puede empezar a trabajar en su nuevo proyecto.