Saltar a contenido

Documentación de la plantilla

Descripción

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

Opcionalmente:

Estructura

El proyecto usa la siguiente estructura de carpetas y archivos:

Estructura del Proyecto

Estructura de carpetas y archivos del proyecto

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

data/

Carpeta para almacenar los archivos de datos (e.g. archivos .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 .gitignore.

Se incluye una sub-carpeta especial (querys/) destinada a almacenar los querys (archivos .sql) que se utilizan para generar los datos. Esta sub-carpeta si se debe versionar en Git, y por defecto, está configurada para que así sea.

Para hacer versionamiento de los datos y/o modelos, se debe hacer uso lo explicado en la práctica 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. Archivos .ipynb) que utilice en el proyecto. Si va a utilizar esta carpeta debe usar la práctica opcional Jupyter notebooks compatibility y seguir las instrucciones para hacer un adecuado versionamiento de los cuadernos.

outputs/

Carpeta para almacenar los archivos de resultados (e.g. archivos .pdf, .png, .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 .gitignore.

Para hacer versionamiento de los datos que hagan parte de los resultados, y por lo tanto se almacenen dentro de esta carpeta, se debe hacer uso lo explicado en la práctica relacionada con Data version control.

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

src/

Carpeta para almacenar el código (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 (archivos .py). Dentro de la carpeta se pueden crear sub-carpetas para organizar las pruebas adecuadamente. Las pruebas se deben escribir usando pytest.

Uso

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

¡Atención!

El proyecto tiene un makefile y un archivo shell (write-requirements.sh) que no corren en WindowsOS por defecto. Por lo tanto es necesario instalar si está utilizando este sistema operativo, adicionalmente, Make. (Tutorial: How to setup/install GNU make on Windows).

Si siguió las instrucciones descritas anteriormente, todas las funcionalidades de la plantilla debe funcionar adecuadamente tanto en WindowsOS, como en MacOS y LinuxOS. Si se le presentan errores:

  1. Es necesario remover el pre-commit que exporta los archivos de librarías requeridas de .pre-commit-config.yaml. y no usar make.
  2. Agradecemos lo reporte para buscar una solución.

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:

    uv sync --extra tests --extra docs

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

    uv sync --extra tests --extra docs --extra <práctica opcional> # (1)!
    1. Debe reemplazar <práctica opcional> por el código de la práctica opcional. Por ejemplo: ... --extra dvc.

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

    ¡Atención!

    Si opta por usar la opción notebooks, debe agregar a su archivo de configuración de git (gitconfig)1 las siguientes instrucciones al final del mismo:

    [filter "strip-notebook-output"]
clean = "uvx jupyter nbconvert --ClearOutputPreprocessor.enabled=True --ClearMetadataPreprocessor.enabled=True --to=notebook --stdin --stdout --log-level=ERROR"

    Esto le indica a git que al agregar un archivo .ipynb al stage, debe crearle una copia en la que limpie la metadata y los outputs. De esta forma se optimiza el versionamiento de este tipo de archivos, y se garantiza que en el equipo local del usuario se mantienen tanto la metadata como los outputs.

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

    uv run pre-commit install
uv run pre-commit install --hook-type pre-commit
uv run pre-commit install --hook-type pre-push

  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 trabajar en la documentación, ejecute:

    uv run mkdocs serve

    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.

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

  1. Este archivo se encuentra en la siguiente ruta: ~/gitconfig. ↩