Zusammenfassung

Diese PEP schlägt die Hinzufügung einer Methode zur Versionierung der einfachen API vor, damit Clients feststellen können, welche Features der einfachen API ein bestimmtes Repository unterstützt.

Begründung

Bei der Weiterentwicklung der einfachen API möchten Clients feststellen können, welche Features das Repository unterstützt. Derzeit gibt es keinen Mechanismus dafür, außer dem Versuch, neue Features zu erkennen, indem man die Daten in den Antworten betrachtet und sieht, ob ein bestimmtes Feature verwendet wird.

Dies funktioniert für eine moderne Version eines Clients recht gut, um festzustellen, ob das Repository alle gewünschten Features unterstützt, aber es sagt einer älteren Version des Clients nichts darüber, dass das Repository Features unterstützt, die sie möglicherweise nicht versteht, und es erlaubt keine Nachrichten, die darauf hinweisen, dass die Ausgabe des Repositorys möglicherweise nicht richtig verstanden wird.

Ein Beispiel für ein solches Szenario war die schrittweise Einführung von python-requires-Metadaten. Während bestehende Clients das Repository weiterhin erfolgreich nutzen konnten, fehlte ihnen die Fähigkeit, diese neuen Daten zu verstehen, die ihr Verhalten beeinflusst hätten, um eine bessere Datei für Endbenutzer auszuwählen.

Übersicht

Diese PEP schlägt die Aufnahme eines Meta-Tags in die Antworten jeder erfolgreichen Anfrage an eine Seite der einfachen API vor, die ein Namensattribut „pypi:repository-version“ und einen Inhalt hat, der eine PEP 440-kompatible Versionsnummer ist. Diese wird weiter eingeschränkt, NUR Major.Minor zu sein, und keine der zusätzlichen Features, die von PEP 440 unterstützt werden.

Dies würde wie folgt aussehen:

<meta name="pypi:repository-version" content="1.0">

Bei der Interpretation der Repository-Version

• Die Erhöhung der Hauptversion wird verwendet, um eine abwärtsinkompatible Änderung zu signalisieren, bei der bestehende Clients nicht mehr erwartet werden, die API sinnvoll nutzen zu können.
• Die Erhöhung der Nebenversion wird verwendet, um eine abwärtskompatible Änderung zu signalisieren, bei der bestehende Clients immer noch erwartet werden, die API sinnvoll nutzen zu können.

Es liegt im Ermessen zukünftiger PEPs, was genau eine abwärtsinkompatible bzw. kompatible Änderung darstellt, über die allgemeine Empfehlung hinaus, dass bestehende Clients die API weiterhin „sinnvoll“ nutzen können, und kann das Hinzufügen, Ändern oder Entfernen bestehender Features umfassen.

Es ist die Erwartung dieser PEP, dass die Hauptversion niemals erhöht wird und zukünftige größere API-Entwicklungen einen anderen Mechanismus zur API-Entwicklung nutzen würden. Die Hauptversion ist jedoch enthalten, um Verwechslungen mit zukünftigen Versionen zu vermeiden (z. B. eine hypothetische einfache API v2, die unter /v2/ leben würde, die aber verwirrend wäre, wenn die Repository-Version auf eine Version >= 2 gesetzt wäre).

Diese PEP setzt die aktuelle API-Version auf „1.0“ und erwartet, dass zukünftige PEPs, die die einfache API weiterentwickeln, die Nebenversionsnummer erhöhen.

Abgelehnte Ideen

Urheberrecht

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