已生成存根文件的自定义包作为依赖时mypy提示找不到模块实现

问题根因 #

• Poetry默认打包规则仅包含.py后缀文件，未显式配置的前提下，.pyi存根文件、py.typed类型标记文件不会被纳入分发包，从Git源安装后虚拟环境内缺失对应类型文件，是触发该报错的最常见原因
• 若确认虚拟环境site-packages/my_utils目录下已存在os.py、os.pyi、py.typed文件，则可能是mypy缓存未更新、或mypy配置中存在my_utils相关的导入忽略规则
• 少数场景下是my_utils项目采用src目录布局但Poetry未正确配置包路径，导致安装后模块路径错位

解决方法 #

1. 修复my_utils项目的Poetry打包配置 #

在my_utils项目的pyproject.toml中添加配置，显式声明需要包含的类型文件：

[tool.poetry]
# 原有配置（name、version、description等）保持不变，新增以下include配置
include = ["my_utils/*.pyi", "my_utils/py.typed"]
# 若存在多层子模块，可改用递归匹配规则：include = ["my_utils/**/*.pyi", "my_utils/py.typed"]

# 若项目采用src布局（my_utils目录在src文件夹下），还需额外添加packages配置
packages = [{include = "my_utils", from = "src"}]

配置修改后推送至GitHub远程仓库。

2. 重新安装依赖 #

在业务项目中执行命令重新安装my_utils：

poetry remove my_utils
poetry add git+ssh://git@github.com/username/my-utils.git

安装完成后验证虚拟环境site-packages/my_utils目录下确实存在os.py、os.pyi、py.typed三个文件。

3. 清理mypy缓存重新检测 #

执行以下命令清除mypy旧缓存后重新执行检测：

mypy --clean
mypy r26/bwf_converter.py

4. 排查mypy配置（可选，若仍报错） #

检查业务项目的mypy配置（mypy.ini或pyproject.toml的[tool.mypy]块），确认不存在针对my_utils的导入忽略规则，比如以下这类配置需要删除：

# [[tool.mypy.overrides]]
# module = "my_utils.*"
# ignore_missing_imports = true

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