Estructura de Paquetes y Diseño de src/

El diseño src/ instala tu paquete antes de que se ejecuten las pruebas, de modo que las importaciones coincidan con la producción y los hacks accidentales de rutas "funciona en mi portátil" fallen en CI.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

# pyproject.toml (extracto)
[project]
name = "billing"
version = "0.1.0"
requires-python = ">=3.14"
 
[tool.setuptools.packages.find]
where = ["src"]
 
# src/billing/__init__.py
"""Paquete del dominio de facturación."""
 
# tests/test_invoice.py
from billing.invoices import compute_total
 
def test_compute_total() -> None:
    assert compute_total([10, 20]) == 30

Cuándo usar esto:

• Cualquier biblioteca o servicio instalable empaquetado para Docker/CI
• Equipos que experimentan errores de importación solo en CI o después de pip install
• Proyectos que separan puntos de entrada de dominio, adaptadores y CLI
• Monorepos con múltiples paquetes bajo un mismo repositorio

Ejemplo de Trabajo

# pyproject.toml
[build-system]
requires = ["setuptools>=75"]
build-backend = "setuptools.build_meta"
 
[project]
name = "orders"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = ["pydantic>=2"]
 
[project.scripts]
orders-api = "orders.cli:main"
 
[tool.setuptools.packages.find]
where = ["src"]
 
# src/orders/__init__.py
__all__ = ["domain", "adapters"]
 
# src/orders/domain/models.py
from dataclasses import dataclass
 
@dataclass(frozen=True)
class LineItem:
    sku: str
    quantity: int
    unit_price_cents: int
 
# src/orders/domain/totals.py
from orders.domain.models import LineItem
 
def order_total(items: list[LineItem]) -> int:
    return sum(i.quantity * i.unit_price_cents for i in items)
 
# src/orders/adapters/memory_repo.py
from orders.domain.models import LineItem
 
class InMemoryOrderRepo:
    def __init__(self) -> None:
        self._items: list[LineItem] = []
 
    def add(self, item: LineItem) -> None:
        self._items.append(item)
 
    def list_items(self) -> list[LineItem]:
        return list(self._items)
 
# src/orders/cli.py
from orders.adapters.memory_repo import InMemoryOrderRepo
from orders.domain.models import LineItem
from orders.domain.totals import order_total
 
def main() -> None:
    repo = InMemoryOrderRepo()
    repo.add(LineItem("ABC", 2, 1500))
    print(order_total(repo.list_items()))
 
if __name__ == "__main__":
    main()

Lo que esto demuestra:

• El código del paquete vive bajo src/orders/, las pruebas importan orders como un nombre instalado
• El dominio (models, totals) se mantiene libre de detalles de CLI y persistencia
• project.scripts expone un punto de entrada de consola estable
• requires-python documenta el límite 3.14 desde el primer día

Análisis Profundo

Cómo Funciona

• pip install -e . (o uv sync) coloca src/orders en sys.path como orders de nivel superior
• Las pruebas y las aplicaciones importan orders.domain, no src.orders.domain
• Las instalaciones editables releen los cambios de origen sin reinstalar
• La CI que solo configura PYTHONPATH=. oculta metadatos de empaquetado faltantes

Árbol Recomendado

my-service/
  pyproject.toml
  src/
    my_service/
      __init__.py
      domain/
      adapters/
      api/          # Routers de FastAPI/Flask
  tests/
    test_domain.py
  README.md

Comandos de Empaquetado

Notas de Python

# Evitar colisiones de nombres de paquetes/módulos
# MAL: src/orders.py Y paquete src/orders/
# BIEN: un directorio de paquete con submódulos
 
# API pública explícita en __init__.py
from orders.domain.totals import order_total as order_total
__all__ = ["order_total"]

Trampas Comunes

• Probar sin instalar - pytest funciona localmente porque la raíz del repositorio está en sys.path, luego falla en Docker. Solución: siempre pip install -e . en CI antes de las pruebas.
• Nombres de paquete duplicados - un archivo orders.py junto a orders/ oculta el paquete. Solución: una convención de diseño; eliminar módulos de nivel superior extraños.
• Importaciones relativas implícitas en scripts - from models import X falla cuando se ejecuta como módulo. Solución: importaciones absolutas desde la raíz del paquete (from orders.domain.models import X).
• Falta __init__.py - los paquetes de namespace pueden funcionar pero confunden las herramientas y las exportaciones explícitas. Solución: agregar __init__.py a menos que necesites deliberadamente namespaces PEP 420.
• Anidación profunda sin propósito - src/foo/bar/baz/qux con una función por archivo. Solución: aplanar hasta que una carpeta tenga un límite claro (dominio, api, adaptadores).
• Pruebas dentro de src/ - enviadas accidentalmente en wheels. Solución: mantener las pruebas en tests/ de nivel superior.

Alternativas

Preguntas Frecuentes

Relacionado

• Lista de Verificación de Decisiones de Arquitectura de Proyecto - decisión de diseño en contexto
• Arquitectura Limpia / Hexagonal - carpetas de dominio vs adaptadores
• Inyección de Dependencias y Cableado - cableado de módulos en la raíz de composición
• Configuración y Ajustes - ubicación del módulo de configuración
• Escenarios de Importación Circular - ciclos de gráficos de paquetes incorrectos

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.