Feld für Wheel-Version-Metadaten zum Kernmetadaten hinzufügen

Derzeit spezifiziert der Wheel 1.0 PEP, PEP 427, dass Wheel-Dateien eine WHEEL Metadatendatei enthalten müssen, die die Version der Wheel-Spezifikation enthält, der die Datei entspricht. PEP 427 schreibt vor, dass Installer bei der Installation eines Wheels mit einer höheren Nebenversion als unterstützt eine Warnung ausgeben und bei der Installation von Wheels mit einer höheren Hauptversion als vom Installer unterstützt abbrechen **MÜSSEN**. Dies stellt sicher, dass Benutzer keine ungültigen Installationen von Wheels erhalten, die Installer nicht ordnungsgemäß installieren können.

Resolver schließen jedoch derzeit keine Wheels mit einer inkompatiblen Wheel-Version aus. Es gibt derzeit auch keine Möglichkeit für einen Resolver, die Version eines Wheels zu überprüfen, ohne das Wheel direkt herunterzuladen. Um die Filterung von Wheel-Versionen für Resolver zu vereinfachen, **MUSS** die Wheel-Version in der relevanten Metadatendatei (derzeit METADATA) enthalten sein. Dies ermöglicht es Resolvern, die Wheel-Version effizient über die PEP 658 Metadaten-API zu überprüfen, ohne die Datei .dist-info/WHEEL herunterladen und inspizieren zu müssen.

Zu diesem Zweck wird ein neues Feld, Wheel-Version, zur Core Metadata Specification hinzugefügt. Dieses Feld ist nur einmal verwendbar und muss dieselbe Version enthalten, die als Wheel-Version in der Datei WHEEL oder einer zukünftigen Ersetzungsdatei, die Metadaten über die Wheel-Datei definiert, angegeben ist. Wenn Wheel-Version in der Metadatendatei fehlt, **MUSS** das Tool die Hauptversion der Wheel-Datei als 1 ableiten.

Wheel-Version **Darf NICHT** in Metadatendateien von Quellcodeverteilungen (PKG-INFO) enthalten sein. Wenn ein Tool Wheel-Version in einer Metadatendatei einer Quellcodeverteilung findet, **sollte** es einen Fehler ausgeben.

Wheel-Version **KANN** in der Metadatendatei für Wheels der Version 1 enthalten sein, aber für Wheels der Version 2 oder höher **MUSS** die Metadatendatei Wheel-Version enthalten. Dies erzwingt, dass zukünftige Revisionen der Wheel-Spezifikation darauf vertrauen können, dass Resolver inkompatible Wheels überspringen, indem sie das Feld Wheel-Version überprüfen. Build-Backends wird empfohlen, Wheel-Version in allen Wheels einzuschließen, die sie generieren, unabhängig von der Version.

Installer **sollten** die Metadatendatei in einem Wheel während der Installation unverändert kopieren. Dies verhindert die Notwendigkeit, die RECORD Datei zu aktualisieren, was ein fehleranfälliger Prozess ist. Tools, die installierte Kernmetadaten lesen, **sollten nicht** davon ausgehen, dass das Feld vorhanden ist, da andere Installationsformate es weglassen können.

Beim Installieren eines Wheels **MÜSSEN** Installer die folgenden Schritte ausführen:

1. Prüfen Sie, ob die Werte von Wheel-Version sowohl in der Kernmetadatendatei als auch in der Wheel-Metadatendatei übereinstimmen. Wenn sie nicht übereinstimmen, **MUSS** der Installer die Installation abbrechen. Kein Wert hat Vorrang.
2. Prüfen Sie, ob der Installer mit Wheel-Version kompatibel ist. Wenn Wheel-Version fehlt, nehmen Sie an, dass die Version 1.0 ist. Warnen Sie, wenn die Nebenversion höher ist, brechen Sie ab, wenn die Hauptversion höher ist. Dieses Verfahren ist identisch mit dem in PEP 427 beschriebenen.
3. Fahren Sie mit der Installation fort, wie in der Spezifikation des Binary Distribution Format beschrieben.

Resolver-Verhalten bezüglich Wheel-Version

Resolver **MÜSSEN** beim Auswählen eines zu installierenden Wheels die Wheel-Version eines Kandidaten-Wheels überprüfen und inkompatible Wheel-Dateien ignorieren. Ohne diese Dateien zu ignorieren, könnten ältere Installer ein Wheel auswählen, das eine für diesen Installer nicht unterstützte Wheel-Version verwendet, und den Installer gemäß PEP 427 zum Abbruch zwingen. Durch das Überspringen inkompatibler Wheel-Dateien werden Benutzer keine Installationsfehler sehen, wenn ein Projekt eine neue Wheel-Hauptversion übernimmt. Wie bereits in PEP 427 spezifiziert, **MÜSSEN** Installer abbrechen, wenn ein Benutzer versucht, direkt ein inkompatibles Wheel zu installieren. Wenn ein Resolver bei der Auflösung von Paketen aus mehreren Indizes zwei Wheels desselben Distributions- und Versionsnamens findet, sollte der Resolver das Wheel mit der höchsten kompatiblen Version bevorzugen.

Während das Obige Benutzer vor unerwarteten Problemen schützt, können Benutzer eine neue Veröffentlichung einer Distribution verpassen, wenn ihr Installer die in der Veröffentlichung verwendete Wheel-Version nicht unterstützt. Stellen Sie sich vor, in Zukunft veröffentlicht ein Paket 3.0 Wheel-Dateien. Nachgelagerte Benutzer sehen nicht, dass eine neue Version verfügbar ist, wenn ihre Installer nur 2.x Wheels unterstützen. Daher **sollten** Installer eine Warnung ausgeben, wenn sie bei der Auflösung von Paketen auf ein inkompatibles Wheel stoßen und dieses überspringen.

Erste Hauptversionserhöhung muss die Dateierweiterung ändern

Leider überprüfen bestehende Resolver die Kompatibilität von Wheels nicht, bevor sie diese als Installationskandidaten auswählen. Bis eine Mehrheit der Benutzer auf Installer aktualisiert, die die Wheel-Kompatibilität ordnungsgemäß prüfen, ist es unsicher, Wheels einer neuen Hauptversion zu veröffentlichen, die bestehende Resolver auswählen könnten. Es könnte bis zu vier Jahre dauern, bis die Mehrheit der Benutzer aktuelle Resolver hat, basierend auf aktuellen Daten zur Nutzung von PyPI-Installern (siehe Anhang: Analyse der Installer-Nutzung auf PyPI für Details). Um Experimente und eine schnellere Einführung von 2.0 Wheels zu ermöglichen, schlägt dieser PEP eine Änderung der Dateierweiterung des Wheel-Dateiformats von .whl auf .whlx für alle zukünftigen Wheel-Versionen vor. Beachten Sie, dass x in whlx der Buchstabe „x“ ist und nicht die Hauptversion des Wheels angibt. Die Änderung des Namens der Erweiterung löst das anfängliche Übergangsproblem, dass 2.0 Wheels Benutzer mit bestehenden Installern, die keine Wheel-Version-Prüfungen implementieren, beeinträchtigen würden. Durch die Verwendung einer anderen Dateierweiterung können 2.0 Wheels sofort auf PyPI hochgeladen werden, und Benutzer können die neuen Funktionen sofort ausprobieren. Benutzer mit älteren Installern ignorieren diese neuen Dateien einfach.

Eine abgelehnte Alternative wäre, die .whl-Erweiterung beizubehalten, aber die Veröffentlichung von Wheel 2.0 auf PyPI zu verzögern. Mehr dazu finden Sie unter Abgelehnte Ideen.

Empfohlenes Build-Backend-Verhalten mit neuen Wheel-Formaten

Build-Backends wird empfohlen, das kompatibelste Wheel basierend auf den vom Projekt verwendeten Funktionen zu generieren. Wenn ein Wheel beispielsweise keine symbolischen Links verwendet und eine solche Funktion in Wheel 5.0 eingeführt wurde, könnte das Build-Backend ein Wheel der Version 4.0 generieren. Andererseits sollen einige Funktionen standardmäßig übernommen werden. Wenn beispielsweise Wheel 3.0 eine bessere Komprimierung einführt, möchte das Build-Backend diese Funktion möglicherweise standardmäßig aktivieren, um die Wheel-Größe und die Downloadleistung zu verbessern.

Einschränkungen für zukünftige Wheel-Revisionen

Obwohl es schwierig ist zu wissen, welche zukünftigen Funktionen für das Wheel-Format geplant sind, ist es wichtig, dass bestimmte Kompromisse eingegangen werden.

Wheel-Dateien **MÜSSEN** nach der Installation mit importlib.metadata der Python-Standardbibliothek für alle unterstützten CPython-Versionen kompatibel bleiben. Zum Beispiel **MUSS** der Ersatz von .dist-info/METADATA durch eine JSON-formatierte Metadatendatei eine Migration über mehrere Hauptversionen erfolgen, wobei eine Version die neue JSON-Datei neben dem bestehenden E-Mail-Header-Format einführt und eine andere zukünftige Version die E-Mail-Header-Metadatendatei entfernt. Die Version zur Entfernung von .dist-info/METADATA **MUSS** ebenfalls erst nach der letzten CPython-Version, die keine Unterstützung für die neue Datei hatte, deren End-of-Life erreicht hat, übernommen werden. Dies stellt sicher, dass Code, der importlib.metadata verwendet, mit Wheel-Hauptversionsrevisionen nicht fehlschlägt.

Wheel-Dateien **MÜSSEN** als äußeres Containerformat ZIP-Dateien bleiben. Zusätzlich **MUSS** das Metadatenverzeichnis .dist-info unkomprimiert im Stammverzeichnis des Archivs platziert werden, damit das Entpacken der Wheel-Datei ein normales .dist-info-Verzeichnis ergibt, das alle Metadaten für das Wheel enthält. Zukünftige Wheel-Revisionen **KÖNNEN** das Layout, die Komprimierung und andere Attribute von Nicht-Metadaten-Komponenten eines Wheels, wie z. B. Daten und Code, ändern. Dies stellt sicher, dass zukünftige Wheel-Revisionen mit Tools, die mit Paketmetadaten arbeiten, kompatibel bleiben, während Verbesserungen bei der Speicherung von Code im Wheel, wie z. B. die Einführung von Komprimierung, ermöglicht werden.

Paket-Tooling **Darf NICHT** davon ausgehen, dass der Inhalt und das Format der Wheel-Datei für zukünftige Wheel-Hauptversionen über die oben genannten Einschränkungen für Metadatenordnerinhalte und äußeres Containerformat hinaus gleich bleiben. Neuere Wheel-Hauptversionen können beispielsweise Dateinamenskomponenten wie den Build-Tag oder den Plattform-Tag hinzufügen oder entfernen. Daher obliegt es dem Tooling, die Metadaten für die Wheel-Version zu überprüfen, bevor es versucht, ein Wheel zu installieren.

Schließlich **DÜRFEN** zukünftige Wheel-Revisionen keine Komprimierungsformate verwenden, die nicht in der CPython-Standardbibliothek der neuesten Version enthalten sind. Wheels, die mit einem neuen Komprimierungsformat generiert werden, sollten als Anforderung für mindestens die erste veröffentlichte Version von CPython gekennzeichnet werden, die das neue Komprimierungsformat unterstützt, unabhängig von der Python-API-Kompatibilität des Codes innerhalb des Wheels.

Das Wheel-Format ist perfekt und muss nicht geändert werden

Das Wheel-Format existiert seit über 10 Jahren, und in dieser Zeit haben sich Python-Pakete stark verändert. Es ist viel häufiger, dass Pakete Rust- oder C-Erweiterungsmodule enthalten, was die Größe der Pakete erhöht. Bessere Komprimierung, wie z. B. lzma oder zstd, könnte viel Zeit und Bandbreite für PyPI und seine Benutzer sparen. Kompatibilitätstags können die breite Palette von Hardware, die heute zur Beschleunigung von Python-Code verwendet wird, nicht ausdrücken und auch keine Informationen zur Kompatibilität von gemeinsam genutzten Bibliotheken kodieren. Um diese Probleme zu lösen, ist eine Weiterentwicklung des Wheel-Paketformats notwendig.

Wheel-Format-Änderungen sollten an CPython-Releases gebunden sein

Ich glaube nicht, dass die Anbindung von Wheel-Revisionen an CPython-Releases vorteilhaft ist. Der Hauptvorteil ist die Vorhersehbarkeit der Übernahme neuer Wheels - Benutzer mit dem neuesten CPython erhalten das neueste Paketformat! Diese Wahl hat jedoch mehrere Probleme. Erstens verlangsamt die Anbindung des neuen Formats an das neueste CPython die Übernahme erheblich. Benutzer von LTS-Versionen von Linux mit älteren Python-Installationen können ihre pip in einer virtuellen Umgebung aktualisieren, aber die Python-Version nicht so einfach aktualisieren. Während einige Änderungen am Wheel-Format notwendigerweise an CPython-Änderungen gebunden sein müssen, wie z. B. das Hinzufügen neuer Komprimierungsformate oder die Änderung des Metadatenformats, müssen viele Änderungen nicht an die Python-Version gebunden sein, wie z. B. symbolische Links, erweiterte Kompatibilitätstags und neue Formate, die vorhandene Komprimierungsformate in der Standardbibliothek verwenden. Zusätzlich werden Wheels über mehrere verschiedene Sprachimplementierungen hinweg verwendet, die hinter der CPython-Version zurückbleiben. Es scheint unfair, ihre Benutzer aufgrund der Python-Version von einer Funktion auszuschließen. Schließlich schlägt dieser PEP zwar nicht vor, die Wheel-Version an CPython-Releases zu binden, aber ein zukünftiger PEP könnte dies jederzeit tun, sodass diese Entscheidung nicht in diesem PEP getroffen werden muss.

Verwenden Sie weiterhin .whl als Dateierweiterung

Obwohl die Beibehaltung der Erweiterung .whl aus vielen Gründen reizvoll ist, birgt sie mehrere Probleme, die schwer zu überwinden sind. Erstens würden aktuelle Installer ein neues Wheel immer noch auswählen und das Paket nicht installieren können. Darüber hinaus könnte der Dateiname eines Wheels nicht geändert werden, ohne bestehende Installer zu beeinträchtigen, die ein bestimmtes Wheel-Dateinamenformat erwarten. Während die aktuelle Dateinamen-Spezifikation für Wheels für die aktuelle Nutzung ausreichend ist, machen die optionalen Build-Tags in der Mitte des Dateinamens jede Erweiterung mehrdeutig (d. h. foo-0.3-py3-none-any-fancy_new_tag.whl würde als Build-Tag py3 analysiert werden). Dies schränkt Änderungen an Informationen, die im Wheel-Dateinamen gespeichert sind, ein.

Speichern Sie die Hauptversion des Wheels in der Dateierweiterung (.whl2)

Die Speicherung der Wheel-Hauptversion in der Dateierweiterung hat mehrere Vorteile. Zum einen entfällt die Notwendigkeit, das Metadatenfeld Wheel-Version einzuführen, da Installer einfach nach Dateierweiterung filtern könnten. Dies würde auch zukünftige parallele Pakete ermöglichen. Die Änderung der Erweiterung für Wheels bei jeder Hauptversion hat jedoch einige Nachteile. Erstens muss die im WHEEL-File gespeicherte Version mit der Dateierweiterung übereinstimmen, und dies müsste von den Installern überprüft werden. Darüber hinaus assoziieren viele Systeme Dateitypen anhand der Dateierweiterung (z. B. ausführbare Zuordnungen, verschiedene Web-Caching-Software), und diese müssten bei jeder veröffentlichten Version aktualisiert werden. Darüber hinaus ist ein Teil der Zerbrechlichkeit der aktuellen Wheel-Spezifikation, dass so viele Metadaten im Dateinamen gespeichert sind. Dateinamen sind nicht gut geeignet, um strukturierte Daten zu speichern. Die Abkehr von der Kodierung von Informationen im Dateinamen sollte ein Ziel zukünftiger Wheel-Revisionen sein.

Eine weitere Möglichkeit besteht darin, die Dateierweiterung zu verwenden, um das äußere Containerformat (d. h. eine ZIP-Datei, die .dist-info enthält) vom inneren Wheel-Versionsformat zu trennen. Dies könnte jedoch zu Verwirrung führen, wenn die Dateierweiterung und die innere Wheel-Version auseinanderlaufen. Wenn ein Installer aufgrund eines inkompatiblen Wheel 3.0, wie aus den Wheel-Metadaten ermittelt, einen Fehler ausgibt, werden einige Benutzer durch den Unterschied zur Dateierweiterung .whl2 verwirrt sein.

Wheel 2.0 sollte das äußere Containerformat ändern

Da Wheel 2.0 die Erweiterung von Wheel-Dateien ändert, ist dies die beste Gelegenheit, das äußere Containerformat zu ändern. Die Kompatibilität muss nicht mit einer anderen Dateierweiterung beibehalten werden, die Tools erst lesen müssen. Der Hauptanwendungsfall für ein anderes äußeres Komprimierungsformat wäre eine bessere Komprimierung. Zum Beispiel könnte der äußere Container in ein Zstandard Tarfile, .tar.zst, geändert werden, das schneller dekomprimiert und kleinere Wheels erzeugt. Es gibt jedoch mehrere praktische Probleme damit. Erstens ist Zstandard kein Teil der Python-Standardbibliothek, daher müssten reine Python-Packaging-Tools eine Erweiterung zum Entpacken dieser Wheels mitliefern. Dies könnte zu Kompatibilitätsproblemen für einige Plattformen führen, auf denen Erweiterungsmodule nicht einfach zu installieren sind. Darüber hinaus könnte eine zukünftige Wheel-Revision immer ein neues Layout von Nicht-Metadaten-Dateien einführen, das ein .tar.zst innerhalb des bestehenden ZIP-basierten Formats verwendet.

Schließlich ist es keine gute Idee, das Wheel-Dateiformat auf einmal zu stark zu ändern. Das Ziel dieses PEP ist es, die Weiterentwicklung der Spezifikation zu erleichtern, und ein Teil der Begründung für die Erleichterung der Wheel-Weiterentwicklung ist die Vermeidung von "Alles auf einmal"-Änderungen. Die Änderung des äußeren Dateiformats für Wheels würde erfordern, die Art und Weise, wie Paketmetadaten nicht nur entdeckt, sondern auch installiert werden, neu zu schreiben.

Warum Spezifikation von Wheel 2.0 nicht in diesem PEP?

Es gibt **viele** Funktionen, die als Teil von Wheel 2.0 enthalten sein könnten, aber dieser PEP deckt sie nicht ab. Das Ziel dieses PEP ist es, eine Kompatibilitätsgeschichte für das Wheel-Dateiformat zu definieren. Änderungen, die sich nicht auf die Kompatibilität von Wheel-Versionen beziehen, müssen nicht in diesem PEP enthalten sein und sollten in Folge-PEPs eingeführt werden, die neue Wheel-Funktionen definieren.

Sollten Indizes die doppelte Veröffentlichung für die erste Migration unterstützen?

Da .whl und .whlx sich im Dateinamen unterscheiden, könnten sie nebeneinander auf Paketindizes wie PyPI hochgeladen werden. Dies hat einige schöne Vorteile, wie z. B. Dual-Support für ältere und neuere Installer, sodass Benutzer, die die neuesten Funktionen nutzen können, während Benutzer, die nicht aktualisieren, immer noch die neueste Version eines Pakets installieren können.

Es gibt jedoch viele Komplikationen. Sollten wir Wheel 2-Uploads für bestehende Wheel 1-only-Releases zulassen? Sollten wir Anforderungen an die nebeneinander veröffentlichten Wheels stellen, wie z. B.:

Sollten wir nur das Hochladen beider mit PEP 694 zulassen, der „atomare“ doppelte Veröffentlichung ermöglicht?