是否可以在同一项目内的单独文件夹中包含类型提示？

Question

我正在向我维护的包添加类型注释。根据 PEP484，类型注释的存根文件 (

.pyi

) 可以与实际代码一起分发

在同一目录中或在第三方包中。然而，将 .pyi

 文件放在同一目录中似乎不太优雅，我更愿意将它们分开；类似于 C/C++ 中标头和实现的处理方式。

简而言之，我当前的包结构是这样的：

my_project
|   setup.py
|   pyproject.toml
|   ...
|
|___my_package
|   |   __init__.py
|   |___module_1
|   |   |   __init.py
|   |   |   fancy_module.py
|   |   |   fancy_module.pyi
|   |   |   ...
|   |
|   |___module_2
|   |   |   __init__.py
|   |   |   more_files.py
|   |   |   more_files.pyi
|   |   |   ...

我希望它是这样的（至少 mypy 和 vscode 支持类型注释）：

my_project
|   setup.py
|   pyproject.toml
|   ...
|
|___my_package
|   |   __init__.py
|   |
|   |___module_1
|   |   |   __init.py
|   |   |   fancy_module.py
|   |   |   ...
|   |
|   |___module_2
|   |   |   __init__.py
|   |   |   more_files.py
|   |   |   ...
|
|___stubs
|   |___module1
|   |   |   fancy_module.pyi
|   |   |   ...
|   |
|   |___module2
|   |   |   more_files.pyi
|   |   |   ...
  

这可能吗？还是我需要考虑分发单独的“第三方”包？

Answer 1

我想你可以做到这一点，只需在项目的根级别创建一个“存根”目录并将

.pyi

 文件放入其中即可！如果您想确保 

mypy

 和其他工具识别这些单独的存根文件，您可以将它们配置为在其搜索路径中包含“stubs”目录！

但是如果你更喜欢第三方包，首先为存根文件创建一个新包，例如

my_package-stubs

，然后根据主包的结构组织第三方包中的存根文件，类似于这个：

my_package-stubs
|___my_package
|   |___module_1
|   |   |   fancy_module.pyi
|   |   |   ...
|   |
|   |___module_2
|   |   |   more_files.pyi
|   |   |   ...

现在，将

my_package-stubs

 作为依赖项包含在主包的 

pyproject.toml

 或 

setup.py

 中，通过这样做，当用户安装主包时，来自第三方包的存根文件将与其一起安装。

pyproject.toml

[build-system]
requires = [
    "my_package-stubs",
    ...
]

设置.py

setup(
    ...
    install_requires=[
        'my_package-stubs',
        ...
    ],
    ...
)