为什么Python项目有以下结构？

Question

我正在创建自己的可安装的 Python 包，使用的是 setup.py 文件。在查看不同的代码库时，我发现了以下的结构 -

abc-def
|-abc_def
|-setup.py

在这里，setup.py 文件里有一个叫 setup 的函数，内容如下 -

setup(
    name="abc_def",
)

我想问的是，父目录的名字是否需要和子目录的名字相同，只是把 - 换成 _。特别是因为 Python 似乎不接受 - 这个符号。例如，如果我在代码中使用 import abc-def，我会得到以下错误 -

>>> import abc-def
  File "<stdin>", line 1
    import abc-def
              ^
SyntaxError: invalid syntax

Answer 1

1. Python项目通常有这样的结构，因为这是使用setuptools时推荐的做法。

2. 保持相同的名称并不是强制的，具体可以参考这里。

虽然setuptools允许开发者在目录名称和包名称之间创建非常复杂的映射关系，但最好保持简单，让目录结构能够反映出想要的包层级，并保持名称一致。

3. 建议新项目使用pyproject.toml，而不是setup.py。

Answer 2

根目录的名字是 abc-def，它代表了项目的源代码目录树的名称。这个名字对Python或打包来说并不重要。这样做的目的是为了让项目的源代码目录名和分发包的名字保持一致。

在 setup.py 文件中，abc-def 这个名字被写成 name，它就是分发包的名字。而 abc_def（目录 abc-def/abc_def）是顶层导入包的名字。所以你可以用 pip install abc-def 来安装这个包，但在代码中你要用 import abc_def 来导入它。这两个名字可以完全不同（比如 "beautiful soup 4"），但在Python社区的惯例是这两个名字应该在某种程度上保持一致，只是在分发包名中用短横线 -，而在导入包名中用下划线 _。

导入包的名字必须是有效的Python标识符，所以不允许使用短横线 -。

关于分发包名字的规范规则可以在这个文档中找到：名字和规范化。所以一个名为 abc-def 的分发包，可以用以下任意一种方式安装，结果都是安装同一个包：

• abc-def
• abc_def
• abc.def
• AbC_-._-dEf

你在 setup.py 中写的分发包名字，就是它在 PyPI 上显示的样子。看看这些例子：

• Sphinx 的首字母是大写的 S
• zope.interface 中有一个点 .