Python单模块包的命名规则是什么？

Question

14

我应该把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
        ...

确保软件包名称和模块导入名称“匹配”：

import super_duper

我应该遵循哪些相关的最佳实践或规则？

- orome

4个回答

5

我不知道是否有任何指导方针要求您的项目名称与安装的包或模块相匹配。有一个deferred draft PEP-423 Naming conventions and recipes related to packaging，但实际上已被废弃（pending update从未应用）。

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

BeautifulSoup项目使用beautifulsoup4作为PyPI上的项目名称，该项目安装了bs4包。
dateutil Python包在PyPI上可用，名称为python-dateutil。在PyPI上使用python-前缀来命名项目名称是相当普遍的，我今天在PyPI上计算了1512个这样的包。
Viivakoodi项目是pyBarcode的一个分支。他们的viivakoodi PyPI项目会在site-packages中安装一个barcode包。另一个类似的分支项目是Pillow，它是Python Image Library的一个分支。它在PyPI上以那个名称可用，但该包会安装PIL包。

个人而言，我更喜欢PyPI项目名称和包含的软件包名称相匹配；这样可以减少混淆。最显著的例外是针对项目分支的情况，其目的是保持旧的软件包名称以便于迁移。

- Martijn Pieters

第二个例子很有趣，因为它消除了我认为存在的一个方程式：包名称和PyPi上的名称之间的关系。因此，实际上有三件事情：包名称、PyPy上的名称以及用于使用包中（孤立的）模型的import所使用的名称。我倾向于同意，最不令人困惑的方法是让这三个名称都相同。 - orome

3

来自PEP 8：

最重要的原则

用户可以看到的作为API公共部分的名称应该遵循反映使用而不是实现的约定。

包和模块名

模块应该有短小的全小写名称。如果下划线可以提高可读性，则可以在模块名称中使用下划线。Python包也应该有短小的全小写名称，尽管不建议使用下划线。

这里唯一涉及您问题的事情是不建议在包名中使用下划线。

目前还有其他PEP正在处理Python打包中的一些不一致性（426，423），但在这些问题解决之前，我会按照PEP 20的规定去做。如果super足以表达被导入的内容，那么我倾向于选择它（虽然如果是这种情况，为什么不在PyPi包名称中使用它呢？）。

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

- Nathaniel

2

你的想法很正确。我见过最常用且对我很有帮助的做法是：

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

你会发现大多数Python开发人员喜欢使用全小写字母且没有特殊字符的模块名称（例如：setuptools，pexpect，matplotlib等）。你的顶级项目文件夹也应与git repo名称匹配，这样当你git clone时它不会改变。

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

- Lundy

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- mwobee · Accepted Answer

简短的回答是：对于单一模块包（应该是大多数发布的包），将模块的名称与包的名称匹配通常是一个好的做法。

稍长的答案是，命名约定总是政治性的。在Python中定义语言标准的通常接受方法是一种称为“Python Enhancement Proposals”（PEP）的过程。PEP由PEP编辑委员会管理，并可公开索引进行审查和评论。

目前，我所知道的仅有一个涵盖模块命名约定的“Active”（已接受并实施）PEP是PEP 8：

模块应具有短小的、全小写的名称。如果下划线可以提高可读性，则可以在模块名称中使用下划线。Python包也应具有短小的、全小写的名称，尽管不鼓励使用下划线。

然而，还有一个提案处于起草阶段，叫做PEP 423，建议正是你在帖子中所说的：

每个项目只分发一个包（或一个模块），并使用包（或模块）名称作为项目名称。

请注意，这个PEP仍处于“Deferred”状态，这意味着它尚未被PEP编辑批准，并且被另一个提案（具体来说是在PEP 440中实现更新模块元数据语法）所阻止。然而，在423号提案最初提出以来，没有竞争标准草案，而且大部分内容似乎都相当不容争议，因此我预计它将来会被接受，而不需要太多重大变化。