PYPI包装中的SRC/文件夹是否具有特殊的含义，还是仅是约定？

Question

我正在学习如何根据教程为PYTI打包Python项目（）。对于示例项目，他们使用文件夹结构：

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
└── tests/

我只是想知道为什么需要 src/文件夹？它有特殊目的吗？一个人可以直接在顶级文件夹中包含包装吗？例如，会有

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── example_package_YOUR_USERNAME_HERE/
│   ├── __init__.py
│   └── example.py
└── tests/

任何缺点或引起并发症吗？

Answer 1

有一个有趣的博客文章关于此主题；基本上，使用 src 可以防止在项目目录中运行测试时，软件包源文件夹将导入而不是已安装的软件包（并且测试应始终针对安装的软件包进行，以便情况相同至于用户）。

考虑以下示例项目，其中正在开发的软件包的名称为 mypkg 。它包含 __ INIT __。py 文件和另一个 data.txt non-code资源：

.
├── mypkg
│   ├── DATA.txt
│   └── __init__.py
├── pyproject.toml
├── setup.cfg
└── test
    └── test_data.py

此处， mypkg/__ init __ init __. py 访问> data.txt 资源并加载其内容：

from importlib.resources import read_text
  
data = read_text('mypkg', 'DATA.txt').strip()  # The content is 'foo'.

脚本 test/test_data.py 检查 mypkg.data 实际上包含'foo'：

import mypkg
  
def test():
    assert mypkg.data == 'foo'

现在，运行 coverage> coverage> coverage> mm pytest 从基本目录中提供这个项目的印象是一切都很好：

$ coverage run -m pytest
[...]
test/test_data.py .                                             [100%]

========================== 1 passed in 0.01s ==========================

但是，有一个微妙的问题。运行 coverage Run -M Pytest Invokes pytest 通过 python -m pytest ，即使用 -m 开关。如文档中所述，这具有“副作用”：

[...]与 -c 选项一样，当前目录将添加到 sys.path的开始中。 [...]

这意味着，在 Mypkg 中导入 test/test_data.py 时，它没有导入已安装的版本，但它从源树中导入了软件包 mypkg 而不是。

现在，让我们进一步假设我们忘了在我们的项目规范中包含 data.txt 资源（毕竟，没有 subtest.in ）。因此，该文件实际上不包含在安装 mypkg 的版本中（例如，通过 python -m pip install. 安装。）。通过直接运行 pytest 来揭示这一点：

$ pytest
[...]
======================= short test summary info =======================
ERROR test/test_data.py - FileNotFoundError: [Errno 2] No such file ...
!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!
========================== 1 error in 0.13s ===========================

因此，尽管安装了 mypkg 被损坏，但使用 coverage 测试通过。该测试没有捕获它，因为它是针对源树而不是安装版本的。如果我们已经使用 src 目录来包含 mypkg 软件包，则通过 -m 添加当前的工作目录不会引起任何问题，例如当前工作目录中没有包装 mypkg 。

但是最后，使用 src 不是必需品，而是更多的惯例/最佳实践。例如，请求不使用 src ，它们仍然设法成为一种流行和成功的项目。