Escenarios de Importación Circular

Las importaciones circulares ocurren cuando el módulo A carga el módulo B mientras B aún se está inicializando e intenta importar A. Python genera ImportError o deja los nombres como marcadores de posición semivacíos tipo None.

Receta

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

# Diagnosticar
python -c "import mypackage"
python -X importtime -c "import mypackage" 2>&1 | head
 
# Solución estructural: extraer tipos compartidos
# mypackage/domain/types.py  <- ambos lados importan este módulo hoja

Cuándo usar esto:

• ImportError: cannot import name 'X' from partially initialized module
• Los tipos funcionan en tiempo de ejecución pero mypy/pyright informan importaciones circulares
• La adición de un nuevo módulo rompe el orden de inicio que "solía funcionar"
• Las importaciones perezosas se multiplican como mecanismo de adaptación

Ejemplo de Trabajo

# Diseño roto:
# orders/models.py importa billing/invoices.py
# billing/invoices.py importa orders/models.py
 
# Paso 1: reproducir
# $ python -c "import orders.models"
# ImportError: cannot import name 'Order' from partially initialized module 'orders.models'
 
# Paso 2: extraer tipos hoja
# shared/types.py
from dataclasses import dataclass
 
@dataclass(frozen=True)
class OrderId:
    value: str
 
@dataclass(frozen=True)
class Money:
    cents: int
 
# orders/models.py
from shared.types import Money, OrderId
 
@dataclass
class Order:
    id: OrderId
    total: Money
 
# billing/invoices.py
from shared.types import Money, OrderId
from orders.models import Order
 
def invoice_for(order: Order) -> Money:
    return order.total

# Puente temporal (documentar ticket para eliminar)
def get_order(order_id: str):
    from orders.models import Order  # importación perezosa dentro de la función
    return Order(OrderId(order_id), Money(0))

Lo que esto demuestra:

• Los tipos de valor compartidos se mueven a un módulo hoja que ambos lados importan.
• Los tipos de dominio importan hacia adentro; facturación importa Order solo después de que orders.models termine de cargarse.
• La importación perezosa desbloquea emergencias pero no reemplaza la estructura.

Análisis Profundo

Cómo Funciona

• La importación se ejecuta de arriba a abajo una vez por módulo; los módulos incompletos residen en sys.modules.
• El acceso a atributos durante la inicialización parcial falla o ve nombres faltantes.
• Las importaciones solo para verificación de tipos (if TYPE_CHECKING:) rompen ciclos para herramientas estáticas sin costo en tiempo de ejecución.
• Las reexportaciones del paquete __init__.py pueden crear accidentalmente ciclos entre subpaquetes.

Formas Comunes de Ciclos

Notas de Python

from typing import TYPE_CHECKING
 
if TYPE_CHECKING:
    from orders.models import Order
 
def describe(order: "Order") -> str:
    return "order"

Trampas

• Solo anotaciones de cadena - las comillas ocultan ciclos sin arreglar la arquitectura. Solución: extraer tipos o invertir la dependencia.
• __init__.py "gordo" - importar un subpaquete ejecuta todo el árbol. Solución: __init__.py vacío o mínimo; importaciones explícitas de submódulos.
• Efectos secundarios en la importación - la conexión a la base de datos al importar empeora la depuración de ciclos. Solución: mover IO a main/hooks de inicio.
• La recopilación de pytest importa todo - los ciclos se ocultan hasta que se ejecuta toda la suite. Solución: prueba de humo import package en CI.
• Renombrar sin invertir aristas - el ciclo regresa con nuevos nombres de módulo. Solución: regla de dependencia: el dominio nunca importa adaptadores.
• Importaciones circulares de conftest de prueba - conftest.py importa la aplicación que importa ayudantes de prueba. Solución: fixtures en tests/support dedicado sin importar módulos de aplicación mutuamente.

Alternativas

Preguntas Frecuentes

Relacionado

• Decisiones de Refactorización - soluciones de ciclos clasificadas
• Estructura de src y Paquetes - higiene de paquetes
• Arquitectura Limpia / Hexagonal - dirección de dependencia
• Herramientas de Depuración - inspeccionar el estado de importación
• Conflictos de Dependencia y Entorno - paquete incorrecto en la ruta imita ciclos

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