SQLAlchemy多对多关系下类引用的循环导入问题求解

问题背景 #

在Python项目中使用SQLAlchemy处理多对多（M2M）关系时，我创建了Left、Right和AssociationTable三张表，但尝试用类引用替代relationship中的字符串引用时，始终无法解决循环导入和类型检查的冲突问题。

当前可行的字符串引用实现 #

目前使用字符串引用定义关系可以正常运行，代码结构如下：

Left类模块 #

if TYPE_CHECKING:
  from ... import Right

class Left(Base):
    __tablename__ = "LEFT_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    brand: Mapped[str] = mapped_column(String(255), nullable=True)

    left_right_association: Mapped[InstrumentedList["AssociationTable"]] = relationship(
        "AssociationTable", 
        back_populates="left"
    )

    rights: Mapped[InstrumentedList["Right"]] = relationship(
        "Right", 
        secondary="ASSOCIATION_TABLE", 
        back_populates="lefts"
    )

Right类模块 #

if TYPE_CHECKING:
  from ... import Left

class Right(Base):
    __tablename__ = "RIGHT_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    version: Mapped[str] = mapped_column(String(255), nullable=True)

    left_right_association: Mapped[InstrumentedList["AssociationTable"]] = relationship(
        "AssociationTable", 
        back_populates="right"
    )

    lefts: Mapped[InstrumentedList["Left"]] = relationship(
        "Left", 
        secondary="ASSOCIATION_TABLE", 
        back_populates="rights"
    )

AssociationTable类模块 #

class AssociationTable(Base):
    __tablename__ = "ASSOCIATION_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    left_id: Mapped[int] = mapped_column(ForeignKey("LEFT_TABLE.id"), nullable=False)
    right_id: Mapped[int] = mapped_column(ForeignKey("RIGHT_TABLE.id"), nullable=False)

    left = relationship("Left", back_populates="left_right_association")
    right = relationship("Right", back_populates="left_right_association")

类引用尝试后的错误 #

当将relationship中的字符串引用改为类引用（例如relationship(Left, secondary="ASSOCIATION_TABLE", back_populates="rights")）时，会触发两类错误：

• 使用TYPE_CHECKING导入：运行时触发NameError: name 'Left' is not defined，因为TYPE_CHECKING块内的导入仅用于类型检查，运行时不执行。
• 直接导入不使用TYPE_CHECKING：触发循环导入错误cannot import name '' from partially initialized module '' (most likely due to a circular import)，因为Left和Right模块互相依赖。

可行的类引用方案 #

想要使用类引用同时避免循环导入和类型错误，有两种可靠的实现方式：

1. 延迟导入+运行时关系更新 #

核心思路是先定义类和关系结构，等所有类初始化完成后再导入关联类，并更新relationship的目标类参数：

Left类模块修改后

from sqlalchemy.orm import Mapped, mapped_column, relationship, InstrumentedList
from .base import Base

class Left(Base):
    __tablename__ = "LEFT_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    brand: Mapped[str] = mapped_column(String(255), nullable=True)

    # 先以无目标类的方式定义关系
    rights: Mapped[InstrumentedList["Right"]] = relationship(
        secondary="ASSOCIATION_TABLE", 
        back_populates="lefts"
    )
    left_right_association: Mapped[InstrumentedList["AssociationTable"]] = relationship(
        back_populates="left"
    )

# 类定义完成后再导入关联类，更新关系的目标类
from .right import Right
from .association import AssociationTable

Left.rights.property.argument = Right
Left.left_right_association.property.argument = AssociationTable

Right类模块修改后

from sqlalchemy.orm import Mapped, mapped_column, relationship, InstrumentedList
from .base import Base

class Right(Base):
    __tablename__ = "RIGHT_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    version: Mapped[str] = mapped_column(String(255), nullable=True)

    lefts: Mapped[InstrumentedList["Left"]] = relationship(
        secondary="ASSOCIATION_TABLE", 
        back_populates="rights"
    )
    left_right_association: Mapped[InstrumentedList["AssociationTable"]] = relationship(
        back_populates="right"
    )

from .left import Left
from .association import AssociationTable

Right.lefts.property.argument = Left
Right.left_right_association.property.argument = AssociationTable

AssociationTable类模块修改后

from sqlalchemy.orm import Mapped, mapped_column, relationship
from .base import Base

class AssociationTable(Base):
    __tablename__ = "ASSOCIATION_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    left_id: Mapped[int] = mapped_column(ForeignKey("LEFT_TABLE.id"), nullable=False)
    right_id: Mapped[int] = mapped_column(ForeignKey("RIGHT_TABLE.id"), nullable=False)

    left = relationship(back_populates="left_right_association")
    right = relationship(back_populates="left_right_association")

from .left import Left
from .right import Right

AssociationTable.left.property.argument = Left
AssociationTable.right.property.argument = Right

这种方式彻底避免了类定义阶段的循环导入，同时实现了类引用的目标。

2. 完整类名字符串+TYPE_CHECKING类型提示 #

如果希望保持代码简洁，可以使用带完整模块路径的类名字符串定义relationship，同时在TYPE_CHECKING块导入类用于类型提示：

Left类模块示例

from sqlalchemy.orm import Mapped, mapped_column, relationship, InstrumentedList
from .base import Base
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .right import Right
    from .association import AssociationTable

class Left(Base):
    __tablename__ = "LEFT_TABLE"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    brand: Mapped[str] = mapped_column(String(255), nullable=True)

    left_right_association: Mapped[InstrumentedList[AssociationTable]] = relationship(
        "myapp.models.association.AssociationTable",  # 替换为你的实际模块路径
        back_populates="left"
    )

    rights: Mapped[InstrumentedList[Right]] = relationship(
        "myapp.models.right.Right",  # 替换为你的实际模块路径
        secondary="ASSOCIATION_TABLE",
        back_populates="lefts"
    )

这种方式下，类型检查工具（如mypy）会通过TYPE_CHECKING块的导入识别类型，而运行时SQLAlchemy会通过完整类名字符串找到对应的模型类，既满足类型检查需求，又避免了循环导入。

关于@declared_attr等方案的说明 #

@declared_attr用于动态定义属性，但如果仍然在类定义阶段导入关联类，依然会触发循环导入。只有将导入操作延迟到类初始化完成后，或使用字符串引用（含完整类名），才能真正解决循环依赖问题。

内容的提问来源于stack exchange，提问作者Marco Debernardi