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 archivo .gitignore del proyecto1.

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 que hagan parte del proyecto y sean necesarios para asegurar la reproducibilidad del mismo, 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.

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 práctica relacionada con Notebooks.

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 archivo .gitignore del proyecto1.

Para hacer versionamiento de los datos que hagan parte del proyecto y sean necesarios para asegurar la reproducibilidad del mismo, 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 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 es posible recrear los datos, los modelos y el 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.50.0) y uv (versión >= 0.7.13).

¡Atención!

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

Si siguió las instrucciones descritas anteriormente, todas las funcionalidades de la plantilla deben 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 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.

  4. En el proyecto se usan pre-commit 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 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. ↩↩