是否有使软件包符合 PEP-561 的最佳实践？

Posted 2023-02-16

【中文标题】是否有使软件包符合 PEP-561 的最佳实践？

【英文标题】：Is there a best practice to make a package PEP-561 compliant?

【发布时间】：2020-11-08 18:14:52

【问题描述】：

我正在编写一个 Python 项目，它作为一个包发布到类似 pypi 的存储库（使用 setuptools 和 twine）。我在代码中使用类型提示。

问题是，当从另一个项目导入包并运行mypy 时，我收到以下错误： error: Skipping analyzing 'XXX': found module but no type hints or library stubs

据我了解，我收到此错误是因为我的包不符合 https://www.python.org/dev/peps/pep-0561/ 。

在网上搜索了一番，没有找到一种非手动的方式将所需文件添加到包中。

我求助于编写自己的代码：

运行stubgen 创建存根文件。 在每个目录中创建py.typed 文件。 在setup.py 文件的package_data 字段中的dict 中收集所有创建的文件。

这段代码解决了这个问题，mypy 运行没有错误。但这对我来说是非常错误的。是否有使包符合 PEP-561 的标准工具？我还缺少其他东西吗？

【问题讨论】：

您是否尝试过跳过第 1 步并简化第 3 步，以便只在 package_data 字段中包含 py.typed 文件？如果有一个py.typed 文件并且没有存根文件，则应该使用 mypy 等类型检查器直接分析您的源代码以获取类型提示。

这是一个很好的优化，但最终我还是要编写自定义代码。此外，生成存根是很容易的部分，因为有一个工具可以做到这一点。

我认为您不需要编写任何自定义代码？您应该只需要在***包中创建一个 py.typed 文件并调整您的 setup.py 文件一次以硬编码新文件的路径。***包中py.typed 文件的存在意味着必须由类型检查器分析所有子包。仔细看看您的第二步，您似乎正在做的是在每个目录中添加一个py.typed 文件？如果是这样，那应该没有必要。

有趣..我会尝试报告回来

感谢@Michael0x2a！那成功了。您想将其添加为答案吗？

【参考方案1】：

如前所述，您需要在模块的包文件夹中添加py.typed。 您还需要将该文件添加到setup.py package_data - 否则当您部署该文件时，该文件将不是包的一部分。

我个人将类型注释放在代码中并且不创建额外的存根文件——但这只能从 python 3.4 开始。如果你想制作兼容 python2.7 的代码，你不能使用内联类型注释——在这种情况下你可以使用存根文件。

如果您想对第三方库进行类型注解，您可以为您用于该库的函数编写一个 *.pyi 文件。这可能有点棘手，因为 MYPY 只能在 MYPY 路径中找到该 *.pyi 文件一次。

所以我是这样处理的：

对于本地测试，MYPY 路径设置为我收集所有第 3 方存根的目录， 为了在 travis 上进行测试，我在包中有一个子目录，其中包含该模块在 travis 上测试它所需的存根，并相应地设置 mypy 路径。

【参考方案2】：

解决方案是将一个py.typed 文件添加到主包的根目录。这迫使 mypy 分析类型。

【讨论】：

重要的是，将py.typed 文件添加到 setup.py 中的 package_data 或 MANIFEST.in 文件中。