Versionen

Ein zusätzlicher Schlüssel, versions, MUSS auf der obersten Ebene vorhanden sein, zusätzlich zu den Schlüsseln name, files und meta, die in PEP 691 definiert sind. Dieser Schlüssel MUSS eine Liste von Versionsstrings enthalten, die alle für dieses Projekt hochgeladenen Projektversionen angeben. Der Wert ist logisch eine Menge, und als solche darf er keine Duplikate enthalten, und die Reihenfolge der Werte ist nicht wichtig.

Alle in dem files-Schlüssel aufgeführten Dateien MÜSSEN mit einer der Versionen in dem versions-Schlüssel verknüpft sein. Der versions-Schlüssel KANN Versionen ohne zugehörige Dateien enthalten (um Versionen ohne hochgeladene Dateien darzustellen, falls der Server ein solches Konzept hat).

Beachten Sie, dass da Server möglicherweise „veraltete“ Daten aus der Zeit vor der Einführung von PEP 440 enthalten, Versionsstrings derzeit nicht als gültige PEP 440-Versionen vorgeschrieben werden können und daher nicht davon ausgegangen werden kann, dass sie nach den PEP 440-Regeln sortiert werden können. Server SOLLTEN jedoch, wo immer möglich, normalisierte PEP 440-Versionen verwenden.

Zusätzliche Dateiinformationen

Zwei neue Schlüssel werden dem files-Schlüssel hinzugefügt.

• size: Dieses Feld ist obligatorisch. Es MUSS eine Ganzzahl enthalten, die die Dateigröße in Bytes angibt.
• upload-time: Dieses Feld ist optional. Wenn vorhanden, muss es eine gültige ISO 8601 Datums-/Zeitzeichenfolge im Format yyyy-mm-ddThh:mm:ss.ffffffZ enthalten, die den Zeitpunkt der Hochladung der Datei in den Index darstellt. Wie durch den Suffix Z angegeben, muss die Upload-Zeit die UTC-Zeitzone verwenden. Der Bruchteil-Sekunden-Teil des Zeitstempels (der .ffffff-Teil) ist optional und kann, wenn vorhanden, bis zu 6 Ziffern Präzision enthalten. Wenn ein Server keine Upload-Zeitinformationen für eine Datei aufzeichnet, KANN er den Schlüssel upload-time weglassen.

Warum diese Daten nicht auch zur HTML API hinzufügen?

Es wäre möglich, die Daten zur HTML API hinzuzufügen, aber die überwiegende Mehrheit der Konsumenten dieser Daten bezieht sie wahrscheinlich derzeit von der PyPI JSON API und ist daher bereits daran gewöhnt, JSON zu parsen. Traditionelle Konsumenten der HTML API haben diese Daten bisher nie benötigt.

Impliziert dies, dass die HTML API veraltet ist?

Nein. Die FAQ von PEP 691 stellte klar, dass die HTML API nicht als veraltet gilt, und diese PEP ändert diese Position nicht. Clients, die auf die von dieser PEP eingeführten neuen Daten zugreifen möchten, müssen jedoch die JSON API verwenden, um sie zu erhalten. Und Indizes, die sie bereitstellen möchten, müssen das JSON-Format bedienen.

Ersetzt die Simple API die JSON- und XML-RPC-APIs von Warehouse?

Wo immer möglich, sollten Clients die Simple API gegenüber den JSON- oder XML-RPC-APIs bevorzugen, da erstere standardisiert ist und von jedem Index erwartet werden kann, während letztere exklusiv für das Warehouse-Projekt sind.

Diese PEP bringt die Simple API zwar näher an den Stand, die JSON API ersetzen zu können, es gibt jedoch keine formelle Richtlinie, dass die Simple API alle Funktionen der bestehenden Warehouse APIs replizieren wird. Vorgeschlagene Ergänzungen zur Simple API werden weiterhin nach ihren individuellen Vorzügen geprüft, und die Anforderung, dass die API für den primären Anwendungsfall des Auffindens von Dateien für ein Projekt einfach und schnell sein muss, wird die entscheidende Überlegung bleiben.

Warum keine anderen Datumsformate zulassen?

Der ISO 8601-Standard ist komplex, und es scheint wenig Sinn darin zu geben, Clients zu zwingen, sich damit auseinanderzusetzen. Das Standardbibliotheksmodul datetime bietet Methoden zum Parsen von ISO 8601-Zeichenfolgen, aber es ist möglich, dass Benutzer auf Indexdaten zugreifen möchten, *ohne* Python zu verwenden (z. B. die Ausgabe von curl in jq umleiten). Ein einzelnes, gut definiertes Format erleichtert dies und hat keine signifikanten Nachteile.

Was passiert, wenn Dateigrößen zu groß für eine JSON-Zahl sind?

Der JSON-Standard schreibt nicht vor, wie Zahlen zu interpretieren sind. Python kann beliebig lange Ganzzahlen in einer JSON-Datei lesen und schreiben, daher sollte dies für in Python geschriebenen Code kein Problem darstellen. Nicht-Python-Implementierungen müssen möglicherweise darauf achten, große Ganzzahlen korrekt zu behandeln, aber dies wird nicht als signifikantes Problem erwartet.

Warum keine PEP 440-Versionen vorschreiben?

Zum Zeitpunkt der Erstellung dieser PEP enthielt und lieferte PyPI immer noch Projekte und Dateien mit „Legacy“-Versionen. Die Anforderung von PEP 440-Versionen würde es PyPI unmöglich machen, diese Spezifikation zu befolgen und gleichzeitig den vorhandenen Inhalt zu liefern.

Idealerweise wird die Simple Index API zu einem zukünftigen Zeitpunkt aktualisiert, um PEP 440-Versionen zu verlangen, und diese Spezifikation wird dann entsprechend aktualisiert. Diese Änderung muss jedoch mit bestehenden Indexanbietern, einschließlich PyPI, koordiniert werden, um nicht konforme Projekte und/oder Dateien abzuschaffen und zu entfernen.

Warum keinen Wert für „neueste Version“ bereitstellen?

Für PEP 440-Versionen ist dies für den Client einfach genug zu tun (mit der Bibliothek packaging, latest = max(Version(s) for s in proj["versions"])). Für nicht standardmäßige Versionen gibt es keine klar definierte Reihenfolge, und Clients müssen entscheiden, welche Regel für ihre Bedürfnisse geeignet ist. Das Erzwingen, dass der Server einen Wert für die neueste Version liefert, entzieht dem Client die Wahl.

Server, die ein explizites Konzept dafür haben, welche Version die „neueste“ ist und die nicht aus den dem Client zur Verfügung stehenden Daten berechnet werden kann, können einen nicht standardmäßigen, mit einem Unterstrich versehenen Schlüssel bereitstellen, um diese Informationen bei Bedarf an den Client zu übermitteln.