如何为SQLAlchemy模型添加正确类型提示？解决字段类型误判问题

当使用SQLAlchemy声明式模型时，直接定义Column会让类型检查工具把实例的字段识别为Column类型而非实际数据类型，以下是几种正确的类型提示方案：

方案一：使用SQLAlchemy 2.0+的Mapped和mapped_column（推荐） #

这是SQLAlchemy官方推荐的现代写法，能直接让类型检查工具识别实例字段的正确类型：

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

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    name: Mapped[str] = mapped_column(String)

def find_user(name: str) -> User:
    # 数据库查询逻辑
    return user

方案二：为Column添加实例类型注解（兼容旧版本） #

如果使用SQLAlchemy 1.x版本，可以通过以下方式告诉类型检查工具实例上的属性类型：

方式A：使用Annotated（Python 3.9+） #

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, String
from typing import Annotated

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    name: Annotated[str, Column(String)] = Column(String)

def find_user(name: str) -> User:
    return user

方式B：直接声明实例属性类型 #

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

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    name = Column(String)
    # 显式声明实例属性的实际类型
    name: str

def find_user(name: str) -> User:
    return user

方案三：使用类型存根文件 #

如果不想修改模型代码，可以为模型创建.pyi类型存根文件，在其中声明实例的字段类型：

user.pyi文件内容：

from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
    name: str

类型检查工具会读取存根文件中的类型定义，忽略实际代码中的Column类型。

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