Saltearse al contenido

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.

Un paquete es una carpeta con un __init__.py; un proyecto es un pyproject.toml que dice cómo se instala.

mi-proyecto/
├── pyproject.toml
├── src/
│ └── mi_paquete/
│ ├── __init__.py
│ ├── modelos.py
│ └── servicios.py
└── tests/
└── test_modelos.py

El 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):

Ventana de terminal
# Linux / macOS
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
Ventana de terminal
# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
Ventana de terminal
# con uv (cualquier sistema)
uv venv
uv pip install -e ".[dev]"
uv lock # escribe uv.lock con las versiones exactas
[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.

Importar un módulo de la biblioteca estándar (coste acumulado)
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.

  • 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.

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.

  • 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.
  • 02 · Configuración tipada: lo que el paquete lee al arrancar.
  • 09 · Empaquetado: de pyproject.toml a rueda publicada.
  • 08 · CI: el entorno limpio automatizado.