{ "cells": [ { "metadata": { "collapsed": true }, "cell_type": "markdown", "source": [ "# Guía Formal sobre Estructuras de Proyectos en Python\n", "\n", "El desarrollo de proyectos en **Python** requiere una estructura bien definida que permita mantener el código organizado, escalable y fácil de mantener.\n", "Una estructura coherente facilita la colaboración entre desarrolladores, la integración continua y la distribución del software.\n", "\n", "Este documento describe las **estructuras más comunes de proyectos Python**, analizando buenas prácticas, ejemplos y herramientas modernas para la gestión de entornos, con especial énfasis en **`uv`**, una herramienta de alto rendimiento para la gestión de entornos y dependencias.\n", "Además, se incluyen recomendaciones sobre el uso de **Jupyter Notebooks** y la **organización de datos** en proyectos científicos o analíticos.\n", "\n", "---\n", "\n", "## 1. Introducción a las estructuras de proyectos\n", "\n", "Una estructura de proyecto en Python define cómo se organizan los archivos y directorios del código fuente, las dependencias, los scripts de configuración y los recursos auxiliares.\n", "\n", "Los objetivos principales son:\n", "\n", "- Separar el código fuente de los datos, las notebooks y la configuración.\n", "- Facilitar la reutilización del código y la automatización de tareas.\n", "- Permitir la distribución del proyecto como paquete instalable.\n", "- Favorecer la gestión de entornos virtuales reproducibles y seguros.\n", "- Integrar de forma ordenada los notebooks de experimentación.\n", "\n", "---\n", "\n", "## 2. Estructura básica de un proyecto Python\n", "\n", "Una estructura simple, adecuada para proyectos pequeños o scripts personales, puede ser la siguiente:\n", "\n", "```\n", "mi_proyecto/\n", "│\n", "├── venv/ # Entorno virtual (opcional)\n", "├── main.py # Punto de entrada principal\n", "├── requirements.txt # Dependencias del proyecto\n", "└── README.md # Documentación básica\n", "```\n", "\n", "Esta estructura es suficiente para scripts o utilidades simples, pero no es adecuada para proyectos colaborativos o de larga duración.\n", "\n", "---\n", "\n", "## 3. Estructura modular (proyectos medianos y grandes)\n", "\n", "A medida que el proyecto crece, se recomienda una organización modular y clara:\n", "\n", "```\n", "mi_proyecto/\n", "│\n", "├── src/ # Código fuente principal\n", "│ └── mi_proyecto/\n", "│ ├── __init__.py\n", "│ ├── core.py\n", "│ ├── utils/\n", "│ │ └── __init__.py\n", "│ └── data_processing.py\n", "│\n", "├── data/ # Carpeta para almacenar datos\n", "│ ├── raw/ # Datos sin procesar\n", "│ ├── processed/ # Datos limpios y transformados\n", "│ └── external/ # Datos externos o descargados\n", "│\n", "├── notebooks/ # Notebooks de análisis o experimentación\n", "│ ├── 01_exploracion.ipynb\n", "│ ├── 02_modelado.ipynb\n", "│ └── utils.ipynb\n", "│\n", "├── requirements.txt # Dependencias del proyecto\n", "├── pyproject.toml # Configuración avanzada (PEP 621)\n", "├── .gitignore\n", "└── README.md\n", "```\n", "\n", "### Ventajas de esta estructura\n", "\n", "- **Claridad modular:** separación del código fuente, notebooks y datos.\n", "- **Escalabilidad:** permite mantener un flujo limpio entre desarrollo y análisis.\n", "- **Colaboración eficiente:** notebooks separados del código productivo.\n", "\n", "---\n", "\n", "## 4. Estructura de proyectos con Jupyter Notebooks\n", "\n", "Los **Jupyter Notebooks** (`.ipynb`) son herramientas esenciales para exploración de datos, visualización y prototipado rápido.\n", "Sin embargo, deben mantenerse **separados del código de producción** para evitar confusión y mejorar la mantenibilidad.\n", "\n", "### Estructura recomendada con notebooks\n", "\n", "```\n", "mi_proyecto/\n", "│\n", "├── src/ # Código fuente principal\n", "│ └── mi_proyecto/\n", "│ ├── __init__.py\n", "│ ├── core.py\n", "│ ├── model/\n", "│ │ ├── train.py\n", "│ │ └── evaluate.py\n", "│ └── utils/\n", "│ └── data_utils.py\n", "│\n", "├── notebooks/ # Notebooks de exploración y presentación\n", "│ ├── 00_exploracion_inicial.ipynb\n", "│ ├── 01_limpieza_datos.ipynb\n", "│ ├── 02_modelado.ipynb\n", "│ └── 03_visualizacion_resultados.ipynb\n", "│\n", "├── data/\n", "│ ├── raw/\n", "│ ├── processed/\n", "│ ├── results/\n", "│ └── external/\n", "│\n", "├── reports/ # Resultados y documentación generada\n", "│ ├── figuras/\n", "│ └── informe_final.pdf\n", "│\n", "├── environment.yml # (opcional) Configuración alternativa para Conda\n", "├── pyproject.toml\n", "├── requirements.txt\n", "├── .gitignore\n", "└── README.md\n", "```\n", "\n", "### Buenas prácticas con Jupyter Notebooks\n", "\n", "1. **Nombrar los notebooks con prefijos numéricos** para reflejar el orden lógico del flujo de trabajo.\n", " Ejemplo: `01_preprocesamiento.ipynb`, `02_modelado.ipynb`.\n", "2. **Evitar lógica de negocio compleja** dentro de los notebooks.\n", " El código debe modularizarse y residir en `src/`.\n", "3. **Importar funciones y módulos desde `src/`** para mantener consistencia:\n", " ```python\n", " from mi_proyecto.utils.data_utils import cargar_datos\n", " ```\n", "4. **Mantener notebooks limpios y ejecutables desde cero.**\n", " Deben poder ejecutarse completamente tras un `Restart & Run All`.\n", "5. **Guardar los resultados procesados** en `data/processed/` o `data/results/`, no en el notebook.\n", "6. **Exportar los notebooks** a formatos reproducibles (`.html` o `.pdf`) para documentación final.\n", "---\n", "\n", "## 5. El archivo `requirements.txt`\n", "\n", "El archivo `requirements.txt` lista todas las dependencias necesarias para ejecutar el proyecto.\n", "Es un componente esencial para garantizar que el entorno de desarrollo y producción sean idénticos.\n", "\n", "### 5.1 Ejemplo básico\n", "\n", "```\n", "numpy==2.0.1\n", "pandas>=2.2.0,<3.0.0\n", "matplotlib==3.9.1\n", "scikit-learn>=1.4.0\n", "jupyterlab==4.2.0\n", "```\n", "\n", "### 5.2 Creación automática\n", "\n", "Puedes generar el archivo a partir del entorno activo:\n", "\n", "```bash\n", "uv pip freeze > requirements.txt\n", "```\n", "o, si usas `pip` tradicional:\n", "```bash\n", "pip freeze > requirements.txt\n", "```\n", "\n", "### 5.3 Instalación de dependencias\n", "\n", "Para reproducir un entorno:\n", "\n", "```bash\n", "uv pip install -r requirements.txt\n", "```\n", "\n", "### 5.4 Buenas prácticas con `requirements.txt`\n", "\n", "- Especificar versiones exactas (`==`) para despliegues productivos.\n", "- Usar rangos (`>=, <`) durante la fase de desarrollo.\n", "- Complementar con `pyproject.toml` para definir dependencias de desarrollo y metadatos.\n", "- Mantener actualizado mediante `uv pip freeze` o herramientas como `pip-tools`.\n", "\n", "---\n", "\n", "## 6. Gestión de entornos con `uv` (recomendado)\n", "\n", "[`uv`](https://github.com/astral-sh/uv) es una herramienta moderna desarrollada por **Astral**, los creadores de `ruff` y `rye`.\n", "Proporciona una gestión de entornos virtuales y dependencias **ultrarrápida**, reproducible y compatible con los estándares de Python.\n", "\n", "### 6.1 Instalación\n", "\n", "```bash\n", "pip install uv\n", "```\n", "o mediante script oficial:\n", "```bash\n", "curl -LsSf https://astral.sh/uv/install.sh | sh\n", "```\n", "\n", "### 6.2 Creación y activación de entornos\n", "\n", "```bash\n", "uv venv\n", "source .venv/bin/activate\n", "```\n", "\n", "Por defecto, el entorno se crea en `.venv/`. Es totalmente compatible con herramientas como `jupyter`, `black` y `ruff`.\n", "\n", "### 6.3 Instalación de dependencias\n", "\n", "```bash\n", "uv pip install -r requirements.txt\n", "```\n", "o directamente:\n", "```bash\n", "uv pip install .\n", "```\n", "\n", "### 6.4 Ventajas de `uv`\n", "\n", "| Característica | Descripción |\n", "|-----------------|-------------|\n", "| **Velocidad** | Hasta 20 veces más rápido que `pip` o `conda`. |\n", "| **Compatibilidad** | Totalmente interoperable con `pyproject.toml` y `requirements.txt`. |\n", "| **Reproducibilidad** | Crea entornos deterministas y caché inteligente. |\n", "| **Ligereza** | Sin dependencias externas, multiplataforma. |\n", "| **Integración** | Soporte directo para `jupyter` y herramientas modernas de desarrollo. |\n", "\n", "---\n", "\n", "## 7. Propuesta para almacenar datos\n", "\n", "En proyectos de análisis o ciencia de datos, los datasets deben organizarse con una estructura clara y reproducible.\n", "\n", "```\n", "data/\n", "├── raw/ # Datos originales sin modificar\n", "├── processed/ # Datos limpios y listos para análisis\n", "├── external/ # Datos descargados de fuentes externas\n", "└── results/ # Resultados o predicciones generadas\n", "```\n", "\n", "### Buenas prácticas\n", "\n", "1. **Evitar almacenar datos grandes en el repositorio.**\n", " Usa `.gitignore` para excluir `/data/raw` y `/data/processed`.\n", "2. **Documentar el origen y formato de los datos** en `data/README.md`.\n", "3. **Usar rutas relativas** en el código.\n", "4. **Mantener una convención de nombres** consistente entre datasets.\n", "5. **Guardar resultados reproducibles** (como modelos o métricas) en `data/results/`.\n", "\n", "---\n", "\n", "## 8. Buenas prácticas generales\n", "\n", "1. **Usar `pyproject.toml`** como fuente principal de configuración.\n", "2. **Gestionar dependencias con `uv`** para lograr entornos reproducibles y rápidos.\n", "3. **Mantener notebooks separados** en `/notebooks/` y código reutilizable en `/src/`.\n", "4. **Guardar datos estructurados en `/data/`** y documentar su procedencia.\n", "5. **Evitar almacenar entornos (`.venv/`) o datos pesados en Git.**\n", "6. **Exportar notebooks** a formatos estáticos para documentación (`.html`, `.pdf`).\n", "7. **Nombrar notebooks secuencialmente** para reflejar el flujo de trabajo.\n", "\n", "---\n", "\n", "## 9. Archivo `pyproject.toml`\n", "\n", "El archivo **`pyproject.toml`** es el estándar moderno para la configuración de proyectos Python definido por [PEP 518](https://peps.python.org/pep-0518/) y extendido por [PEP 621](https://peps.python.org/pep-0621/).\n", "Su objetivo es centralizar la información del proyecto, las dependencias, los requisitos de construcción y la configuración de herramientas en un solo archivo, reemplazando en gran medida a `setup.py` y `requirements.txt`.\n", "\n", "---\n", "\n", "### 9.1 Estructura básica\n", "\n", "Un archivo `pyproject.toml` mínimo suele incluir las siguientes secciones:\n", "\n", "```toml\n", "[project]\n", "name = \"mi_proyecto\"\n", "version = \"0.1.0\"\n", "description = \"Descripción breve del proyecto\"\n", "authors = [{ name = \"Tu Nombre\", email = \"tu@email.com\" }]\n", "readme = \"README.md\"\n", "requires-python = \">=3.10\"\n", "dependencies = [\n", " \"numpy>=2.0.0,<3.0.0\",\n", " \"pandas>=2.2.0,<3.0.0\",\n", "]\n", "\n", "[build-system]\n", "requires = [\"setuptools>=60.0\", \"wheel\"]\n", "build-backend = \"setuptools.build_meta\"\n", "```\n", "\n", "**Explicación de secciones:**\n", "\n", "- `[project]`: contiene los metadatos del proyecto (nombre, versión, autores, descripción, dependencias).\n", "- `dependencies`: lista de dependencias que deben instalarse para usar el proyecto.\n", "- `[build-system]`: define las herramientas necesarias para construir e instalar el proyecto, por ejemplo `setuptools` y `wheel`.\n", "- `build-backend`: indica el backend de construcción que se utilizará, normalmente `setuptools.build_meta`.\n", "\n", "\n", "## 10. Conclusión\n", "\n", "Una estructura de proyecto bien diseñada es la base para la reproducibilidad, colaboración y mantenimiento en el desarrollo con Python.\n", "\n", "Entre las herramientas modernas, **`uv`** destaca por su velocidad, simplicidad y compatibilidad con los estándares más recientes.\n", "En combinación con un manejo ordenado de **notebooks**, **dependencias** y **datos**, proporciona un flujo de trabajo profesional, sostenible y escalable.\n", "\n", "> En resumen:\n", "> - Usa **`uv`** para gestionar entornos y dependencias.\n", "> - Organiza el código en `/src/` y los datos en `/data/`.\n", "> - Mantén los **notebooks** en `/notebooks/`, limpios y bien documentados.\n", "> - Versiona solo lo esencial: código, metadatos y resultados relevantes.\n", "\n", "---\n" ], "id": "9c07fe268baa3337" }, { "metadata": {}, "cell_type": "code", "outputs": [], "execution_count": null, "source": "", "id": "e77812a65db0b0d2" } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 2 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython2", "version": "2.7.6" } }, "nbformat": 4, "nbformat_minor": 5 }