尊重所有权

在使用命名空间之前，请了解其目的。

除非明确授权，否则不要插入您不拥有的命名空间。

如有疑问，请咨询.

例如，不要插入“django.contrib”命名空间，因为它由Django的核心贡献者管理。

项目作者可以定义例外情况。参见下面的组织社区贡献。

此外，此规则适用于非Python项目。

例如，不要使用“apache”作为顶级命名空间：“Apache”是一个现有项目的名称（在“Apache”的情况下，它也是一个商标）。

私有（包括闭源）项目使用命名空间

...因为私有项目由某人拥有。因此，应用所有权规则。

对于内部/客户项目，使用您的公司名称作为命名空间。

此规则适用于闭源项目。

例如，如果您正在为“Python Sport”公司创建一个“climbing”项目：使用“pythonsport.climbing”名称，即使它是闭源的。

个人项目使用命名空间

...因为它们由个人拥有。因此，应用所有权规则。

即使项目具有“内部”或“个人”名称，将其作为开源项目发布也无需羞愧。

如果项目发展到作者希望更改所有权的地步（即项目不再属于个人），请记住重命名项目很容易。

社区拥有的项目可以避免命名空间包

如果您的项目足够通用（即它不是另一个产品或框架的贡献），您可以避免命名空间包。基本条件通常是您的项目由专门从事此项目的团体（即开发团队）拥有。

只有当您确实打算让代码为社区所有时，才使用“共享”命名空间。

例如，sphinx项目属于Sphinx开发团队。没有必要拥有一个只有一个“sphinx.sphinx”项目的“sphinx”命名空间包。

如有疑问，请使用个人/组织命名空间

如果您的项目确实是实验性的，最好的选择是使用个人或组织命名空间

• 它允许项目尽早发布。
• 如果项目被废弃，它不会占用名称。
• 它不会阻碍未来的变化。当项目成熟且没有理由保留个人所有权时，仍然可以重命名项目。

多个包/模块应该很少见

从技术上讲，Python 分发可以提供多个包和/或模块。有关详细信息，请参阅安装脚本参考。

有些分发确实如此。例如，setuptools 和 distribute 都声明了“pkg_resources”、“easy_install”和“site”模块，此外还有各自的“setuptools”和“distribute”包。

将此用例视为例外。在大多数情况下，您不需要此功能。因此，一个分发应该一次只提供一个包或模块。

不同的名称应该很少见

使用单一名称规则的一个显著例外是当您明确需要不同名称时。

例如，Pillow 项目提供了原始 PIL 分发的替代方案。这两个项目都分发一个“PIL”包。

将此用例视为例外。在大多数情况下，您不需要此功能。因此，分发包名称应与项目名称相同。

两层几乎总是足够的

不要在深层嵌套的层次结构中定义所有内容：您最终会得到诸如“pythonsport.common.maps.forest”之类的项目和包。这种类型的名称既冗长又笨重（例如，如果您从包中导入很多内容）。

此外，大型层次结构往往会随着时间的推移而崩溃，因为不同包之间的界限变得模糊不清。

共识是优先使用两层嵌套。

例如，我们有 plone.principalsource 而不是 plone.source.principal 或类似的东西。名称更短，包结构更简单，并且在这里拥有三层嵌套几乎没有任何好处。试图将所有“核心 Plone”源（源是一种词汇表）放入 plone.source.* 命名空间是不切实际的，部分原因是一些源是其他包的一部分，部分原因是因为源已经存在于其他地方。如果我们创建了一个新的命名空间，它从一开始就会被不一致地使用。

是：“pyranha”

是：“pythonsport.climbing”

是：“pythonsport.forestmap”

否：“pythonsport.maps.forest”

所有权只使用一层

不要使用3层来在社区命名空间中设置个人/组织所有权。

例如，让我们考虑

• 您正在插入一个社区命名空间，例如“collective”。
• 您想添加一个更严格的“所有权”级别，以避免社区内部的冲突。

在这种情况下，您最好将最严格的所有权级别作为第一层。

例如，其中“collective”是“gergovie”所属的主要社区命名空间，“vercingetorix”是“gergovie”作者的名字

否：“collective.vercingetorix.gergovie”

是：“vercingetorix.gergovie”

不要使用命名空间层进行分类

请改用打包元数据。

不要使用超过3层

从技术上讲，您可以创建深度嵌套的层次结构。但是，在大多数情况下，您不应该需要它。

如果存在，请遵循社区或相关项目约定

项目或相关社区可能具有特定的约定，这些约定可能与本文档中解释的约定不同。

在这种情况下，他们应在文档中声明特定的约定。

因此，如果您的项目属于另一个项目或社区，请首先在主项目的文档中查找特定约定。

如果没有特定的约定，请遵循本文档中声明的约定。

例如，Plone 社区在“collective”命名空间包中发布社区贡献。这与此处提出的标准贡献命名空间不同。但由于它有文档记录，因此没有歧义，您应该遵循此特定约定。

社区贡献使用标准模式

当没有定义特定规则时，使用 ${MAINPROJECT}contrib.${PROJECT} 模式来存储任何产品或框架的社区贡献，其中

• ${MAINPROJECT} 是相关项目的名称。在下面的示例中是“pyranha”。
• ${PROJECT} 是您的项目名称。在下面的示例中是“giantteeth”。

举例来说：

• 您是“pyranha”项目的作者。您拥有“pyranha”命名空间。
• 您没有为社区贡献定义特定的命名约定。
• 第三方开发人员希望在社区命名空间中发布与您的“pyranha”项目相关的“giantteeth”项目。因此，他应该将其发布为“pyranhacontrib.giantteeth”。

这是组织社区贡献的最简单方法。

组织社区贡献

这是遵循社区约定和贡献的标准模式规则的对应部分。

行动

• 为社区贡献选择一个命名约定。
• 如果它不是默认值，则将其记录下来。
  • 如果您使用默认约定，那么本文档应该足够了。不要重复它。您可以引用它。
  • 否则，请在项目的“贡献”或“创建模块”文档中告知用户自定义约定。
• 还建议使用额外的元数据，例如分类器和关键词。

关于约定选择

• 新项目应选择默认贡献模式。
• 现有社区贡献项目应从自定义约定开始。然后，它们可以促进迁移。

  这意味着现有的社区约定不必更改。但是，至少，它们应该明确地记录下来。

示例：“pyranha”是您的项目名称和包名称。告诉贡献者

• pyranha 相关分发应使用“pyranha”关键字
• 提供模板的 pyranha 相关分发也应使用“templates”关键字。
• 社区贡献应在“pyranhacontrib”命名空间下发布（即使用“pyranhacontrib.*”模式）。

如何检查名称可用性？

在选择项目名称之前，请确保它尚未在以下位置注册

• PyPI
• 就是这样。PyPI是唯一的官方场所。

例如，您也可以在各种位置（如流行的代码托管服务）进行检查，但请记住，PyPI是您在Python社区中可以**注册**名称的唯一地方。

这就是为什么在PyPI上注册名称很重要的原因。

还要确保已分发包或模块的名称尚未注册

• 在Python 标准库中。
• 在PyPI上的项目内部。目前没有相关的辅助工具。请注意，遵循使用单一名称规则的项目越多，验证就越容易。
• 您可以咨询社区。

使用单一名称规则也有助于您避免与包名称冲突：如果项目名称可用，那么包名称也很可能可用。

如何重命名项目？

重命名项目是可能的，但请记住这会造成一些混淆。因此，请特别注意 README 和文档，以便用户理解发生了什么。

1. 首先，不要从 PyPI 中删除旧的分发。因为有些用户可能正在使用它们。
2. 复制旧项目，然后更改名称（项目和包/模块）。至少要注意
   • 打包文件，
   • 包含源文件的文件夹名称，
   • 文档，包括 README，
   • 代码中的导入语句。
3. 在 setup.cfg 文件中为新分发分配 Obsoletes-Dist 元数据。请参阅 PEP 345 关于 Obsolete-Dist 和 setup.cfg 规范。
4. 发布重命名项目的新版本，然后发布它。
5. 编辑旧项目
   • 添加对新项目的依赖，
   • 删除除打包内容之外的所有内容，
   • 在安装脚本中添加 Development Status :: 7 - Inactive 分类器，
   • 发布新版本。

因此，旧包的用户

• 可以继续使用已弃用版本的旧分发，
• 可以升级到旧分发的最新版本，该版本是空的……
• ...并自动下载新的分发作为旧分发的依赖项。

发现旧项目的用户会看到它处于非活动状态。

如何将命名指南应用于现有项目？

现有项目没有义务重命名。出于显而易见的原因，选择权留给项目作者和维护者。

但是，邀请项目作者

• 至少，说明当前命名。
• 然后规划并推广迁移。
• 可选地实际重命名现有项目或分发的包/模块。