尊重所有权

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

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

如有疑问，请咨询.

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

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

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

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

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

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

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

此规则适用于闭源项目。

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

单个项目使用命名空间

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

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

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

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

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

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

例如，sphinx项目属于Sphinx开发团队。无需在内部创建一个名为“sphinx”的命名空间包，其中只包含一个名为“sphinx.sphinx”的项目。

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

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

• 它允许项目尽早发布。
• 如果项目被放弃，它不会阻塞名称。
• 它不会阻止将来的更改。当项目变得成熟并且没有理由保留个人所有权时，仍然可以重命名项目。

多个包/模块应该很少见

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

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

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

不同的名称应该很少见

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

例如，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”。

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

组织社区贡献

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

操作

• 为社区贡献选择命名约定。
• 如果它不是默认值，则记录它。
  • 如果您使用默认约定，则本文档就足够了。无需重复。您可以引用它。
  • 否则，在项目的“贡献”或“创建模块”文档中告诉用户自定义约定。
• 此外，建议使用其他元数据，例如分类器和关键词。

关于约定选择

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

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

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

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

如何检查名称可用性？

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

• PyPI
• 仅此而已。PyPI 是唯一官方场所。

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

这就是为什么您需要使用 PyPI 注册名称很重要的原因。

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

• 在Python 标准库中。
• 在 PyPI 中的项目内部。目前没有为此提供帮助程序。请注意，越多的项目遵循使用单个名称规则，验证就越容易。

• 如果您有任何疑问，可以咨询社区。

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

如何重命名项目？

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

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

因此，旧版包的用户

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

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

如何在现有项目上应用命名指南？

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

但是，邀请项目作者

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