Módulos, Importaciones y Paquetes

Python organiza el código en módulos (archivos) y paquetes (directorios). El sistema de importación carga el código una vez por proceso, lo almacena en caché en sys.modules y expone los nombres a través del espacio de nombres de importación.

Receta

# myapp/services/users.py
from myapp.models.user import User
from myapp.utils.text import slugify
 
def list_active() -> list[User]:
    return [u for u in User.all() if u.active]

Cuándo usar esto:

• Para dividir un script en crecimiento en paquetes mantenibles
• Para publicar bibliotecas reutilizables en PyPI
• Para ejecutar puntos de entrada de CLI a través de python -m
• Para cargar perezosamente dependencias opcionales pesadas

Ejemplo de Trabajo

# myapp/__init__.py
__version__ = "1.0.0"
 
# myapp/config.py
from dataclasses import dataclass
import os
 
@dataclass(frozen=True)
class Settings:
    debug: bool
    database_url: str
 
def load_settings() -> Settings:
    return Settings(
        debug=os.getenv("DEBUG", "0") == "1",
        database_url=os.getenv("DATABASE_URL", "sqlite:///local.db"),
    )
 
# myapp/main.py
from myapp.config import load_settings
 
def main() -> None:
    settings = load_settings()
    print(f"debug={settings.debug} db={settings.database_url}")
 
if __name__ == "__main__":
    main()

Ejecuta con: python -m myapp.main desde el directorio padre en PYTHONPATH.

Lo que esto demuestra:

• El archivo __init__.py del paquete puede exponer metadatos de versión
• Las importaciones absolutas (from myapp.config import ...) permanecen claras a medida que el paquete crece
• Guardia de entrada if __name__ == "__main__" para módulos ejecutables
• El modificador -m establece __package__ correctamente para importaciones relativas dentro del paquete

Profundización

Cómo Funciona

• Ruta de búsqueda de módulos - sys.path lista directorios; PYTHONPATH y los site-packages de venv lo extienden.
• Caché de módulos - La primera importación ejecuta el cuerpo del módulo; las importaciones posteriores reutilizan sys.modules.
• Importaciones relativas - from .config import load_settings requieren contexto de paquete (-m o importación de paquete).
• Paquetes de espacio de nombres - Los directorios PEP 420 sin __init__.py pueden participar en un espacio de nombres dividido.
• __all__ - Documenta los nombres públicos para from module import * (raro en el código de la aplicación).

Recomendación de Diseño

project/
  src/
    myapp/
      __init__.py
      main.py
      config.py
  pyproject.toml

Instala en modo editable (uv pip install -e .) para que import myapp se resuelva durante el desarrollo.

Notas de Python

import importlib
 
def lazy_import(module: str):
    return importlib.import_module(module)
 
# El bloque TYPE_CHECKING evita importaciones circulares en tiempo de ejecución
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from myapp.models import User

Trampas Comunes

• Importaciones circulares - a importa b mientras b importa a. Solución: Mueve tipos compartidos a un tercer módulo o usa importación perezosa dentro de funciones.
• Ejecutar archivo directamente - python myapp/main.py rompe las importaciones relativas. Solución: python -m myapp.main.
• Sobrescribir la biblioteca estándar - Nombrar un archivo json.py rompe import json. Solución: Evita nombres de la biblioteca estándar para módulos.
• Efectos secundarios en la importación - Las conexiones de base de datos a nivel de módulo ralentizan las pruebas. Solución: Funciones de fábrica llamadas desde main.
• Importaciones de estrella - from utils import * contamina el espacio de nombres. Solución: Importa símbolos explícitos.

Alternativas

Preguntas Frecuentes

Relacionado

• Inicio Rápido de Entornos Virtuales - dependencias aisladas
• Diseño src - diseño de paquetes de producción
• Explicación de pyproject.toml - metadatos del paquete
• Archivos y E/S - lectura de archivos de configuración

Versiones de la Pila: 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+.