Paquetes y entornos
Un proyecto en Python no empieza con un archivo .py: empieza con la decisión de dónde vive el código y cómo se encuentra. Esa decisión produce dos bugs clásicos —importar lo que no es, y no importar lo que debería— y un tercero, más caro: que el programa funcione en tu máquina porque el paquete está instalado de una forma que nadie más tiene.
En una línea
Sección titulada «En una línea»Un paquete es una carpeta con un __init__.py; un proyecto es un pyproject.toml que dice cómo se instala.
La estructura que evita el bug
Sección titulada «La estructura que evita el bug»mi-proyecto/├── pyproject.toml├── src/│ └── mi_paquete/│ ├── __init__.py│ ├── modelos.py│ └── servicios.py└── tests/ └── test_modelos.pyEl src/ no es decorativo. Sin él, import mi_paquete funciona desde la raíz del proyecto aunque el paquete no esté instalado, porque Python añade el directorio actual a sys.path. El código pasa las pruebas y falla al empaquetar, porque la distribución no incluye lo que el import encontraba por accidente.
Con src/, el import falla hasta que instalas el paquete (pip install -e .), y esa instalación es la misma que hará cualquiera.
El entorno virtual y la instalación, en cada sistema (y con uv, que hace lo mismo más rápido):
# Linux / macOSpython -m venv .venv.venv/bin/pip install -e ".[dev]"# Windows (PowerShell)python -m venv .venv.venv\Scripts\pip install -e ".[dev]"# con uv (cualquier sistema)uv venvuv pip install -e ".[dev]"uv lock # escribe uv.lock con las versiones exactasuv sync --extra dev # instala exactamente lo que dice uv.lock, incluido el extra devComprobado con uv 0.13 sobre este pyproject.toml: uv venv crea .venv y elige el Python disponible; uv lock resolvió 24 paquetes y escribió uv.lock. Ojo con uv sync a secas: instala sólo las dependencias de [project] y desinstala lo que sobre, así que quita pytest y ruff si viven en el extra dev; con --extra dev se quedan. uv sync --frozen instala sin tocar uv.lock.
El pyproject.toml
Sección titulada «El pyproject.toml»[project]name = "mi-paquete"version = "0.1.0"requires-python = ">=3.11"dependencies = ["httpx>=0.27", "pydantic>=2.6"]
[project.optional-dependencies]dev = ["pytest>=8", "ruff>=0.5", "mypy>=1.10"]
[project.scripts]mi-cli = "mi_paquete.cli:main"
[build-system]requires = ["hatchling"]build-backend = "hatchling.build"Cuatro bloques y cada uno responde una pregunta: qué es el paquete, con qué se ejecuta, qué necesita en producción, qué necesita para desarrollar y qué comando instala.
El coste de arrancar
Sección titulada «El coste de arrancar»| Módulo | Primera importación |
|---|---|
decimal |
5.9 ms |
json |
11.5 ms |
logging |
18.8 ms |
dataclasses |
22.1 ms |
python mediciones/07-01-05-produccion.py
Cada import pesa, y se paga en cada arranque de proceso: en una CLI, en cada worker de un servicio, en cada tarea de un ProcessPoolExecutor. Un servicio que importa veinte módulos pesados tarda décimas de segundo en estar listo, y eso multiplicado por cien workers son segundos de despliegue.
La herramienta es python -X importtime -c "import mi_paquete", que imprime el árbol de imports con su coste. Lo que se hace con eso: mover los imports caros dentro de la función que los usa, cuando esa función no siempre se llama.
La trampa
Sección titulada «La trampa»Cuándo no aplica
Sección titulada «Cuándo no aplica»- Un script de un archivo. Un venv y ya.
- Un notebook de análisis. Las dependencias las gestiona el entorno del notebook.
- Un prototipo de un día. Pero si el prototipo va a crecer, empezar con
src/cuesta cinco minutos.
Ejercicio
Sección titulada «Ejercicio»Un compañero dice que su paquete «funciona en local pero falla al instalarlo con pip install .». El error es ModuleNotFoundError: No module named 'utils'. Explica la causa más probable y cómo el diseño con src/ la habría evitado.
Solución
La causa más probable es que utils.py está fuera del paquete (en la raíz del proyecto) y el código lo importa como si fuera un módulo hermano. En local funciona porque el directorio actual está en sys.path; al instalar, sólo se copia la carpeta del paquete y utils.py no viaja.
Otra causa posible: el paquete no incluye subpaquetes porque el backend de build no los descubre sin configuración (packages = ["mi_paquete"] en hatchling, o un __init__.py que falta en un subdirectorio).
El diseño con src/ no arregla el import mal puesto, pero lo hace visible: al no estar el directorio actual en la ruta de búsqueda del paquete instalable, el import falla desde el primer día y no en el despliegue.
La comprobación definitiva: crear un venv limpio, pip install ., y ejecutar los tests ahí. Es el único entorno que se parece al de producción.
Referencias
Sección titulada «Referencias»- Ramalho, L. Fluent Python, 2ª ed. Capítulo 2.
- Lott, S. F. Modern Python Cookbook, 3ª ed. Capítulo 16: dependencias y entornos.
- Mediciones:
mediciones/07-01-05-produccion.py.
Capítulos relacionados
Sección titulada «Capítulos relacionados»- 02 · Configuración tipada: lo que el paquete lee al arrancar.
- 09 · Empaquetado: de
pyproject.tomla rueda publicada. - 08 · CI: el entorno limpio automatizado.