如何为SQLAlchemy模型中的列添加正确的类型注解？

问题根源 #

直接用str/int等原生类型注解列属性时，Pylance会检测到Column[Text]（或对应类型）与声明的原生类型不兼容，从而抛出警告——因为类定义时赋值的是Column实例，而不是原生类型值。

推荐方案：SQLAlchemy 2.0+ 官方类型注解方式 #

SQLAlchemy 2.0及以上版本提供了Mapped和mapped_column专门适配类型检查器（包括Pyright/Pylance），完全解决类型不匹配问题。

代码示例：

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

class Base(DeclarativeBase):
    pass

class MyModel(Base):
    __tablename__ = 'mytable'

    id: Mapped[str] = mapped_column(String(32), primary_key=True)
    test: Mapped[int] = mapped_column(Integer, index=True)
    is_valid: Mapped[bool] = mapped_column(Boolean, default=True)

• Mapped[T]声明属性对应的Python原生类型
• mapped_column()替代原Column()，自动关联类型信息，Pylance能正确识别类定义时的Column实例与实例访问时的原生类型映射。

兼容旧版SQLAlchemy（<2.0）的方案 #

方案1：显式指定Column泛型类型

直接将注解类型设为Column[T]，避免赋值类型不匹配警告，但访问实例属性时需注意类型提示：

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

Base = declarative_base()

class MyModel(Base):
    __tablename__: str = 'mytable'

    id: Column[str] = Column(String(32), primary_key=True)
    test: Column[int] = Column(Integer, index=True)
    is_valid: Column[bool] = Column(Boolean, default=True)

访问属性时可通过类型断言转换为原生类型：

from typing import cast

instance = MyModel()
user_id = cast(str, instance.id)

方案2：精准抑制警告

若不想调整代码结构，可在列定义后添加注释抑制Pylance的赋值类型不匹配警告：

class MyModel(Base):
    __tablename__: str = 'mytable'

    id: str = Column(String(32), primary_key=True)  # type: ignore[assignment]
    test: int = Column(Integer, index=True)  # type: ignore[assignment]
    is_valid: bool = Column(Boolean, default=True)  # type: ignore[assignment]

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