SQLAlchemy字符串关系引发flake8与mypy未定义名称报错

方案1：用TYPE_CHECKING条件导入（推荐） #

Python的typing.TYPE_CHECKING常量在运行时为False，仅在类型检查阶段生效。利用这个特性，你可以在不触发循环引用的前提下，让类型检查工具识别关联类：

在order.py中：

from typing import TYPE_CHECKING
from sqlalchemy import Column, Integer
from sqlalchemy.orm import relationship
from database import Base

if TYPE_CHECKING:
    # 仅类型检查时导入，运行时不会执行，避免循环引用
    from .item import Item

class Order(Base):
    __tablename__ = "orders"
    id = Column(Integer, primary_key=True)
    items = relationship("Item", back_populates="order")

在item.py中同理：

from typing import TYPE_CHECKING
from sqlalchemy import Column, Integer, ForeignKey
from sqlalchemy.orm import relationship
from database import Base

if TYPE_CHECKING:
    from .order import Order

class Item(Base):
    __tablename__ = "items"
    id = Column(Integer, primary_key=True)
    order_id = Column(Integer, ForeignKey("orders.id"))
    order = relationship("Order", back_populates="items")

这样mypy能准确识别关联类的类型，flake8也不会因为未导入而报F821错误。

方案2：类型注解使用字符串形式 #

如果不需要显式导入类，仅需让类型检查工具识别类型，可以直接用字符串形式标注类型：

class Order(Base):
    __tablename__ = "orders"
    id = Column(Integer, primary_key=True)
    # 用字符串"Item"标注类型，无需导入
    items: list["Item"] = relationship("Item", back_populates="order")

这种方式适合仅需要类型提示的场景，同样能避免类型检查工具的报错。

方案3：局部忽略flake8的F821（不推荐，仅应急） #

如果上述方案都不适用，可以针对单个行添加注释忽略F821错误，避免全局关闭规则：

items = relationship("Item", back_populates="order")  # noqa: F821

注意仅在必要时使用，优先保证代码的类型完整性。

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