如何让mypy正确使用自定义类型提示文件？

方案1：利用Poetry+Mypy配置指定类型提示路径（推荐） #

• 在项目根目录创建types目录，内部新建bob-stubs子目录，将你的*.pyi类型提示文件放入其中
• 在pyproject.toml中添加Mypy相关配置：

  [tool.mypy]
  # 指定类型提示搜索路径
  mypy_path = "./types"
  # 排除对types目录下stubs文件的类型检查
  exclude = ['types/.*']
  # 单独对bob-stubs设置宽松检查规则（避免mypy校验stubs自身）
  [tool.mypy.types.bob-stubs]
  ignore_missing_imports = true
  follow_imports = silent
  

方案2：构建PEP 561兼容的本地stubs包 #

• 按PEP 561规范整理bob-stubs目录结构：

  bob-stubs/
      __init__.pyi
      # 对应第三方包模块的.pyi文件
      py.typed  # 空文件，必须存在，标记该目录为合法类型提示包
  

• 在pyproject.toml中添加本地stubs依赖：

  [tool.poetry.dependencies]
  bob-stubs = { path = "./bob-stubs", develop = true }
  

• 执行poetry install，Poetry会将该stubs包链接到虚拟环境的site-packages，mypy会自动识别，且不会对stubs文件本身做类型检查

方案3：调整现有typings目录的Mypy规则 #

• 若保留项目内的typings/bob-stubs目录，修改mypy.ini配置：

  [mypy]
  mypy_path = ./typings
  # 全局排除typings目录的类型检查
  exclude = typings/
  # 或单独针对bob-stubs设置忽略规则
  [mypy-bob-stubs.*]
  ignore_errors = true
  follow_imports = silent
  

验证方式 #

• 执行mypy --verbose 你的脚本文件.py，查看输出日志中是否包含Loading stub file from .../bob-stubs/...的内容，确认mypy已加载自定义类型提示

内容的提问来源于stack exchange，提问作者Paul D Smith