如何为接受含整数'id'字段的任意SQLAlchemy ORM类的函数添加静态类型标注？

你遇到的核心问题是混淆了ORM类的实例属性和类属性的类型差异：在SQLAlchemy 2.0的ORM体系中，实例的id是Python原生int类型，而类本身的id是InstrumentedAttribute[int]（SQLAlchemy用于生成SQL表达式的工具属性）。你的函数f访问的是类属性model.id，但之前的Protocol都错误地定义了实例属性的结构，导致类型检查器无法匹配。

下面是针对问题的完整解决方案和错误分析：

正确解决方案 #

方案1：使用ClassVar定义类属性Protocol #

这个方案直接描述ORM类的结构（类属性id的类型），完全保留类型安全，且不需要修改现有ORM类：

from typing import Protocol, TypeVar, ClassVar
import sqlalchemy as sql
from sqlalchemy import orm
from sqlalchemy.orm.attributes import InstrumentedAttribute

# 定义Protocol：描述类必须包含类型为InstrumentedAttribute[int]的id类属性
class HasIntIdClass(Protocol):
    id: ClassVar[InstrumentedAttribute[int]]

# 定义ORM实例类型的TypeVar，绑定到DeclarativeBase
T = TypeVar('T', bound=orm.DeclarativeBase)

# 函数参数model是类类型，必须同时满足ORM基类和HasIntIdClass Protocol
def f(model: type[T] & HasIntIdClass) -> sql.Select[tuple[T]]:
    return sql.select(model).where(model.id > 42).order_by(model.id.desc())

# 你的原有ORM类定义
class Base(orm.DeclarativeBase):
    pass

class Foo(Base):
    __tablename__ = 'foos'
    id: orm.Mapped[int] = orm.mapped_column(primary_key=True)

print(f(Foo))  # mypy类型检查完全通过

方案2：绑定类类型的TypeVar #

这个方案更简洁，直接将TypeVar绑定到描述类结构的Protocol：

from typing import Protocol, TypeVar
import sqlalchemy as sql
from sqlalchemy import orm
from sqlalchemy.orm.attributes import InstrumentedAttribute

# 描述类结构的Protocol：类必须有id属性，类型为InstrumentedAttribute[int]
class ModelWithIntId(Protocol):
    id: InstrumentedAttribute[int]

# 定义类类型的TypeVar，绑定到ModelWithIntId
ModelType = TypeVar('ModelType', bound=ModelWithIntId)

def f(model: ModelType) -> sql.Select[tuple[orm.Instance[ModelType]]]:
    return sql.select(model).where(model.id > 42).order_by(model.id.desc())

# 原有ORM类定义
class Base(orm.DeclarativeBase):
    pass

class Foo(Base):
    __tablename__ = 'foos'
    id: orm.Mapped[int] = orm.mapped_column(primary_key=True)

print(f(Foo))  # 类型检查通过

方案3：基于操作的灵活Protocol #

如果你不想依赖SQLAlchemy的内部类型（如InstrumentedAttribute），可以定义一个只关注操作的Protocol，只要id支持比较和排序操作即可：

from typing import Protocol, TypeVar
import sqlalchemy as sql
from sqlalchemy import orm
from sqlalchemy.sql.elements import ColumnElement

# 描述id需要支持的操作：大于比较、降序排序
class SupportsIdOperations(Protocol):
    def __gt__(self, other: int) -> ColumnElement[bool]: ...
    def desc(self) -> ColumnElement[bool]: ...

# 描述类的Protocol：类有id属性且符合SupportsIdOperations
class ModelWithIntId(Protocol):
    id: SupportsIdOperations

ModelType = TypeVar('ModelType', bound=ModelWithIntId)

def f(model: ModelType) -> sql.Select[tuple[orm.Instance[ModelType]]]:
    return sql.select(model).where(model.id > 42).order_by(model.id.desc())

# 原有ORM类定义
class Base(orm.DeclarativeBase):
    pass

class Foo(Base):
    __tablename__ = 'foos'
    id: orm.Mapped[int] = orm.mapped_column(primary_key=True)

print(f(Foo))  # 类型检查通过

你之前尝试的错误分析 #

1. id: int：Protocol声明的是实例的id为int，但函数中访问的是类的id（InstrumentedAttribute[int]）。mypy无法识别SQLAlchemy的表达式逻辑，误以为是普通Python比较（返回bool），导致类型不匹配错误。
2. id: orm.Mapped[int]：Mapped[int]是给类型检查器看的字段注解，不是类属性的实际类型。实例的id是原生int，不符合Mapped[int]，因此TypeVar无法绑定到Foo。
3. id: orm.attributes.InstrumentedAttribute[int]：未使用ClassVar标记，mypy认为这是实例属性，但实例的id是int而非InstrumentedAttribute[int]，因此Foo实例不符合Protocol，TypeVar无法绑定。

注意事项 #

• 确保使用SQLAlchemy 2.0+版本，该版本内置了完整的类型注解支持，无需额外安装sqlalchemy-stubs。
• 所有方案都基于Python的**结构子类型（Structural Subtyping）**实现，完全不需要修改现有ORM类。

内容来源于stack exchange