尊重所有權

在使用名稱空間之前，請了解其目的。

除非明確授權，否則不要插入您不擁有的名稱空間。

如有疑問，請諮詢.

例如，不要插入“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 分類器，
   • 釋出新版本。

因此，舊包的使用者

• 可以繼續使用已棄用版本的舊分發，
• 可以升級到舊分發的最新版本，該版本是空的……
• ...並自動下載新的分發作為舊分發的依賴項。

發現舊專案的使用者會看到它處於非活動狀態。

如何將命名指南應用於現有專案？

現有專案沒有義務重新命名。出於顯而易見的原因，選擇權留給專案作者和維護者。

但是，邀請專案作者

• 至少，說明當前命名。
• 然後規劃並推廣遷移。
• 可選地實際重新命名現有專案或分發的包/模組。