Zusammenfassung

Diese PEP schlägt einen standardisierten Satz von index-gelieferten Projektstatusmarkern sowie einen Mechanismus zur Übermittlung dieser Marker in den HTML- und JSON-Simple-Indizes vor.

Rationale und Motivation

Der „Status“ eines Projekts ist ein wichtiges Metadatum, das durch das Wachstum der Größe und Komplexität des Python-Packaging-Ökosystems immer wichtiger wird. Der Projektstatus (oder Proxys wie die jüngste Aktivität) ist nützlich, um festzustellen, ob ein Projekt gepflegt wird oder anderweitig für den Konsum geeignet ist.

Python-Packaging hat mindestens drei verschiedene Mechanismen zur Kommunikation des „Status“ eines Projekts

1. Distributionspakete können Trove-Klassifikatoren in ihren Metadaten enthalten, wie ursprünglich in PEP 301 spezifiziert. Die Liste der unterstützten Klassifikatoren wird von der PyPA gepflegt und enthält die Hierarchie der Development Status. Zum Beispiel kann eine Distribution den Klassifikator Development Status :: 7 - Inactive enthalten, um anzuzeigen, dass das Projekt der Distribution inaktiv ist.

   Trove-Klassifikatoren sind flexibel, aber sie haben auch erhebliche Einschränkungen: Sie sind maschinenlesbar und werden auf Indizes wie PyPI gerendert, erfordern aber auch, dass der Maintainer eine oder mehrere neue Distributionen hochlädt, jedes Mal, wenn er den Entwicklungsstatus seines Projekts aktualisieren möchte. Darüber hinaus können ältere Distributionen, da Distributionen im Python-Packaging-Ökosystem de facto unveränderlich sind, ihre Klassifikatoren nicht aktualisieren lassen, um den aktuellen Status des Projekts widerzuspiegeln.

2. Indizes können Distributionen und Releases als „yanked“ markieren, wie ursprünglich in PEP 592 spezifiziert. Yanked-Distributionen werden bei der Abhängigkeitsauflösung nicht berücksichtigt.

   Wenn eine Distribution yanked wurde, wird sie im HTML-Index mit data-yanked und im JSON-Index mit yanked: bool | str markiert. Zusätzlich werden Indizes wie PyPI yanked-Distributionen standardmäßig ausblenden und sie mit einem Hinweis rendern, wenn der Benutzer sie direkt aufruft.

   Yanking ist maschinenlesbar wie Trove-Klassifikatoren, aber zweckgebunden statt universell: Benutzer können einen Freitextgrund für das Yanking einer bestimmten Distributionsdatei angeben, aber die Semantik des Yankings ist festgelegt, und es kann keine zuverlässige Rückschließung des Projektstatus durch eine Maschine basierend auf diesem Freitextgrund erfolgen.

3. PyPI selbst hat Projektstatus, die für das gesamte Projekt (d.h. alle Releases und Distributionen) gelten. Projektstatus haben sowohl vom Maintainer als auch vom Index-Administrator kontrollierbare Zustände
   • PyPI-Administratoren können ein Projekt „unter Quarantäne stellen“. Quarantäne verhält sich wie ein verstärktes Yanking: Das gesamte Projekt bleibt während der Quarantäne deinstallierbar, und nur ein Administrator kann es wieder aus der Quarantäne entfernen.
   • Projekteigentümer können ein Projekt „archivieren“. Das Archivieren eines Projekts deaktiviert das Hochladen neuer Releases und Distributionen für dieses Projekt, hat aber ansonsten keine Auswirkungen auf die Möglichkeit, ein Projekt herunterzuladen.

   Projektstatus sind prinzipiell maschinenlesbar, werden aber derzeit nicht über PyPIs APIs verfügbar gemacht. Stattdessen rendert PyPI Projektstatus auf der benutzerorientierten (d.h. nicht-indexbezogenen) Webseite jedes Projekts.

Zusammenfassend lässt sich sagen, dass es mehrere Möglichkeiten gibt, den „Status“ eines Projekts im Python-Packaging zu kommunizieren. Keine davon erfüllt jedoch die vier gewünschten Eigenschaften. Es gibt keinen aktuellen Projektstatusindikator, der maschinenlesbar, allgemein (d.h. mehr als einen möglichen Zustand vermittelnd), index-agnostisch ist und für das gesamte Projekt gilt, anstatt pro Release oder pro Distribution.

Diese PEP schlägt die Übernahme der PyPI-Projektstatus als index-agnostischen Mechanismus vor, der alle vier Bedingungen erfüllt.

Spezifikation

Diese PEP spezifiziert zwei Aspekte: einen Satz von Projektstatusmarkern und deren Darstellung in den standardmäßigen HTML- und JSON-Indizes.

 <!DOCTYPE html>
 <html>
   <head>
     <meta name="pypi:repository-version" content="1.4">
     <meta name="pypi:project-status" content="quarantined">
     <meta name="pypi:project-status-reason" content="the project is haunted">
     <title>Links for sampleproject</title>
   </head>
   <body>
     <h1>Links for sampleproject</h1>
   </body>
 </html>

 {
   "meta": {
     "api-version": "1.4"
   },
   "project-status": {
     "status": "quarantined",
     "reason": "the project is haunted"
   },
   "alternate-locations": [],
   "files": [],
   "name": "sampleproject",
   "versions": [
     "1.2.0",
     "1.3.0",
     "1.3.1",
     "2.0.0",
     "3.0.0",
     "4.0.0"
   ]
 }

Zukünftige Überlegungen

Diese PEP definiert nur vier Projektstatusmarker: aktiv, archiviert, unter Quarantäne gestellt und veraltet.

Zukünftige PEPs (oder PyPA-Standardisierungsprozesse) können bei Bedarf zusätzliche Projektstatusmarker definieren. Zukünftige Statusmarker können eine Erhöhung der Metadatenversion erfordern, es sei denn, es wird eine zukünftige Metadatenänderung vorgenommen, um „offene“ Statusmarker zu ermöglichen (d.h. wo Indizes und Installer nicht unbedingt eine einzige gemeinsame Liste von zulässigen Status haben).

Wie in dieser PEP spezifiziert, sind Projektstatusmarker „nackt“, d.h. sie vermitteln keine zusätzlichen benutzergesteuerten Metadaten (wie z.B. eine Erklärung für die Archivierung eines Projekts).

Eine zukünftige PEP kann wählen, den Projektstatusmechanismus um benutzergesteuerte Metadaten zu erweitern, ähnlich dem Freitext, der während des Release-Yankings erlaubt ist.

Sicherheitsimplikationen

Diese PEP identifiziert keine positiven oder negativen Sicherheitsauswirkungen im Zusammenhang mit der Hinzufügung von Projektstatusmarkern.

Wie man das lehrt

Die Aufklärung der Python-Community über diese PEP hat zwei Aspekte

• Gewöhnliche Paket-Maintainer müssen über ihre Fähigkeit informiert werden, Projektstatusmarker zu setzen, z. B. um ihre Downstreams zu informieren, dass ein Projekt archiviert oder veraltet ist.

  Wenn diese PEP angenommen wird, werden die Autoren dieser PEP mit PyPI über geeignete, auf den Maintainer ausgerichtete Dokumentation und Kommunikation koordinieren, einschließlich Blogbeiträgen zur Funktionsankündigung und Aktualisierungen der Benutzerdokumentation von PyPI.

• Installer- und Index-Maintainer müssen über die neuen Projektstatusmarker und deren Interpretation informiert werden.

  Wenn diese PEP angenommen wird, werden die Autoren dieser PEP die Implementierung auf PyPI durchführen und als Referenzimplementierung für andere Indizes dienen.

  Diese PEP schreibt keine Änderungen im Installer-Verhalten vor. Wenn diese PEP jedoch angenommen wird, werden die Autoren dieser PEP mit den Maintainern beliebter Installer (z. B. pip) koordinieren, um ihnen zu helfen, zu bestimmen, inwieweit sie Projektstatus anzeigen möchten.

Abgelehnte Ideen

{
  "meta": {
    "api-version": "1.4"
  },
  "_project-status": "quarantined",
  "alternate-locations": [],
  "files": [],
  "name": "sampleproject",
  "versions": [
    "1.2.0",
    "1.3.0",
    "1.3.1",
    "2.0.0",
    "3.0.0",
    "4.0.0"
  ]
}

Urheberrecht

Dieses Dokument wird in die Public Domain oder unter die CC0-1.0-Universal-Lizenz gestellt, je nachdem, welche Lizenz permissiver ist.