使用命名空间包与同名子文件夹时Mypy无法检测类型不匹配

问题根源 #

使用--namespace-packages参数时，Mypy无法正确识别命名空间包的类型提示，核心原因有两个：

• 未将源码根目录（src）加入Mypy的模块搜索路径，导致命名空间包的导入解析异常
• 命名空间包缺少py.typed标记，被Mypy判定为无类型包，所有相关类型被默认推断为Any

解决方案 #

1. 执行Mypy时指定Python路径 #

修改Mypy命令，添加--pythonpath src参数，确保Mypy能从src目录开始正确解析命名空间包：

mypy src --check-untyped-defs --namespace-packages --pythonpath src

2. 给命名空间包添加py.typed标记 #

在src/mb2目录下创建一个空的py.typed文件，这是PEP 561规定的标准方式，用于告诉Mypy该包提供类型提示：

src
  mb2
    py.typed  # 新增此空文件
    base.py
    steps
      ...

3. （可选）用配置文件简化命令 #

创建pyproject.toml文件，把Mypy配置写入其中，避免每次命令行输入大量参数：

[tool.mypy]
pythonpath = ["src"]
namespace_packages = true
check_untyped_defs = true

之后只需运行mypy src即可完成类型检查。

验证效果 #

完成上述配置后重新运行Mypy，应该能检测到test.py中get_resource_costs(cfg)的类型不匹配问题，同时reveal_type(cfg)和reveal_type(get_resource_costs)会显示正确的具体类型，而非Any。

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