如何用Mypy正确处理依赖外部库的动态类方法？

针对你遇到的「根据依赖是否存在动态给类添加方法，运行正常但Mypy报错」的场景，以下是几种无需频繁使用# type: ignore的规范处理方式：

方案1：使用TYPE_CHECKING与Protocol协议 #

利用typing.TYPE_CHECKING仅在类型检查阶段生效的特性，结合Protocol协议描述有SQLAlchemy时类的结构，让Mypy识别动态方法：

from typing import TYPE_CHECKING, Protocol

try:
    import sqlalchemy as sa
    SA_AVAILABLE = True
except ImportError:
    SA_AVAILABLE = False

# 仅在类型检查且SQLAlchemy可用时定义协议
if TYPE_CHECKING and SA_AVAILABLE:
    class MyClassWithSA(Protocol):
        def my_dynamic_class_func(self) -> sa.orm.Query: ...

class MyClass:
    # 类原有逻辑
    pass

if SA_AVAILABLE:
    def my_dynamic_class_func(self) -> sa.orm.Query:
        # 方法具体实现
        ...
    setattr(MyClass, "my_dynamic_class_func", my_dynamic_class_func)

# 调用时标注实例为协议类型，Mypy会认可动态方法
foo: MyClassWithSA = MyClass()
query = foo.my_dynamic_class_func()

原理：TYPE_CHECKING在运行时为False，不会触发SQLAlchemy的导入逻辑；类型检查阶段，Mypy会根据SA_AVAILABLE的静态值，认为MyClassWithSA协议有效，从而识别my_dynamic_class_func方法。

方案2：类型守卫（Type Guard）+ 条件判断 #

通过类型守卫函数告诉Mypy实例是否具备动态方法，结合运行时的条件分支：

from typing import TYPE_CHECKING, TypeGuard

try:
    import sqlalchemy as sa
    SA_AVAILABLE = True
except ImportError:
    SA_AVAILABLE = False

class MyClass:
    # 类原有逻辑
    pass

if SA_AVAILABLE:
    def my_dynamic_class_func(self) -> sa.orm.Query:
        ...
    setattr(MyClass, "my_dynamic_class_func", my_dynamic_class_func)

def has_sa_methods(obj: MyClass) -> TypeGuard[MyClass]:
    # 运行时检查方法是否存在，类型检查时Mypy会根据SA_AVAILABLE判断返回值
    return SA_AVAILABLE

# 调用方式
foo = MyClass()
if has_sa_methods(foo):
    # Mypy会在该分支内识别my_dynamic_class_func方法
    query = foo.my_dynamic_class_func()

原理：类型守卫函数has_sa_methods向Mypy声明，当返回True时，传入的MyClass实例具备动态添加的方法。运行时依赖SA_AVAILABLE的实际值判断，类型检查时Mypy会根据静态分析的SA_AVAILABLE值识别分支有效性。

方案3：条件类型存根文件 #

如果你的项目使用类型存根（.pyi），可以在存根中做条件导入，动态定义方法：

在对应模块的存根文件（如my_module.pyi）中：

from typing import Optional

try:
    import sqlalchemy as sa
except ImportError:
    sa = None  # type: ignore

class MyClass:
    if sa is not None:
        def my_dynamic_class_func(self) -> sa.orm.Query: ...

原理：类型存根仅在Mypy检查时被读取，这里尝试导入SQLAlchemy，成功则定义方法，否则跳过。Mypy会根据环境中是否存在SQLAlchemy，自动识别类的方法结构。

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