Flask-SQLAlchemy与MyPy类型不兼容错误：db.Model赋值问题求解

环境版本 #

• mypy 1.1.1
• SQLAlchemy 2.0.6
• Flask-SQLAlchemy 3.0.3

遇到的错误 #

error: Incompatible types in assignment (expression has type "Type[Any]", variable has type "DefaultMeta") [assignment]
error: Variable "application.models.BaseModel" is not valid as a type [valid-type]

失效的旧方案 #

此前通过导入sqlalchemy.ext.declarative.DeclarativeMeta并标注类型的方式可解决，但包更新后失效：

from sqlalchemy.ext.declarative import DeclarativeMeta
BaseModel: DeclarativeMeta = db.Model

正确的类型声明方案 #

方案一：使用Flask-SQLAlchemy官方导出的DefaultMeta结合Type #

from typing import Type
from flask_sqlalchemy import SQLAlchemy
from flask_sqlalchemy.model import DefaultMeta

db = SQLAlchemy()
# 正确标注db.Model的类型，同时让BaseModel可作为类型使用
BaseModel: Type[DefaultMeta] = db.Model

方案二：基于SQLAlchemy 2.x的DeclarativeBase #

由于db.Model本质是SQLAlchemy 2.x DeclarativeBase的子类，也可以用以下方式：

from typing import Type
from sqlalchemy.orm import DeclarativeBase
from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()
BaseModel: Type[DeclarativeBase] = db.Model

方案三：通过TypeVar定义可复用的模型类型（解决类型有效性问题） #

如果需要在其他地方复用模型类型注解，建议定义泛型类型变量：

from typing import TypeVar
from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()
# 定义绑定到db.Model的泛型类型变量
ModelT = TypeVar("ModelT", bound=db.Model)

# 示例：使用该类型变量
def get_model_by_id(model_type: type[ModelT], model_id: int) -> ModelT:
    return model_type.query.get(model_id)

附加说明 #

• 确保Python版本支持PEP 484类型注解（3.6+），若使用3.9以下版本，需用typing.Type替代type[]
• 若仍有类型解析问题，可在文件顶部添加from __future__ import annotations延迟类型注解解析，避免提前解析时的类型冲突

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