Estructura de un proyecto Python
Mapa conceptual
Módulo vs paquete
- Módulo: un archivo .py con código.
- Paquete: una carpeta con un __init__.py que agrupa módulos; se importa con puntos (paquete.submodulo).
Un layout típico
El layout src/ pone el código dentro de una carpeta homónima bajo src/, lo que evita importar accidentalmente el paquete desde la raíz. Encima: un archivo de configuración, pruebas en tests/, documentación, y dependencias declaradas.
| Elemento | Para qué | Ejemplo |
|---|---|---|
| src/mi_proyecto/ | el código real | main.py, utils.py |
| tests/ | pruebas separadas | test_unidades.py |
| pyproject.toml | config de empaquetado | nombre, versión, dependencias |
| requirements.txt | dependencias fijadas | numpy==1.26.0 |
| README.md | portada y uso | cómo instalar y ejecutar |
El archivo __init__.py
Marca una carpeta como paquete. Puede estar vacío o exponer una API concreta: al hacer «from paquete import x» define qué se considera parte pública, ocultando el resto.
Dependencias declaradas
Nunca asumas librerías «instaladas globalmente»: decláralas. requirements.txt o pyproject.toml fijan qué versión de cada paquete necesitas. Eso es la diferencia entre un proyecto que otro puede correr y uno que solo corre en tu máquina.
Punto de entrada
Un proyecto define cómo se arranca: un main.py, o un entry point declarado en la configuración que permite lanzar tu herramienta como comando. Esto vuelve reutilizable lo que era un guion suelto.
¿Qué diferencia hay entre un módulo y un paquete?
Entornos aislados
Cada proyecto debería vivir en su propio entorno virtual (venv): un espacio con su intérprete y sus paquetes, para que las dependencias de un proyecto no choquen con las de otro. Se crea, se activa y se instalan paquetes ahí dentro.
Pruebas separadas
Los tests van en su propia carpeta, no mezclados con el código de producción. Una estructura clara permite correr todas las pruebas de un golpe y detectar regresiones cuando mueves algo.
Un proyecto bien estructurado mantiene las pruebas dentro de los mismos archivos de código para facilitar su lectura.
Errores frecuentes
- Poner todo en un solo script que crece hasta ser ilegible.
- Importar desde la raíz del proyecto sin instalarlo: funciona en tu máquina y rompe en la de nadie.
- No fijar versiones: el proyecto se descompone cuando una librería cambia.
De guion a proyecto
El salto de calidad ocurre cuando dejas de «ejecutar un archivo» y empiezas a «instalar un paquete». Puedes compartirlo, probarlo y versionarlo. La estructura hace posible todo lo demás.
Ordena los pasos de un proyecto nuevo:
Paso 1
Paso 2
Paso 3
Paso 4
Python Packaging
Guía oficial para empaquetar proyectos.
Revisa un proyecto Python que hayas hecho. Propón una estructura con src/, tests/ y un archivo de dependencias. ¿Qué paso de los de la lección falta en tu proyecto actual?
Python: Classes
Tutorial oficial de clases en Python 3.