Zusammenfassung

Diese PEP schlägt die Möglichkeit vor, einen bestimmten Dateidownload in einem einfachen Repository als „yanked“ (zurückgezogen) zu markieren. Das Zurückziehen einer Datei ermöglicht es Autoren, eine Datei effektiv zu löschen, ohne die Funktionalität für Benutzer zu beeinträchtigen, die eine bestimmte Version fest angepinnt haben.

Sie ändert auch die kanonische Quelle für die einfache API des Repositorys in das Referenzdokument Simple Repository API.

Motivation

Immer wenn ein Projekt feststellt, dass eine bestimmte Veröffentlichung auf PyPI fehlerhaft sein könnte, möchte es oft verhindern, dass weitere Benutzer unwissentlich diese Version verwenden. Die offensichtliche Lösung, die vorhandene Datei aus einem Repository zu löschen, würde jedoch Benutzer brechen, die Best Practices befolgt und eine bestimmte Version des Projekts angepinnt haben.

Dies bringt Projekte in eine Zwickmühle, in der neue Projekte diese bekannte fehlerhafte Version herunterladen könnten, aber wenn sie etwas unternehmen, um dies zu verhindern, brechen sie bereits bestehende Projekte, die sie verwenden.

Durch die Möglichkeit, eine Datei „zurückzuziehen“, sie aber dennoch für Benutzer verfügbar zu machen, die sie explizit anfordern, können Projekte die schlimmsten Brüche mildern und gleichzeitig sicherstellen, dass Projekte, die die zugrunde liegenden Probleme umgangen haben oder nicht auf sie gestoßen sind, weiterhin funktionieren.

Eines der Hauptszenarien, in denen dies passieren kann, ist das Einstellen der Unterstützung für eine bestimmte Python-Version. Die Metadaten python-requires ermöglichen das Einstellen der Unterstützung für eine Python-Version auf eine Weise, die für Benutzer, die diese Python-Version noch verwenden, nicht störend ist. Ein häufiger Fehler ist jedoch, diesen Metadatenanteil wegzulassen oder zu vergessen, ihn zu aktualisieren. Wenn dieser Fehler gemacht wurde, hat ein Projekt wirklich nur drei Optionen:

• Verhindern Sie die Installation dieser Version durch einen Mechanismus (derzeit ist der einzige Mechanismus die vollständige Löschung der Veröffentlichung).
• Veröffentlichen Sie die funktionierende Version erneut mit einer höheren Versionsnummer und veröffentlichen Sie dann die Version, die die Unterstützung eingestellt hat, mit einer noch höheren Versionsnummer und den korrekten Metadaten erneut.
• Tun Sie nichts und dokumentieren Sie, dass Benutzer dieser älteren Python-Version diese Veröffentlichung manuell ausschließen müssen.

Mit dieser PEP können Projekte die erste Option wählen, jedoch mit einem Mechanismus, der die Welt für Benutzer, die das Projekt derzeit erfolgreich nutzen, weniger wahrscheinlich beeinträchtigt.

Spezifikation

Links in der einfachen Repository-API **MÜSSEN** ein Attribut data-yanked haben, das entweder keinen Wert hat oder einen beliebigen String als Wert hat. Das Vorhandensein eines data-yanked-Attributs **SOLLTE** so interpretiert werden, dass die von diesem speziellen Link angesprochene Datei „zurückgezogen“ wurde und im Allgemeinen nicht von einem Installer ausgewählt werden sollte, außer unter bestimmten Umständen.

Der Wert des data-yanked-Attributs, falls vorhanden, ist ein beliebiger String, der den Grund für das Zurückziehen der Datei darstellt. Tools, die die einfache Repository-API verarbeiten, **KÖNNEN** diesen String Endbenutzern anzeigen.

Das Zurückziehungsattribut ist nicht unveränderlich, sobald es gesetzt ist, und kann in Zukunft widerrufen werden (und nach dem Widerruf auch wieder gesetzt werden). Daher **MÜSSEN** API-Benutzer damit umgehen können, dass eine zurückgezogene Datei „ent-zurückgezogen“ (und sogar erneut zurückgezogen) wird.

Abgelehnte Ideen

Eine frühere, undokumentierte Version der einfachen Repository-API hatte versionsspezifische Seiten wie /simple/<project>/<version>/. Würden wir diese zurückbringen, könnten zurückgezogene Dateien nur auf diesen Seiten und nicht auf der seitenlosen Seite überhaupt erscheinen. Dies würde jedoch die Cache-Fähigkeit der einfachen API drastisch reduzieren und sich direkt auf unsere Fähigkeit auswirken, sie für den gesamten eingehenden Datenverkehr zu skalieren.

Eine frühere Iteration dieser PEP hatte das Attribut data-yanked als booleschen Wert. Es wurde jedoch entschieden, dass die Ermöglichung eines Strings sowohl die Implementierung vereinfachte als auch eine zusätzliche allgemeine Funktionalität bot, die es Projekten ermöglichte, einen Mechanismus anzugeben, *warum* sie eine Veröffentlichung zurückziehen.

Ein anderer Vorschlag war, eine bestimmte Syntax im beliebigen String zu reservieren, um es uns zu ermöglichen, den Standard in Zukunft zu entwickeln, falls wir dies jemals benötigen sollten. Da wir jedoch in Zukunft zusätzliche Attribute hinzufügen können, wurde diese Idee verworfen und stattdessen bevorzugt, zusätzliche Attribute zu verwenden, falls jemals Bedarf entsteht.

Hinweise zur Warehouse/PyPI-Implementierung

Während diese PEP das Zurückziehen auf Dateiebene implementiert, liegt dies größtenteils an der Form der einfachen Repository-API und ist keine spezifische Entscheidung, die von dieser PEP getroffen wurde.

In Warehouse wird die Benutzererfahrung in Bezug auf das Zurückziehen oder Ent-Zurückziehen einer gesamten Veröffentlichung implementiert, anstatt als Operation auf einzelnen Dateien, die dann über die API als zurückgezogene einzelne Dateien ausgesetzt werden.

Andere Repository-Implementierungen können wählen, diese Funktion auf andere Weise oder gar nicht auszuliefern.

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.