如何让mypy在查找对象时支持多导入路径检测？

我正在开发一个项目，其中创建了一个包装第三方模块（含多个子模块）的模块。该包装模块会自行处理部分功能，必要时也会调用第三方模块的函数。我希望找到方法帮助静态分析工具（尤其是mypy）尽可能理解这一场景。

我找到的一个部分解决方案是在包装模块的__init__.py中添加如下代码：

# wrapper_module.__init__

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from original_module import submodule_a
    from original_module import submodule_b
    # ...

    from wrapper_module import submodule_a
    from wrapper_module import submodule_b
    # ...


# Actual code doing the imports dynamically

这在一定程度上能让部分导入被正确识别，但目前的问题是，mypy只会在original_module中查找对象（这符合逻辑，因为没有规则说明同名导入的交互方式，但奇怪的是它会采用第一个导入，而Python中通常第二个会覆盖第一个）。

有趣的是，PyCharm能完美理解我的需求：当其他模块导入wrapper_module后，使用wrapper_module.submodule_a.some_function()时，它会先在wrapper_module中查找some_function，找不到再去original_module中查找（比如“转到实现”功能表现完美）。

请问是否有办法让mypy实现这一功能？mypy是否支持通过正确语法引导来查找动态导入对象的多路径？

1. 利用模块级__getattr__配合类型注解 #

mypy对模块级别的__getattr__有良好支持，你可以在wrapper_module/__init__.py中定义这个函数，并添加精确的类型逻辑，让mypy明确属性的查找优先级：

from typing import TYPE_CHECKING, Any
import original_module

if TYPE_CHECKING:
    from . import submodule_a, submodule_b

def __getattr__(name: str) -> Any:
    # 运行时逻辑：优先取当前模块的子模块，取不到再从原模块获取
    try:
        return globals()[name]
    except KeyError:
        return getattr(original_module, name)

# 显式导出所有需要暴露的成员，让mypy优先识别包装的子模块
__all__ = ["submodule_a", "submodule_b"] + [attr for attr in dir(original_module) if not attr.startswith("_")]

2. 为包装子模块编写类型存根文件 #

如果你的包装子模块有自定义逻辑，可以为每个子模块单独创建.pyi类型存根，明确标注自定义内容，未覆盖的部分自动沿用原模块的类型：
比如wrapper_module/submodule_a.pyi：

# 先导入原模块子模块的所有类型，再覆盖自定义函数
from original_module.submodule_a import *

# 自定义功能的类型注解
def some_custom_function(x: int) -> str: ...

这样mypy会优先使用存根中定义的自定义内容，未声明的成员则自动匹配原模块的类型定义。

3. 临时调整TYPE_CHECKING块的导入顺序（不推荐） #

虽然mypy会按导入顺序优先识别第一个同名对象，但你可以把包装模块的子模块导入放在原模块之前：

if TYPE_CHECKING:
    from wrapper_module import submodule_a, submodule_b
    from original_module import submodule_a as original_submodule_a, submodule_b as original_submodule_b

这种方式容易造成代码混淆，仅适合临时快速验证，不建议长期使用。

核心逻辑说明 #

mypy是静态分析工具，不会像PyCharm那样做运行时路径的动态推断，必须通过明确的类型约定告诉它属性的查找优先级。模块级__getattr__是官方推荐的处理动态模块属性的方案，能同时兼顾运行时逻辑和静态分析的准确性。

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