如何让mypy识别独立的-stubs类型存根包？

文件夹结构 #

.
├── foo
│   ├── __init__.py
│   └── classic.py
├── foo-stubs
│   ├── __init__.pyi
│   └── classic.pyi
├── pyproject.toml
└── t.py

各文件内容 #

foo/init.py #

from foo.classic import my_func

foo/classic.py #

def my_func(a):
    return 3

foo-stubs/init.pyi #

from typing import Any
from foo.classic import my_func

__all__ = ['my_func']

foo-stubs/classic.pyi #

from typing import Any

def my_func(a: Any) -> int: ...

pyproject.toml #

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "foo"
version = "0.1.0"
requires-python = ">=3.9"

测试代码与运行结果 #

t.py #

from foo import my_func

reveal_type(my_func)

运行mypy t.py后的输出：

t.py:3: note: Revealed type is "def (a: Any) -> Any"
Success: no issues found in 1 source file

疑问 #

为何识别出的类型是def (a: Any) -> Any？预期应该是def (a: Any) -> builtins.int？

注：已知可将.pyi文件放入foo目录并添加py.typed，但希望通过typing规范中提到的独立-stubs目录方案解决该问题。

解决方案 #

问题出在stubs目录的导入逻辑和mypy的识别配置上：

1. 修正stubs内部的导入路径
   当前foo-stubs/__init__.pyi中使用from foo.classic import my_func，会让mypy直接读取源码模块的类型（而非stubs）。需要改为stubs内部的相对导入，保持结构与源码一致：

from typing import Any
from .classic import my_func  # 指向同目录下的classic.pyi

__all__ = ['my_func']

2. 确保mypy识别stubs目录
   需要明确告诉mypy去哪里找独立stubs，有两种方式：

• 给pyproject.toml添加mypy配置：

  [tool.mypy]
  python_path = ["."]
  stubpath = ["foo-stubs"]
  

• 运行mypy时指定stubs路径：

  mypy --stub-path foo-stubs t.py
  

完成以上修改后，重新运行mypy，reveal_type(my_func)会正确显示为def (a: Any) -> builtins.int。

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