是否有命名单模块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
        ...

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

import super_duper

我应该遵循相关的最佳做法或规则吗？

Answer 1

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

稍微长一点的答案是命名约定总是政治性的。在Python中定义语言标准的普遍接受的方法是称为“Python增强提议”（PEP）的过程。 PEP由一组PEP编辑管理，publicly indexed用于审核和评论。

目前，我所知道的只有一个“活跃”（接受并实施）的PEP涵盖了模块命名约定，即PEP 8：

  

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

但是，在起草过程中还有另一个名为PEP 423的提案，建议您在帖子中说明的内容：

  

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

     

  

• 它避免了项目名称与分布式软件包或模块名称之间可能出现的混淆。

  

• 它使名称保持一致。

  

• 这是明确的：当人们看到项目名称时，他会猜测包/模块名称，反之亦然。

  

• 它还限制了包/模块名称之间的隐式冲突。通过使用单个名称，当您将项目名称注册到PyPI时，您就可以了   还执行基本的包/模块名称可用性验证。

  

值得注意的是，此PEP仍处于“延迟”状态，这意味着它已经未已被PEP编辑批准，并被另一个提案阻止（特别是实施更新到PEP 440中的模块元数据语法。然而，自423的原始提案以来，没有起草任何竞争标准，而且大部分内容似乎都是相当无争议的，所以我希望将来可以接受它而不会有太多重大变化。

Answer 2

我不知道需要您的项目名称与已安装的软件包或模块匹配的准则。有一个deferred draft PEP-423 Naming conventions and recipes related to packaging，但实际上已经放弃了（从未应用pending update）。

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

• BeautifulSoup project使用beautifulsoup4作为PyPI上的项目名称，后者会安装包bs4。

• dateutil Python package在PyPI上可用python-dateutil。使用python-前缀PyPI项目名称相当普遍，我今天在PyPI上计算了1512个这样的包。

• Viivakoodi project是pyBarcode的一个分支。他们的viivakoodi PyPI project会在barcode中安装site-packages个包。另一个这样的fork项目是Pillow，它是Python Image Library的一个分支。它在PyPI under that name上可用，但该软件包会安装PIL软件包。

那就是说，我个人更喜欢它的PyPI项目名称和包含的包匹配;它减少了混乱。最值得注意的例外是项目分支，其目的是维护旧的软件包名称以便于迁移。

Answer 3

来自PEP 8：

  

覆盖原则

     

作为API的公共部分对用户可见的名称应遵循反映使用而非实现的约定。

     

套餐和模块名称

     

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

这里似乎唯一能解决你的问题的是不鼓励打包名称中的下划线。

目前正在开展其他PEP工作来解决Python包装中的一些不一致问题（426，423），但在这些问题得到解决之前我会选择最有意义的内容。在PEP 20下。如果super足以传达正在导入的内容，那么我倾向于使用它（尽管如果是这样，为什么不将它用于PyPi包名呢？）。

我不认为惯例规定它们是相同的，但在实践中它们都试图达到相同的目标，因此在大多数情况下最终都是相同的。

Answer 4

你有正确的想法。我见过的最常用的惯例，对我来说效果很好的是：

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

你会发现大多数python开发人员更喜欢所有小写字母，模块名称没有特殊字符（setuptools，pexpect，matplotlib等）。
你的顶级项目文件夹也应该与git repo名称匹配，这样你在git clone时就不会改变。

我最好的建议是，从一些优秀的项目中查看来源，并模仿他们所做的事情。