Plantilla de proyecto de ciencia de datos

Una plantilla moderna para proyectos de ciencia de datos con todas las herramientas necesarias para experimentación, desarrollo, pruebas y despliegue. Desde notebooks hasta producción.

✨📚✨ Documentación: https://joserzapata.github.io/data-science-project-template/

Código Fuente: https://github.com/JoseRZapata/data-science-project-template

Características

Gestión de dependencias con UV
Gestión de entornos virtuales con UV
Linting con pre-commit y Ruff
Integración continua con GitHub Actions
Documentación con mkdocs y mkdocstrings usando el tema mkdocs-material
Actualizaciones automáticas de dependencias con Dependabot
Formateo de código con Ruff
Ordenamiento de imports con Ruff usando la regla isort.
Pruebas con pytest
Cobertura de código con Coverage.py
Reportes de cobertura con Codecov
Verificación estática de tipos con mypy
Auditoría de seguridad con Ruff usando la regla bandit.
Gestión de etiquetas del proyecto con GitHub Labeler

Referencias

📁 Crear un Nuevo Proyecto

👍 Recomendaciones

Se recomienda encarecidamente usar gestores para las versiones de Python, dependencias y entornos virtuales.

Este proyecto usa UV, una herramienta extremadamente rápida para reemplazar pip, pip-tools, Pipx, Poetry, Pyenv, twine, virtualenv, y más.

🌟 Revisa cómo configurar tu entorno: https://joserzapata.github.io/data-science-project-template/local_setup/

🍪🥇 Vía Cruft - (recomendado)

instalar cruft

# Instalar cruft en un entorno aislado usando uv

uv tool install cruft

# O instalar con pip

pip install --user cruft # Instalar `cruft` en tu PATH para fácil acceso

crear proyecto

cruft create https://github.com/JoseRZapata/data-science-project-template

luego dentro de la carpeta del proyecto, inicializar git y el entorno uv usando Make:

instalar proyecto

make init_git
make install_env
source .venv/bin/activate

🍪 Vía Cookiecutter

instalar cookiecutter

uv tool install cookiecutter # Instalar cookiecutter en un entorno aislado

# O instalar con pip

pip install --user cookiecutter # Instalar `cookiecutter` en tu PATH para fácil acceso

crear proyecto

cookiecutter gh:JoseRZapata/data-science-project-template

Nota: Cookiecutter usa gh: como abreviatura de https://github.com/

🔗 Vincular un Proyecto Existente

Si el proyecto fue instalado originalmente vía Cookiecutter, primero debes usar Cruft para vincular el proyecto con la plantilla original:

cruft link https://github.com/JoseRZapata/data-science-project-template

Luego:

cruft update

🗃️ Estructura del proyecto

Estructura de carpetas para proyectos de ciencia de datos ¿por qué?

.
├── .code_quality
│   ├── mypy.ini                        # configuración de mypy
│   └── ruff.toml                       # configuración de ruff
├── .github                             # configuración de github
│   ├── actions
│   │   └── python-poetry-env
│   │       └── action.yml              # github action para configurar entorno python
│   ├── dependabot.md                   # github action para actualizar dependencias
│   ├── pull_request_template.md        # plantilla para pull requests
│   └── workflows                       # flujos de trabajo de github actions
│       ├── ci.yml                      # ejecutar integración continua (pruebas, pre-commit, etc.)
│       ├── dependency_review.yml       # revisión de dependencias
│       ├── docs.yml                    # construir documentación (mkdocs)
│       └── pre-commit_autoupdate.yml   # actualizar hooks de pre-commit
├── .vscode                             # configuración de vscode
|   ├── extensions.json                 # lista de extensiones recomendadas
|   ├── launch.json                     # configuración de ejecución de vscode
|   └── settings.json                   # configuración de vscode
├── conf                                # carpeta de archivos de configuración
│   └── config.yaml                     # archivo principal de configuración
├── data
│   ├── 01_raw                          # datos crudos inmutables
│   ├── 02_intermediate                 # datos tipados
│   ├── 03_primary                      # datos del modelo de dominio
│   ├── 04_feature                      # características del modelo
│   ├── 05_model_input                  # frecuentemente llamados 'master tables'
│   ├── 06_models                       # modelos serializados
│   ├── 07_model_output                 # datos generados por ejecuciones del modelo
│   ├── 08_reporting                    # reportes, resultados, etc
│   └── README.md                       # descripción de la estructura de datos
├── docs                                # documentación de tu proyecto
│   ├── index.md                        # página principal de documentación
├── models                              # almacenar modelos finales
├── notebooks
│   ├── 1-data                          # extracción y limpieza de datos
│   ├── 2-exploration                   # análisis exploratorio de datos (EDA)
│   ├── 3-analysis                      # Análisis estadístico, pruebas de hipótesis.
│   ├── 4-feat_eng                      # ingeniería de características (creación, selección y transformación.)
│   ├── 5-models                        # entrenamiento de modelos, evaluación y ajuste de hiperparámetros.
│   ├── 6-interpretation                # interpretación de modelos
│   ├── 7-deploy                        # empaquetado de modelos, estrategias de despliegue.
│   ├── 8-reports                       # narrativa, resúmenes y conclusiones de análisis.
│   ├── notebook_template.ipynb         # plantilla para notebooks
│   └── README.md                       # información sobre los notebooks
├── src                                 # código fuente para uso en este proyecto
│   ├── README.md                       # descripción de la estructura de src
│   ├── tmp_mock.py                     # archivo python de ejemplo
│   ├── data                            # extracción, validación, procesamiento, transformación de datos
│   ├── model                           # entrenamiento, evaluación, validación, exportación de modelos
│   ├── inference                       # predicción, servicio, monitoreo de modelos
│   └── pipelines                       # orquestación de pipelines
│       ├── feature_pipeline            # transforma datos crudos en características y etiquetas
│       ├── training_pipeline           # transforma características y etiquetas en un modelo
│       └── inference_pipeline          # toma características y un modelo entrenado para predicciones
├── tests                               # código de pruebas para tu proyecto
│   ├── test_mock.py                    # archivo de prueba de ejemplo
│   ├── data                            # pruebas para el módulo data
│   ├── model                           # pruebas para el módulo model
│   ├── inference                       # pruebas para el módulo inference
│   └── pipelines                       # pruebas para el módulo pipelines
├── .editorconfig                       # configuración del editor
├── .gitignore                          # archivos a ignorar en git
├── .pre-commit-config.yaml             # configuración para hooks de pre-commit
├── codecov.yml                         # configuración para codecov
├── Makefile                            # comandos útiles para configurar entorno, ejecutar pruebas, etc.
├── mkdocs.yml                          # configuración para documentación mkdocs
├── pyproject.toml                      # archivo de dependencias y configuración del proyecto
├── uv.lock                             # dependencias bloqueadas
└── README.md                           # descripción de tu proyecto

✨ Características y Herramientas

🚀 Estandarización y Automatización del Proyecto

🔨 Automatización del Flujo de Trabajo del Desarrollador

Empaquetado de Python, gestión de dependencias y gestión de entornos con UV - ¿por qué usar un gestor? (uv es un reemplazo de poetry)
Orquestación del flujo de trabajo del proyecto con Make como interfaz shim
- Makefile autodocumentado; simplemente escribe make en la línea de comandos para mostrar documentación autogenerada sobre los objetivos disponibles:
Sincronización automatizada de plantillas Cookiecutter con Cruft - ¿por qué?
Automatización y gestión de herramientas de calidad de código con pre-commit
Integración y despliegue continuos con GitHub Actions
Archivos de configuración del proyecto con Hydra - ¿por qué?

🌱 Paquete Python o Plantilla de Proyecto Renderizado Condicionalmente

Opcional: Soporte para Jupyter

🔧 Mantenibilidad

🏷️ Verificación de Tipos y Validación de Datos

Verificación estática de tipos con Mypy

✅ 🧪 Pruebas/Cobertura

Pruebas con Pytest
Cobertura de código con Coverage.py
Reportes de cobertura con Codecov

🚨 Linting

🔍 Calidad de código

Ruff Un linter y formateador de Python extremadamente rápido (10x-100x más rápido), escrito en Rust.
- Reemplazo de ~~Pylint~~, ~~Flake8~~ (incluyendo plugins principales) y más linters bajo una interfaz única y común
ShellCheck
Commits no seguros:
- Secretos con detect-secrets
- Archivos grandes con check-added-large-files
- Archivos que contienen cadenas de conflicto de merge. check-merge-conflict

🎨 Formateo de código

Ruff Un linter y formateador de Python extremadamente rápido (10x-100x más rápido), escrito en Rust.
- Reemplazo de ~~Black~~, ~~isort~~, ~~pyupgrade~~ y más formateadores bajo una interfaz única y común
Formateo general de archivos:
- end-of-file-fixer
- pretty-format-json
- (trim) trailing-whitespace
- check-yaml

👷 CI/CD

Actualizaciones automáticas de dependencias

Actualizaciones de dependencias con Dependabot, merge automatizado de PRs de Dependabot con el Dependabot Auto Merge GitHub Action
Esto es un reemplazo de pip-audit, En tu entorno local, si quieres verificar vulnerabilidades en tus dependencias puedes usar [pip-audit].

Revisión de dependencias en PR

Revisión de dependencias con dependency-review-action, esta acción escanea tus pull requests por cambios de dependencias, y generará un error si se están introduciendo vulnerabilidades o licencias inválidas.

Actualizaciones automáticas de Pre-commit

Actualizaciones automáticas con flujo de trabajo de GitHub Actions .github/workflows/pre-commit_autoupdate.yml

🔒 Seguridad

🔏 Pruebas Estáticas de Seguridad de Aplicaciones (SAST)

Vulnerabilidades de código con Bandit usando Ruff

⌨️ Accesibilidad

🔨 Herramienta de automatización (Makefile)

Makefile para automatizar la configuración de tu entorno, la instalación de dependencias, la ejecución de pruebas, etc. en la terminal escribe make para ver los comandos disponibles

Target                Descripción
-------------------   ----------------------------------------------------
check                 Ejecutar herramientas de calidad de código con hooks de pre-commit.
docs_test             Probar si la documentación se puede construir sin advertencias o errores
docs_view             Construir y servir la documentación
init_env              Instalar dependencias con uv y activar entorno
init_git              Inicializar repositorio git
install_data_libs     Instalar pandas, scikit-learn, Jupyter, seaborn
pre-commit_update     Actualizar hooks de pre-commit
test                  Probar el código con pytest y cobertura

📝 Documentación del Proyecto

Construcción de documentación con MkDocs - Tutorial
- Potenciado por mkdocs-material
- Documentación automática rica a partir de anotaciones de tipo y docstrings (NumPy, Google, etc.) con mkdocstrings