为何mypy忽略存根文件？运行mypy未报错的原因

目录结构 #

.
├── mymod.py
└── mymod.pyi

相关文件内容 #

mymod.py #

def add(a, b):
    return a + b

if __name__ == "__main__":
    add(None, None)

mymod.pyi #

from typing import (
    Union,
)

def add(a: Union[int, str], b: Union[int, str]) -> Union[int, str]: ...

未设置任何存根文件相关环境变量或配置，且已清除mypy缓存，运行mypy mymod.py时为何未生成任何错误？

• mypy默认忽略__main__代码块的类型检查：你调用add(None, None)的逻辑处于if __name__ == "__main__":代码块中，mypy的默认规则不会对这个代码块做类型校验，所以即便传入了不符合存根定义的参数，也不会触发错误提示。
• 存根文件主要约束外部导入场景：存根文件的作用是给其他导入该模块的代码提供类型校验依据。如果有其他Python文件导入mymod并调用add(None, None)，mypy就会根据存根里的类型定义抛出错误，但直接检查模块本身时，内部的__main__代码块不在校验范围内。

如果想要让mypy检查__main__代码块的类型问题，可以添加--check-untyped-defs参数执行检查，比如运行mypy --check-untyped-defs mymod.py，此时就能看到add(None, None)违反类型定义的错误提示了。

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