命名单模块 Python 包有规则吗？

Question

我给 Python 包中的单独模块的名称是否应该与包的名称匹配？

例如，如果我有一个包含结构为

的单个模块的包

super-duper/
    super/
        __init.py___
        mycode.py
        ...

我可以在 PyPi 上创建一个包 super-duper，安装后，site-packages 中会有两个名称不匹配的文件夹：

 super/
 super_duper-1.2.3.dist-info/

这意味着要导入我使用的项目

import super

而不是实际的包名(super_duper)

这似乎违反了遵循模式

的惯例（从我在 site-packages 中看到的早期其他每个包的文件夹判断）

 same_name/
 same_name-1.2.3.dist-info/

对于 PyPi 包 same-name。

我是否应该（总是）构建我的项目，以便

super-duper/
    super_duper/
        __init.py___
        mycode.py
        ...

确保包名和模块导入名"match":

import super_duper

是否有我应该遵循的相关最佳实践或规则？

Answer 1

你的想法是对的。我见过最常用且对我来说效果很好的约定是：

/superduper
    /superduper
        __init__.py
        code.py
    /.git
    setup.py
    README.rst

您会发现大多数 python 开发人员更喜欢模块名称（setuptools、pexpect、matplotlib 等）全部小写且没有特殊字符。
您的顶级项目文件夹也应该与 git 存储库名称相匹配，这样当您 git 克隆时它不会改变。

我最好的建议是查看一些已建立的良好项目的源代码，并模仿他们所做的。

Answer 2

来自PEP 8：

Overriding Principle

Names that are visible to the user as public parts of the API should follow conventions that reflect usage rather than implementation.

Package and Module Names

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

这里唯一似乎可以解决您的问题的是不鼓励在包名称中使用下划线。

目前还有其他 PEP 正在处理 Python 包装中的一些一般不一致问题（426, 423), but until those are resolved I would go with what makes the most sense under PEP 20。如果 super 足以传达正在导入的内容，那么我会倾向于使用它（尽管如果是这样，为什么不将它也用于 PyPi 包名称呢？）。

我不认为惯例要求它们相同，但实际上它们都在努力实现相同的目标，因此在大多数情况下最终都是相同的。

Answer 3

据我所知，没有任何准则要求您的项目名称与已安装的包或模块相匹配。有一个 deferred draft PEP-423 Naming conventions and recipes related to packaging, but this is effectively abandoned (a pending update 从未应用过）。

你说你看了，但你可能错过了一些项目名称和包含的包不匹配的现有示例：

PyPI上的项目名BeautifulSoup project uses beautifulsoup4，安装包bs4.
dateutil Python package is available on PyPI as python-dateutil。在 PyPI 项目名称前加上 python- 是相当常见的，我今天在 PyPI 上统计了 1512 个这样的包。
Viivakoodi project is a fork of pyBarcode. Their viivakoodi PyPI project installs a barcode package in site-packages. Another such fork project is Pillow, which is a fork of the Python Image Library. It is available on PyPI under that name但包安装PIL包。

也就是说，我个人更喜欢它，因为 PyPI 项目名称和包含的包相匹配；它减少了混乱。最值得注意的例外是项目分叉，其目的是维护旧包名称以简化迁移。

Answer 4

对您的问题的简短回答是：是的，让您的模块名称与单个模块包（应该是大多数已发布的包）的包名称相匹配通常是一个好习惯。

稍微长一点的答案是命名约定总是政治性的。在 Python 中定义语言标准的普遍接受的方法是称为 "Python Enhancement Proposals" (PEPs) 的过程。 PEP 由一组 PEP 编辑管理，publicly indexed 供审查和评论。

目前，只有一个 "Active"（已接受并已实施）PEP 我知道它涵盖了模块命名约定，即 PEP 8:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

但是，还有一个名为 PEP 423 的提案仍在起草过程中，它完全推荐您在 post 中陈述的内容：

Distribute only one package (or only one module) per project, and use package (or module) name as project name.

It avoids possible confusion between project name and distributed package or module name.

It makes the name consistent.

It is explicit: when one sees project name, he guesses package/module name, and vice versa.

It also limits implicit clashes between package/module names. By using a single name, when you register a project name to PyPI, you also perform a basic package/module name availability verification.

重要的是要注意此 PEP 仍处于 "Deferred" 状态，这意味着它未被 PEP 编辑批准，并被另一个人阻止提案（特别是在 PEP 440 中实现对模块元数据语法的更新）。但是，自 423 最初提出以来，当时并没有起草任何竞争标准，而且很多内容似乎都没有争议，所以我希望它在未来不会有太大的变化而被接受。

命名单模块 Python 包有规则吗？

Are there rules for naming single-module Python packages?

python

python-module

package

pypi