Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 658 – Metadaten der Distribution über die Simple Repository API bereitstellen

Autor:
Tzu-ping Chung <uranusjr at gmail.com>
Sponsor:
Brett Cannon <brett at python.org>
PEP-Delegate:
Donald Stufft <donald at stufft.io>
Discussions-To:
Discourse thread
Status:
Akzeptiert
Typ:
Standards Track
Thema:
Packaging
Erstellt:
10-Mai-2021
Post-History:
10-Mai-2021
Resolution:
Discourse-Nachricht
Inhaltsverzeichnis

Zusammenfassung

Diese PEP schlägt vor, ein Anker-Tag hinzuzufügen, um die METADATA-Datei aus Distributionen in der PEP 503 „simple“ Repository API bereitzustellen. Ein Attribut data-dist-info-metadata wird eingeführt, um anzuzeigen, dass die Datei einer gegebenen Distribution unabhängig heruntergeladen werden kann.

Motivation

Paketmanagement-Workflows, die durch neuere Tools populär geworden sind, erhöhen den Bedarf, Distributionsmetadaten zu inspizieren, ohne die Distribution installieren zu wollen, und mehrere Distributionen eines Projekts herunterzuladen, um sie anhand ihrer Metadaten auszuwählen. Das bedeutet, dass am Ende viel heruntergeladene Daten verworfen werden, was ineffizient ist und zu einer schlechten Benutzererfahrung führt.

Begründung

Tools haben Methoden erforscht, um die Downloadgröße durch teilweises Herunterladen von Wheels mittels HTTP-Range-Anfragen zu reduzieren. Dies fügt jedoch zusätzliche Laufzeitanforderungen an den Repository-Server hinzu. Es entstehen auch zusätzliche Overhead, da eine separate Anfrage erforderlich ist, um die Dateiliste des Wheels abzurufen, um den korrekten Offset zum Abrufen der Metadaten-Datei zu finden. Daher ist es wünschenswert, dass der Server die Metadaten-Datei im Voraus extrahiert und als unabhängige Datei bereitstellt, um die Notwendigkeit zusätzlicher Anfragen und ZIP-Inspektionen zu vermeiden.

Die von der Core Metadata Specification [core-metadata] definierte Metadaten-Datei wird direkt von Repositories bereitgestellt, da sie die notwendigen Informationen für gängige Anwendungsfälle enthält. Die Metadaten dürfen nur für standardkonforme Distributionen wie Wheels [wheel] und sdists [sdist] bereitgestellt werden und müssen identisch mit der kanonischen Metadaten-Datei der Distribution sein, wie z. B. die METADATA-Datei eines Wheels im Verzeichnis .dist-info [dist-info].

Ein HTML-Attribut am Ankerlink der Distributionsdatei ist erforderlich, um anzuzeigen, ob ein Client die separat bereitgestellte Metadaten-Datei auswählen kann. Das Attribut wird auch verwendet, um den Hash des Metadaten-Inhalts für die clientseitige Verifizierung bereitzustellen. Das Fehlen des Attributs zeigt an, dass kein separater Metadateneintrag für die Distribution verfügbar ist, entweder aufgrund des Inhalts der Distribution oder mangels Repository-Unterstützung.

Spezifikation

In der Projektseite eines einfachen Repositories **kann** jeder Anker-Tag, der auf eine Distribution verweist, ein Attribut data-dist-info-metadata haben. Die Anwesenheit des Attributs zeigt an, dass die von dem Anker-Tag repräsentierte Distribution eine Core Metadata-Datei **enthalten muss**, die nicht geändert wird, wenn die Distribution verarbeitet und/oder installiert wird.

Wenn ein Attribut data-dist-info-metadata vorhanden ist, **muss** das Repository die Core Metadata-Datei der Distribution zusammen mit der Distribution bereitstellen, wobei an den Dateinamen der Distribution .metadata angehängt wird. Zum Beispiel würde sich die Core Metadata einer Distribution, die unter /files/distribution-1.0-py3.none.any.whl bereitgestellt wird, unter /files/distribution-1.0-py3.none.any.whl.metadata befinden. Dies ähnelt der Art und Weise, wie PEP 503 den Speicherort der GPG-Signaturdatei spezifiziert.

Das Repository **sollte** den Hash der Core Metadata-Datei als Wert des Attributs data-dist-info-metadata unter Verwendung der Syntax <hashname>=<hashvalue> bereitstellen, wobei <hashname> der kleingeschriebene Name der verwendeten Hash-Funktion und <hashvalue> der hex-kodierte Digest ist. Das Repository **kann** true als Wert des Attributs verwenden, wenn kein Hash verfügbar ist.

Abwärtskompatibilität

Wenn einem Anker-Tag das Attribut data-dist-info-metadata fehlt, wird erwartet, dass Tools zu ihrem aktuellen Verhalten zurückkehren, nämlich die Distribution herunterzuladen, um die Metadaten zu inspizieren.

Ältere Tools, die das neue Attribut data-dist-info-metadata nicht unterstützen, werden erwartet, das Attribut zu ignorieren und ihr aktuelles Verhalten beizubehalten, nämlich die Distribution herunterzuladen, um die Metadaten zu inspizieren. Dies ähnelt der Funktionsweise, wie frühere data- Attributerweiterungen von bestehenden Tools erwartet werden.

Abgelehnte Ideen

Metadaten-Inhalt auf der Projektseite einfügen

Da Tools im Allgemeinen nur Abhängigkeitsinformationen aus einer Distribution benötigen, zusätzlich zu dem, was bereits auf der Projektseite verfügbar ist, wurde vorgeschlagen, dass Repositories die Informationen direkt auf der Projektseite einfügen können, wie z. B. das Attribut data-requires-python, das in PEP 503 spezifiziert ist.

Dieser Ansatz wurde verworfen, da eine Distribution beliebig lange Listen von Abhängigkeiten (einschließlich erforderlicher und optionaler) enthalten kann, und es ist unklar, ob die Aufnahme der Informationen für jede Distribution eines Projekts zu Nettoeinsparungen führen würde, da die Informationen für die meisten Distributionen im Allgemeinen unnötig werden. Durch die separate Bereitstellung der Metadaten kann die Leistung besser geschätzt werden, da die Datennutzung proportionaler zur Anzahl der inspizierten Distributionen sein wird.

Weitere Dateien in der Distribution bereitstellen

Es wurde vorgeschlagen, das gesamte Verzeichnis .dist-info als separaten Teil bereitzustellen, anstatt nur die Metadaten-Datei. Das Bereitstellen mehrerer Dateien in einer Einheit über HTTP erfordert jedoch eine erneute Archivierung separat, nachdem sie vom Repository-Server aus der ursprünglichen Distribution extrahiert wurden, und es gibt keine aktuellen Anwendungsfälle für andere Dateien als METADATA, wenn die Distribution selbst nicht installiert werden soll.

Es sollte auch angemerkt werden, dass der hier gewählte Ansatz nicht ausschließt, dass in Zukunft weitere Dateien eingeführt werden, unabhängig davon, ob wir sie zusammen oder einzeln bereitstellen möchten.

URL der Metadaten-Datei auf der Projektseite explizit angeben

Eine frühe Version dieses Entwurfs schlug vor, die URL der Metadaten-Datei in das Attribut data-dist-info-metadata einzufügen. Aber die Leute empfinden es für die Auffindbarkeit als besser, wenn das Repository die Metadaten-Datei an einem bestimmten Ort bereitstellt. Der aktuelle Ansatz hat auch den zusätzlichen Vorteil, dass die Projektseite kleiner wird.

Referenzen

Source: https://github.com/python/peps/blob/main/peps/pep-0658.rst

Last modified: 2025-02-01 08:55:40 GMT