Zusammenfassung

Diese PEP schlägt einen Mechanismus vor, mit dem Projekte, die auf pypi.org gehostet werden, Wheel-Artefakte sicher auf externen Websites außerhalb von PyPI hosten können. Diese PEP schlägt ausdrücklich *nicht* das externe Hosten von Projekten, Paketen oder deren Metadaten vor. Diese Funktionalität ist bereits durch das externe Hosten unabhängiger Paketindizes verfügbar. Da diese PEP nur einen Mechanismus bereitstellt, mit dem Projekte die Download-URL für spezifische freigegebene Wheel-Artefakte anpassen können, muss die Abhängigkeitsauflösung, wie sie bereits von gängigen Installer-Tools wie pip und uv implementiert ist, nicht geändert werden.

Diese PEP definiert, was in diesem Kontext als „sicher“ gilt, zusammen mit einem neuen Paket-Upload-Dateiformat namens .rim-Datei. Sie definiert, wie .rim-Dateien die Metadaten beeinflussen, die für die Simple Repository API eines Pakets in den Formaten HTML und JSON zurückgegeben werden, und wie traditionelle Wheels leicht in .rim-Dateien umgewandelt werden können.

PEP zurückgezogen

Diese PEP wurde von den Autoren am 31.01.2025 zurückgezogen. Unserer Einschätzung nach ist die Stimmung im Diskussionsforum, dass, obwohl die Probleme, die diese PEP zu lösen versucht, valide sind, die meisten Leute einen anderen Ansatz bevorzugen würden. Insbesondere ist unsere Einschätzung, dass die meisten Benutzer mehr Kontrolle über die Möglichkeit wünschen, mehrere Indizes anzugeben, wie diese Indizes miteinander interagieren und die Prioritäts- und Vertrauenszuweisungen für diese Indizes. Zum Beispiel könnten Lösungen wie PEP 766 einen besseren Weg nach vorn bieten. Bestehende Notfallmaßnahmen (z. B. Anfragen zur Erhöhung des PyPI-Limits und der Ansatz „wheel-stub“) sind in der Zwischenzeit ausreichend – wenn auch nicht ideal. Die Autoren bedanken sich bei allen, die zu der konstruktiven Diskussion beigetragen haben, und insbesondere bei denen, die ihre Unterstützung für diese PEP öffentlich und privat gezeigt haben.

Begründung

Der Python Package Index, gehostet unter https://pypi.org, legt Standardgrenzen für die Dateigröße von Upload-Artefakten (100 MiB) und die Gesamtgröße des Projekts (10 GiB) fest. Die meisten Projekte können im Laufe ihres Lebens problemlos innerhalb dieser Grenzen bleiben, auch nach Jahren des Uploads. Einige wenige Projekte sind an diese Grenzen gestoßen und haben sowohl Ausnahmen bei der Dateigröße als auch bei der Projektgröße erhalten, was es ihnen ermöglicht, weiterhin neue Releases hochzuladen, ohne drastischere Maßnahmen ergreifen zu müssen, wie z. B. das Entfernen von Dateien, die möglicherweise noch von Benutzern verwendet werden (z. B. durch Versions-Pins).

Eine verwandte Problemumgehung ist der Ansatz „wheel stub“, der einen indirekten Link zwischen PyPI und einem externen Drittanbieter-Paketindex bereitstellt, wo solche Einschränkungen vermieden werden können. Wheel-Stubs sind Quellcodeverteilungen (auch „sdists“ genannt), die ein PEP 517-Build-Backend verwenden, das anstelle der Umwandlung von Quellcode in ein Binär-Wheel eine Logik ausführt, um die URL für ein vorhandenes, extern gehostetes Wheel zu berechnen, das heruntergeladen und installiert werden soll. Dieser Ansatz funktioniert, verschleiert jedoch die Verbindung zwischen PyPI, dem sdist und dem extern gehosteten Wheel, da es keine Möglichkeit gibt, diese Informationen an pip oder ähnliche Tools weiterzugeben.

Spezifikation

Ein neuer Typ von hochladbarer Datei wird definiert, genannt „RIM“ (d. h. .rim) oder „Remote Installable Metadata“-Datei. Der Name erinnert an ein Rad, bei dem der Reifen entfernt wurde, und betont, dass .rim-Dateien leicht aus .whl-Dateien abgeleitet werden können. Der Prozess der Umwandlung eines .whl in ein .rim ist weiter unten beschrieben. Das Dateinamensformat entspricht exakt der Spezifikation des Wheel-Dateinamensformats, außer dass RIM-Dateien die Endung .rim verwenden. Das bedeutet, dass alle Tags, die zur Unterscheidung von .whl-Dateien verwendet werden, auch verschiedene .rim-Dateien unterscheiden, und somit bei der Abhängigkeitsauflösung, genau wie heute .whl-Dateien, verwendet werden können. In dieser Hinsicht sind .whl- und .rim-Dateien austauschbar.

Der Inhalt einer .rim-Datei ist *fast* identisch mit .whl-Dateien. Jedoch **MÜSSEN** .rim-Dateien nur das Verzeichnis .dist-info aus einem Wheel enthalten. Kein anderes übergeordnetes Datei- oder Verzeichnis ist in der .rim-Zip-Datei erlaubt. Das Verzeichnis .dist-info **MUSS** eine einzige zusätzliche Datei enthalten, zusätzlich zu den erlaubten in einem .whl-Datei .dist-info-Verzeichnis: eine Datei namens EXTERNAL-HOSTING.json.

Dies ist eine JSON-Datei, die die folgenden Schlüssel enthält

version

Dies ist die Dateiformatversion, die für diese PEP **MUSS** 1.0 sein.

owner

Dies **MUSS** den PyPI-Organisationsbesitzer dieser extern gehosteten Datei benennen, aus Gründen, die im Folgenden im Detail erläutert werden.

uri

Dies ist eine einzelne URL, die den Speicherort der physischen .whl-Datei angibt, die auf einer externen Website gehostet wird. Diese URL **MUSS** das https-Schema verwenden.

size

Dies ist ein ganzzahliger Wert, der die Größe in Bytes der physischen .whl-Datei auf dem Remote-Host beschreibt.

hashes

Dies ist ein Dictionary im Format, das in PEP 694 beschrieben wird, das verwendet wird, um sowohl den PEP 694 der physischen .whl-Datei zu erfassen, mit den gleichen Einschränkungen wie in dieser PEP vorgeschlagen. Da diese Hashes nach dem Hochladen auf PyPI unveränderlich sind, dienen sie als kritische Validierung dafür, dass das extern gehostete Wheel nicht beschädigt oder kompromittiert wurde.

Resilienz des externen Hostings

Eines der Hauptanliegen, das zur Rücknahme von PEP 438 in PEP 470 führte, war die potenzielle Verwirrung der Benutzer, wenn ein externer Index verschwand. Aus PEP 470:

Diese Verwirrung entsteht dadurch, dass Endbenutzer von Projekten nicht erkennen, ob ein Projekt auf PyPI gehostet wird oder ob es auf einen externen Dienst angewiesen ist. Dies äußert sich oft, wenn der externe Dienst ausfällt, PyPI aber nicht. Die Leute sehen, dass PyPI funktioniert und andere Projekte funktionieren, aber dieses eine spezielle Projekt nicht. Sie erkennen oft nicht, wen sie kontaktieren müssen, um dies zu beheben, oder welche Schritte sie unternehmen können.

Obwohl das Problem, dass ein externer Wheel-Hosting-Dienst ausfällt, von dieser PEP nicht direkt gelöst wird, gibt es mehrere Schutzmaßnahmen, um die potenzielle Belastung für PyPI-Administratoren erheblich zu reduzieren.

Diese PEP schlägt daher vor, dass

• Das externe Hosten von Wheels ist nur für Pakete erlaubt, die von Organisationskonten besessen werden. Externes Hosten ist eine einstellung für die gesamte Organisation.
• Organisationskonten erhalten nicht automatisch die Fähigkeit, Wheels extern zu hosten; diese Funktion **MUSS** von PyPI-Administratoren nach eigenem Ermessen explizit aktiviert werden. Da dies keine häufige Anfrage sein wird, erwarten wir nicht, dass der Aufwand auch nur annähernd so belastend ist wie die PEP 541-Lösungen, Anfragen zur Kontowiederherstellung oder sogar Anfragen zur Erhöhung der Datei-/Projektgröße. Anfragen zum externen Hosten werden auf die gleiche Weise behandelt wie diese Anfragen, d. h. über den PyPI GitHub Support Tracker.
• Organisationskonten, die externes Wheel-Hosting anfordern, **MÜSSEN** ihre eigene Support-Kontakt-URI registrieren, sei es eine mailto-URI für eine Kontaktadresse oder die URL zum Support-Tracker der Organisation. Eine solche Kontakt-URI ist für Organisationen optional, die sich nicht für externes Wheel-File-Hosting entscheiden.

In Kombination mit dem Schlüssel owner in der Datei EXTERNAL-HOSTING.json ermöglicht dies, dass Installer-Tools bei Downloadfehlern eindeutig von den PyPI-Support-Administratoren direkt an die Support-Administratoren der Organisation weitergeleitet werden können.

Obwohl die genauen Mechanismen zum Speichern und Abrufen dieser organisationsspezifischen Support-URL separat definiert werden, nehmen wir zum Beispiel an, dass ein Paket foo seine Wheel-Dateien extern auf https://foo.example.com <https://foo.example.com> hostet und dieser Host nicht mehr erreichbar wird. Wenn ein Installer-Tool versucht, das Wheel des Pakets foo herunterzuladen und zu installieren, schlägt der Download-Schritt fehl. Der Installer wäre dann in der Lage, PyPI abzufragen, um dem Endbenutzer eine nützliche Fehlermeldung anzuzeigen.

• Der Installer lädt die .rim-Datei herunter und liest den Schlüssel owner aus der Datei EXTERNAL-HOSTING.json innerhalb des .rim-Zip-Archivs.
• Der Installer fragt PyPI nach der Support-URI für den Organisationsbesitzer des extern gehosteten Wheels.
• Daraufhin würde eine informative Fehlermeldung angezeigt, z. B.:

  Die extern gehostete Wheel-Datei foo-....whl konnte nicht heruntergeladen werden. Bitte wenden Sie sich zur Hilfe an support@foo.example.com. Melden Sie dies nicht den PyPI-Administratoren.

Demontage von Wheels

Es ist im Allgemeinen sehr einfach, aus einer vorhandenen .whl-Datei eine .rim-Datei zu erstellen. Dies könnte effizient von einem PEP 518 Build-Backend mit einer zusätzlichen Kommandozeilenoption oder einem separaten Werkzeug erfolgen, das eine .whl-Datei als Eingabe nimmt und die zugehörige .rim-Datei erstellt. Um die Analogie zu vervollständigen, wird der Vorgang der Umwandlung eines .whl in ein .rim als „Dismounting“ (Demontage) bezeichnet. Die Schritte, die ein solches Werkzeug ausführen würde, sind:

• Akzeptieren der Quell-.whl-Datei, des Organisationsbesitzers des Pakets, der URL, unter der das .whl gehostet wird, und der Support-URI zur Meldung von Download-Problemen als Eingabe. Diese könnten tatsächlich in der pyproject.toml-Datei erfasst werden, aber diese Spezifikation liegt außerhalb des Umfangs dieser PEP.
• Entpacken Sie die .whl und erstellen Sie das .rim-Zip-Archiv.
• Lassen Sie aus der .rim-Datei jeden Pfad in der .whl weg, der **NICHT** im Verzeichnis .dist-info verwurzelt ist.
• Berechnen Sie den Hash der Quell-.whl-Datei.
• Fügen Sie die Datei EXTERNAL-HOSTING.json mit den oben beschriebenen JSON-Schlüsseln und -Werten zum .rim-Archiv hinzu.

Änderungen an Werkzeugen

Theoretisch sollten Installer-Tools keine Änderungen benötigen, da sie, wenn sie das herunterzuladende und zu installierende Wheel identifiziert haben, einfach die Download-URLs konsultieren, die von PyPIs Simple API zurückgegeben werden. In der Praxis können Tools wie pip und uv jedoch eingeschränkte Listen von Hosts haben, von denen sie Downloads zulassen, wie z. B. die eigene Domäne pythonhosted.org von PyPI.

In diesem Fall müssen solche Tools diese Einschränkungen lockern, aber die genaue Richtlinie dafür überlässt sich den Installer-Tools selbst. Beliebige Ansätze können implementiert werden, wie z. B. das Herunterladen der .rim-Datei und die Überprüfung der Metadaten in EXTERNAL-HOSTING.json, oder einfach das Vertrauen in externe Downloads für jedes Wheel mit einem übereinstimmenden Prüfsumme. Sie könnten auch PyPI nach dem Organisationsbesitzer und der Support-URI des Projekts abfragen, bevor sie dem Download vertrauen. Sie könnten den Benutzer warnen, wenn extern gehostete Wheel-Dateien angetroffen werden, und/oder die Verwendung einer Kommandozeilenoption zum Aktivieren zusätzlicher Download-Hosts erfordern. Jede dieser Überprüfungsrichtlinien könnte in Konfigurationsdateien gewählt werden.

Installer-Tools sollten wahrscheinlich auch bessere Fehlermeldungen liefern, wenn extern gehostete Wheels nicht heruntergeladen werden können, z. B. weil ein Host nicht erreichbar ist. Wie oben beschrieben, könnten solche Tools genügend Metadaten von PyPI abfragen, um klare und eindeutige Fehlermeldungen zu liefern, die Benutzer auf die externe Hosting-Support-E-Mail-Adresse oder den Issue-Tracker des Pakets verweisen.

Beschränkungen für externe Hosting-Dienste

Die folgenden Einschränkungen führen zu zuverlässigen und kompatiblen externen Wheel-Hosting-Diensten

• Externe Wheels **MÜSSEN** über HTTPS bedient werden, mit einem Zertifikat, das von Mozillas Stammzertifikatsspeicher signiert ist. Dies gewährleistet die Kompatibilität mit pip und uv. Zum Zeitpunkt der Erstellung verwendet pip 24.2 auf Python 3.10 oder neuer den Systemzertifikatsspeicher zusätzlich zum Mozilla-Speicher, der vom Drittanbieter-Paket certifi bereitgestellt wird. uv verwendet den Mozilla-Speicher, der von der webpki-roots-Kiste bereitgestellt wird, jedoch nicht den System-Speicher, es sei denn, das Flag --native-tls wird verwendet [1]. *Die PyPI-Administratoren können diese Anforderung in Zukunft ändern, aber die Kompatibilität mit gängigen Installern wird nicht beeinträchtigt.*
• Externe Wheel-Hosts **SOLLTEN** ein Content Delivery Network (CDN) verwenden, genau wie PyPI es tut.
• Externe Wheel-Hosts **MÜSSEN** sich zu einer stabilen URL für alle von ihnen gehosteten Wheels verpflichten.
• Extern gehostete Wheels **DÜRFEN NICHT** von einem externen Wheel-Host entfernt werden, es sei denn, die entsprechende .rim-Datei wurde zuvor von PyPI gelöscht, und **DÜRFEN NICHT** externe Wheels für "yanked" Releases entfernen.
• Externe Wheel-Hosts **MÜSSEN** HTTP Range Requests unterstützen.
• Externe Wheel-Hosts **SOLLTEN** das HTTP/2-Protokoll unterstützen.

Sicherheit

Mehrere Faktoren, wie in diesem Vorschlag beschrieben, sollten Sicherheitsbedenken bei extern gehosteten Wheels mindern, wie z. B.:

• Wheel-Datei-Prüfsummen **MÜSSEN** in .rim-Dateien enthalten sein und können nach dem Hochladen nicht mehr geändert werden. Da die auf PyPI gespeicherte Prüfsumme unveränderlich und erforderlich ist, ist es nicht möglich, eine externe Wheel-Datei zu fälschen, selbst wenn die besitzende Organisation die Kontrolle über ihre Hosting-Domäne verliert.
• Extern gehostete Wheels **MÜSSEN** über HTTPS bedient werden.
• Um extern gehostete Wheels bedienen zu können, **MÜSSEN** Organisationen von den PyPI-Administratoren genehmigt werden.

Wenn Benutzer Malware oder Schwachstellen in PyPI-gehosteten Projekten identifizieren, können sie dies nun über die Meldefunktionen für Malware auf PyPI melden, wie auch in diesem Blogbeitrag beschrieben. Derselbe Prozess kann zur Meldung von Sicherheitsproblemen in extern gehosteten Wheels verwendet werden, und derselbe Behebungsansatz sollte verwendet werden. Darüber hinaus, da Organisationen mit aktiviertem externem Hosting eine Support-Kontakt-URI bereitstellen **MÜSSEN**, kann diese URI in einigen Fällen verwendet werden, um das Sicherheitsproblem an die hostende Organisation zu melden. Eine solche organisationsweite Meldung ist für Malware nicht sinnvoll, könnte aber tatsächlich ein sehr nützlicher Weg sein, um Sicherheitslücken in extern gehosteten Wheels zu melden.

Abgelehnte Ideen

Mehrere Ideen wurden in Betracht gezogen und abgelehnt.

• Anforderung digitaler Signaturen auf extern gehosteten Wheel-Dateien, entweder zusätzlich zu oder anstelle von Hashes. Wir halten dies für unnötig, da die Prüfsummenanforderung ausreichen sollte, um zu validieren, dass die Metadaten auf PyPI für ein Wheel exakt mit dem heruntergeladenen Wheel übereinstimmen. Die zusätzliche Komplexität der Schlüsselverwaltung überwiegt jeden zusätzlichen Nutzen, den solche digitalen Signaturen mit sich bringen könnten.
• Hash-Überprüfung bei Uploads von .rim-Dateien. PyPI *könnte* überprüfen, ob der Hash in der hochgeladenen .rim-Datei mit dem extern gehosteten Wheel übereinstimmt, bevor es den Upload akzeptiert. Dies erfordert jedoch das Herunterladen des externen Wheels und die Durchführung der Prüfsumme, was auch impliziert, dass der Upload der .rim-Datei erst akzeptiert werden kann, nachdem diese externe .whl-Datei heruntergeladen und verifiziert wurde. Dies erhöht die PyPI-Bandbreite und verlangsamt die Upload-Abfrage, obwohl PEP 694 Entwurfs-Uploads diese Bedenken potenziell mildern könnten. Dennoch ist der Nutzen wahrscheinlich nicht die zusätzliche Komplexität wert.
• Regelmäßige Überprüfung der Download-URLs durch den Index. PyPI könnte versuchen, periodisch sicherzustellen, dass der externe Wheel-Host oder die externe .whl-Datei selbst noch verfügbar ist, z. B. über eine HTTP HEAD-Anfrage. Dies ist wahrscheinlich übertrieben und ohne Angabe der Dateiprüfsumme in der Antwort [2], bietet möglicherweise keinen großen zusätzlichen Nutzen.
• Diese PEP könnte es einer Organisation ermöglichen, alternative Download-Hosts bereitzustellen, sodass ein sekundärer verfügbar ist, falls der primäre ausfällt. Wir glauben, dass DNS-basierte Replikation eine weitaus bessere, bekannte Technik ist und wahrscheinlich ohnehin viel widerstandsfähiger ist.
• .rim-Datei-Ersetzung. Während .whl-Dateien bestehende .rim-Dateien ersetzen dürfen, solange a) die .rim-Datei nicht gelöscht oder zurückgezogen wurde, b) die Prüfsummen übereinstimmen, erlauben wir nicht das Ersetzen von .whl-Dateien durch .rim-Dateien, noch erlauben wir, dass eine .rim-Datei eine bestehende .rim-Datei überschreibt. Letzteres könnte eine Technik sein, um die Hosting-URL für ein extern gehostetes .whl zu ändern; wir halten dies jedoch nicht für eine gute Idee. Es gibt andere Möglichkeiten, eine externe Host-URL zu "reparieren", wie oben beschrieben, und wir möchten keine Massen-Neu-Uploads bestehender .rim-Dateien fördern.

Fußnoten

Urheberrecht

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