Besitz respektieren

Verstehen Sie den Zweck eines Namespaces, bevor Sie ihn verwenden.

Schließen Sie sich keinem Namespace an, der Ihnen nicht gehört, es sei denn, dies ist ausdrücklich genehmigt.

Im Zweifelsfall fragen.

Verbinden Sie sich beispielsweise nicht mit dem „django.contrib“-Namespace, da dieser von den Kernbeitragenden von Django verwaltet wird.

Ausnahmen können von Projektverfassern definiert werden. Siehe Community-Beiträge organisieren unten.

Diese Regel gilt auch für Nicht-Python-Projekte.

Verwenden Sie beispielsweise nicht „apache“ als Top-Level-Namespace: „Apache“ ist der Name eines bestehenden Projekts (im Fall von „Apache“ ist es auch eine Marke).

Private (einschließlich Closed-Source) Projekte verwenden einen Namespace

… weil private Projekte jemandem gehören. Wenden Sie also die Besitzregel an.

Für interne/Kundenprojekte verwenden Sie den Namen Ihres Unternehmens als Namespace.

Diese Regel gilt für Closed-Source-Projekte.

Wenn Sie beispielsweise ein Projekt „climbing“ für das Unternehmen „Python Sport“ erstellen: Verwenden Sie den Namen „pythonsport.climbing“, auch wenn es Closed Source ist.

Individuelle Projekte verwenden einen Namespace

… weil sie Einzelpersonen gehören. Wenden Sie also die Besitzregel an.

Es gibt keine Schande, ein Projekt als Open Source zu veröffentlichen, auch wenn es einen „internen“ oder „individuellen“ Namen hat.

Wenn das Projekt an einem Punkt angelangt ist, an dem der Autor den Besitz ändern möchte (d. h. das Projekt gehört nicht mehr einer Einzelperson), denken Sie daran, dass es einfach ist, das Projekt umzubenennen.

Community-eigene Projekte können Namespace-Pakete vermeiden

Wenn Ihr Projekt generisch genug ist (d. h. es ist kein Beitrag zu einem anderen Produkt oder Framework), können Sie Namespace-Pakete vermeiden. Die Grundbedingung ist im Allgemeinen, dass Ihr Projekt einer Gruppe (d. h. dem Entwicklungsteam) gehört, die sich diesem Projekt widmet.

Verwenden Sie nur einen „gemeinsamen“ Namespace, wenn Sie wirklich beabsichtigen, dass der Code gemeinschaftseigen ist.

Zum Beispiel gehört das Projekt sphinx dem Sphinx-Entwicklungsteam. Es besteht keine Notwendigkeit, ein „sphinx“-Namespace-Paket mit nur einem Projekt „sphinx.sphinx“ darin zu haben.

Im Zweifelsfall einen individuellen/organisatorischen Namespace verwenden

Wenn Ihr Projekt wirklich experimentell ist, ist die beste Wahl die Verwendung eines individuellen oder organisatorischen Namespace

• es ermöglicht frühe Veröffentlichungen von Projekten.
• es wird einen Namen nicht blockieren, wenn das Projekt aufgegeben wird.
• es blockiert keine zukünftigen Änderungen. Wenn ein Projekt reif wird und es keinen Grund mehr gibt, den individuellen Besitz beizubehalten, bleibt es möglich, das Projekt umzubenennen.

Mehrere Pakete/Module sollten selten sein

Technisch gesehen können Python-Distributionen mehrere Pakete und/oder Module bereitstellen. Siehe Setup-Skript-Referenz für Details.

Einige Distributionen tun dies tatsächlich. Zum Beispiel deklarieren setuptools und distribute neben den jeweiligen Paketen „setuptools“ und „distribute“ auch die Module „pkg_resources“, „easy_install“ und „site“.

Betrachten Sie diesen Anwendungsfall als Ausnahme. In den meisten Fällen benötigen Sie diese Funktion nicht. Daher sollte eine Distribution nur ein Paket oder Modul gleichzeitig bereitstellen.

Unterschiedliche Namen sollten selten sein

Eine bemerkenswerte Ausnahme von der Regel Einen einzelnen Namen verwenden ist, wenn Sie explizit unterschiedliche Namen benötigen.

Zum Beispiel bietet das Projekt Pillow eine Alternative zur ursprünglichen PIL-Distribution. Beide Projekte verteilen ein „PIL“-Paket.

Betrachten Sie diesen Anwendungsfall als Ausnahme. In den meisten Fällen benötigen Sie diese Funktion nicht. Daher sollte der Name eines verteilten Pakets mit dem Projektnamen übereinstimmen.

Zwei Ebenen sind fast immer genug

Definieren Sie nicht alles in tief verschachtelten Hierarchien: Sie werden am Ende bei Projekten und Paketen wie „pythonsport.common.maps.forest“ landen. Diese Art von Namen ist sowohl sperrig als auch umständlich (z. B. wenn Sie viele Importe aus dem Paket haben).

Darüber hinaus neigen große Hierarchien dazu, im Laufe der Zeit zusammenzubrechen, da die Grenzen zwischen verschiedenen Paketen verschwimmen.

Der Konsens ist, dass zwei Verschachtelungsebenen bevorzugt werden.

Zum Beispiel haben wir plone.principalsource anstelle von plone.source.principal oder etwas Ähnlichem. Der Name ist kürzer, die Paketstruktur ist einfacher, und es gäbe wenig zu gewinnen, drei Verschachtelungsebenen hier zu haben. Es wäre unpraktisch zu versuchen, alle „Kern-Plone“-Quellen (eine Quelle ist eine Art Vokabular) in den Namespace plone.source.* aufzunehmen, zum Teil, weil einige Quellen Teil anderer Pakete sind, und zum Teil, weil Quellen bereits an anderer Stelle existieren. Hätten wir einen neuen Namespace geschaffen, wäre er von Anfang an inkonsistent verwendet worden.

Ja: „pyranha“

Ja: „pythonsport.climbing“

Ja: „pythonsport.forestmap“

Nein: „pythonsport.maps.forest“

Nur eine Ebene für den Besitz verwenden

Verwenden Sie keine 3 Ebenen, um individuelle/organisatorische Zugehörigkeit in einem Community-Namespace festzulegen.

Als Beispiel betrachten wir

• Sie schließen sich einem Community-Namespace an, wie z. B. „collective“.
• und Sie möchten eine restriktivere „Besitz“-Ebene hinzufügen, um Kollisionen innerhalb der Community zu vermeiden.

In diesem Fall **verwenden Sie besser die restriktivste Besitzebene als erste Ebene.**

Zum Beispiel, wo „collective“ ein großer Community-Namespace ist, zu dem „gergovie“ gehört, und „vercingetorix“ der Name des Autors von „gergovie“ ist

Nein: „collective.vercingetorix.gergovie“

Ja: „vercingetorix.gergovie“

Keine Namespace-Ebenen zur Kategorisierung verwenden

Verwenden Sie Packaging-Metadaten stattdessen.

Nicht mehr als 3 Ebenen verwenden

Technisch gesehen können Sie tief verschachtelte Hierarchien erstellen. In den meisten Fällen benötigen Sie dies jedoch nicht.

Community- oder verwandte Projektkonventionen befolgen, falls vorhanden

Projekte oder verwandte Communities können spezifische Konventionen haben, die von den in diesem Dokument erklärten abweichen können.

In diesem Fall sollten sie spezifische Konventionen in der Dokumentation deklarieren.

Wenn Ihr Projekt also zu einem anderen Projekt oder einer Community gehört, suchen Sie zuerst nach spezifischen Konventionen in der Dokumentation des Hauptprojekts.

Wenn es keine spezifischen Konventionen gibt, folgen Sie denen, die in diesem Dokument erklärt werden.

Zum Beispiel veröffentlicht die Plone-Community Community-Beiträge im Namespace-Paket „collective“. Dies unterscheidet sich von dem Standard-Namespace für Beiträge, der hier vorgeschlagen wird. Aber da es dokumentiert ist, gibt es keine Mehrdeutigkeit und Sie sollten dieser spezifischen Konvention folgen.

Standardmuster für Community-Beiträge verwenden

Wenn keine spezifische Regel definiert ist, verwenden Sie das Muster ${MAINPROJECT}contrib.${PROJECT}, um Community-Beiträge für jedes Produkt oder Framework zu speichern, wobei

• ${MAINPROJECT} der Name des zugehörigen Projekts ist. „pyranha“ im folgenden Beispiel.
• ${PROJECT} der Name Ihres Projekts ist. „giantteeth“ im folgenden Beispiel.

Als Beispiel:

• Sie sind der Autor des Projekts „pyranha“. Sie besitzen den Namespace „pyranha“.
• Sie haben keine spezifischen Namenskonventionen für Community-Beiträge definiert.
• ein Drittentwickler möchte ein Projekt „giantteeth“ veröffentlichen, das mit Ihrem Projekt „pyranha“ in einem Community-Namespace zusammenhängt. Also sollte er es als „pyranhacontrib.giantteeth“ veröffentlichen.

Dies ist der einfachste Weg, Community-Beiträge zu organisieren.

Community-Beiträge organisieren

Dies ist das Gegenstück zu den Regeln Community- oder verwandte Projektkonventionen befolgen, falls vorhanden und Standardmuster für Community-Beiträge verwenden.

Aktionen

• Wählen Sie eine Namenskonvention für Community-Beiträge.
• Wenn es nicht die Standardeinstellung ist, dann dokumentieren Sie es.
  • Wenn Sie die Standardkonvention verwenden, dann sollte dieses Dokument ausreichen. Wiederholen Sie es nicht. Sie können darauf verweisen.
  • Andernfalls informieren Sie die Benutzer über benutzerdefinierte Konventionen in der Dokumentation des Projekts „contribute“ oder „create modules“.
• Empfehlen Sie auch die Verwendung zusätzlicher Metadaten, wie z. B. Klassifikatoren und Schlüsselwörter.

Über die Wahl von Konventionen

• Neue Projekte sollten das Standard-Contrib-Muster wählen.
• Bestehende Projekte mit Community-Beiträgen sollten mit benutzerdefinierten Konventionen beginnen. Dann können sie Migrationen fördern.

  Das bedeutet, dass bestehende Community-Konventionen nicht geändert werden müssen. Aber sie sollten zumindest explizit dokumentiert werden.

Beispiel: „pyranha“ ist Ihr Projektname und Paketname. Sagen Sie den Mitwirkenden, dass

• pyranha-bezogene Distributionen das Schlüsselwort „pyranha“ verwenden sollten
• pyranha-bezogene Distributionen, die Vorlagen bereitstellen, sollten auch das Schlüsselwort „templates“ verwenden.
• Community-Beiträge sollten unter dem Namespace „pyranhacontrib“ veröffentlicht werden (d.h. verwenden Sie das Muster „pyranhacontrib.*“).

Wie prüft man die Verfügbarkeit von Namen?

Bevor Sie einen Projektnamen wählen, stellen Sie sicher, dass er nicht bereits an den folgenden Orten registriert ist

• PyPI
• das ist alles. PyPI ist der einzige offizielle Ort.

Sie könnten zum Beispiel auch an verschiedenen Orten wie beliebten Code-Hosting-Diensten nachschauen, aber denken Sie daran, dass PyPI der einzige Ort ist, an dem Sie sich für Namen in der Python-Community **registrieren** können.

Deshalb ist es wichtig, dass Sie Namen bei PyPI registrieren.

Stellen Sie auch sicher, dass die Namen der verteilten Pakete oder Module nicht bereits registriert wurden

• in der Python Standard Library.
• in Projekten bei PyPI. Es gibt derzeit keine Hilfestellung dafür. Beachten Sie, dass es umso einfacher ist, die Überprüfung, je mehr Projekte der Regel einen einzelnen Namen verwenden folgen.
• Sie können die Community fragen.

Die Regel einen einzelnen Namen verwenden hilft Ihnen auch, Kollisionen mit Paketnamen zu vermeiden: Wenn ein Projektname verfügbar ist, hat der Paketname gute Chancen, ebenfalls verfügbar zu sein.

Wie benennt man ein Projekt um?

Das Umbenennen eines Projekts ist möglich, aber denken Sie daran, dass dies einige Verwirrung stiften wird. Achten Sie daher besonders auf README und Dokumentation, damit die Benutzer verstehen, was passiert ist.

1. Zunächst einmal: **Entfernen Sie keine Legacy-Distributionen aus PyPI**. Denn einige Benutzer verwenden sie möglicherweise.
2. Kopieren Sie das Legacy-Projekt, ändern Sie dann die Namen (Projekt und Paket/Modul). Achten Sie mindestens auf
   • Packaging-Dateien,
   • Ordnernamen, die Quelldateien enthalten,
   • Dokumentation, einschließlich README,
   • Importanweisungen im Code.
3. Weisen Sie der neuen Distribution die Metadaten Obsoletes-Dist in der Datei setup.cfg zu. Siehe PEP 345 zu Obsolete-Dist und setup.cfg-Spezifikation.
4. Veröffentlichen Sie eine neue Version des umbenannten Projekts und veröffentlichen Sie sie dann.
5. Bearbeiten Sie das Legacy-Projekt
   • fügen Sie eine Abhängigkeit zum neuen Projekt hinzu,
   • entfernen Sie alles außer den Packaging-Elementen,
   • fügen Sie den Klassifikator Development Status :: 7 - Inactive im Setup-Skript hinzu,
   • veröffentlichen Sie eine neue Version.

Daher können Benutzer des Legacy-Pakets

• Legacy-Distributionen weiterhin in einer veralteten Version verwenden,
• können auf die letzte Version der Legacy-Distribution upgraden, die leer ist…
• … und laden automatisch die neue Distribution als Abhängigkeit des Legacy-Projekts herunter.

Benutzer, die das Legacy-Projekt entdecken, sehen, dass es inaktiv ist.

Wie wendet man Namensrichtlinien auf bestehende Projekte an?

Es gibt keine Verpflichtung für bestehende Projekte, umbenannt zu werden. Die Wahl liegt bei den Projektverfassern und Maintainern aus offensichtlichen Gründen.

Projektverfasser werden jedoch eingeladen

• zumindest Stand zur aktuellen Benennung.
• dann Planung und Förderung der Migration.
• optional tatsächlich bestehende Projekte oder verteilte Pakete/Module umbenennen.