Mypy使用.pyi存根文件做类型检查不生效如何解决

配置不生效是三个核心规则没踩中：

• 直接将单个源码文件路径func.py作为mypy的检查目标时，mypy会进入单文件检查模式，不会主动去mypy_path配置的存根目录中查找该入口文件本身对应的.pyi存根，只会为该文件导入的第三方/其他模块查找存根。
• 缺少强制检查无类型注解源码的配置，mypy默认对完全没有写内联类型注解的函数会放宽检查规则，即使找到存根也可能跳过参数类型校验。
• 之前命令中使用的--config并非mypy的标准配置参数，部分版本下无法正确加载配置文件，需要使用标准参数--config-file指定配置路径。

1. 修正mypy配置文件 #

修改home/mypy.ini内容为以下配置：

[mypy]
# 同时将存根目录、当前源码根目录加入mypy的模块搜索路径
mypy_path = $MYPY_CONFIG_FILE_DIR/stubs:$MYPY_CONFIG_FILE_DIR
# 强制对没有写内联类型注解的函数定义做类型检查
check_untyped_defs = True
# 显式声明包根路径，避免mypy自动推导目录结构出错
explicit_package_bases = True

注意：home/stubs目录下不要创建__init__.py或__init__.pyi文件，否则mypy会将其识别为普通代码包而非存根目录，你当前存放的home/stubs/func.pyi文件位置不需要调整。

2. 调整mypy执行命令 #

不要直接传入单个文件路径作为检查目标，改为按模块名检查，在home目录下执行以下命令：

python -m mypy --config-file mypy.ini -p func

如果需要检查目录下所有代码文件，可以直接传入源码根目录路径，命令如下：

python -m mypy --config-file mypy.ini .

执行命令后会输出你需要的类型报错：

func.py:4: error: Argument 1 to "f" has incompatible type "str"; expected "int"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

补充：如果使用mypy 0.900以下的老版本，$MYPY_CONFIG_FILE_DIR环境变量不生效，可以将路径写为绝对路径，或升级mypy到最新稳定版。

内容的提问来源于stack exchange，提问作者j-hil