Pyright转换SQLAlchemy Column(int)为int时提示类型不兼容报错

• SQLAlchemy 2.0之前的版本，以及未使用官方推荐类型写法的2.0版本中，Column对象在类定义层面的静态类型标注始终为Column[T]类型，静态检查器无法自动识别ORM映射逻辑——即**类层面定义的Column对象，在实例访问时会自动转换为对应Python原生类型（如int、str）**的隐式逻辑，因此会直接判定类型不兼容。
• Pyright的类型检查规则严格度高于默认配置的mypy，不会对ORM场景下的这类隐式类型转换做特殊放行，只要代码中出现将类层面的Column对象赋值给声明为原生类型（如int）的参数、属性的场景，就会抛出你看到的报错。
• 额外触发场景：如果手动给ORM模型编写了带类型标注的__init__方法，或者混用了dataclass与SQLAlchemy模型但未做类型适配，会进一步提升这类报错的出现概率。

方案1：使用SQLAlchemy 2.0官方推荐的Mapped写法（优先选择，零注释兼容） #

SQLAlchemy 2.0专门新增了Mapped泛型和mapped_column构造方法解决静态类型检查问题，写法调整后Pyright可以完全正确推导类型，不需要加任何忽略注释，自动补全也能正常工作。
示例代码：

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import Integer, String

class Base(DeclarativeBase):
    pass

class DemoModel(Base):
    __tablename__ = "demo_table"
    # 实例访问id时，Pyright会正确识别类型为int，不会报Column不兼容错误
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    username: Mapped[str] = mapped_column(String(32))

*说明：mapped_column和旧版Column的参数完全兼容，老项目迁移的替换成本极低。

方案2：SQLAlchemy 1.4及以下老版本适配 #

如果暂时无法升级到SQLAlchemy 2.0，可通过两步解决：

1. 安装官方维护的类型桩包：
   pip install sqlalchemy2-stubs
2. 定义列时显式声明泛型类型，让Pyright能识别映射后的原生类型：

from sqlalchemy import Column, Integer
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class DemoModel(Base):
    __tablename__ = "demo_table"
    id: Column[int] = Column(Integer, primary_key=True)

方案3：临时忽略报错（仅适合临时兼容，不推荐长期使用） #

如果暂时无法调整模型写法，不要使用无差别的# type: ignore，要精准指定忽略的错误码，避免掩盖真实的类型错误：

id = Column(Integer, primary_key=True)  # pyright: ignore[reportGeneralTypeIssues]

避坑提示：不要为了消除这类报错直接全局关闭Pyright的类型检查，也不要给整段代码加无差别的忽略注释，后续出现真实的参数类型错误时检查器不会报警，容易埋下线上bug。

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