Zusammenfassung

Metadaten für Python-Pakete werden in der Distributionsdatei in einem Standardformat gespeichert, das in der Core Metadata Specification definiert ist. Für Quellcode-Distributionen gibt es jedoch, obwohl das Format der Daten definiert ist, traditionell viele Inkonsistenzen darin, welche Daten in der Quellcode-Distribution aufgezeichnet werden. Eine Diskussion dieses Problems finden Sie hier.

Infolgedessen können Metadaten-Konsumenten den Daten, die aus Quellcode-Distributionen verfügbar sind, nicht vertrauen und müssen die (kostspieligen) PEP 517 Build-Mechanismen verwenden, um Metadaten zu extrahieren.

Dieses PEP definiert einen Standard, der es Build-Backends ermöglicht, Paketmetadaten zuverlässig in der Quellcode-Distribution zu speichern und gleichzeitig die notwendige Flexibilität zu wahren, um Metadatenfelder zu handhaben, die zum Build-Zeitpunkt berechnet werden müssen.

Motivation

Es gibt eine Reihe von Problemen mit der Art und Weise, wie Metadaten derzeit in Quellcode-Distributionen gespeichert werden

• Die Details, wie Metadaten gespeichert werden sollen, sind, obwohl standardisiert, nicht leicht zu finden.
• Die Spezifikation erfordert eine alte Metadatenversion und wurde nicht im Einklang mit Änderungen an der Core Metadata Spec aktualisiert.
• Es gibt keine Möglichkeit in der Spezifikation, zwischen „dieses Feld wurde ausgelassen, da sein Wert erst zum Build-Zeitpunkt bekannt sein wird“ und „dieses Feld hat keinen Wert“ zu unterscheiden.
• Die Core Metadata Specification lässt die meisten Felder optional, was bedeutet, dass das vorherige Problem fast jedes Metadatenfeld betrifft.

Dieses PEP schlägt eine Aktualisierung der Metadatenspezifikation vor, um die Aufzeichnung von Feldern zu ermöglichen, die „später ausgefüllt“ werden sollen, und aktualisiert die Spezifikation für Quellcode-Distributionen, um zu klären, dass Backends sdist-Metadaten mit dieser Version der Spezifikation (oder einer neueren) aufzeichnen sollten.

Begründung

Dieses PEP ermöglicht es Projekten, Quellcode-Distributions-Metadatenwerte als „dynamisch“ zu definieren. In diesem Zusammenhang bedeutet die Aussage, dass ein Feld „dynamisch“ ist, dass der Wert zum Zeitpunkt der Erstellung der Quellcode-Distribution nicht festgelegt wurde. Dynamische Werte werden vom Build-Backend zum Zeitpunkt der Erstellung des Wheels bereitgestellt und könnten von Details der Build-Umgebung abhängen.

PEP 621 hat ein ähnliches Konzept von „dynamischen“ Werten, die „später ausgefüllt“ werden, und daher wählen wir hier analog denselben Begriff.

Spezifikation

Dieses PEP definiert die Beziehung zwischen Metadatenwerten, die in einer Quellcode-Distribution angegeben sind, und den entsprechenden Werten in daraus erstellten Wheels. Es verlangt von Build-Backends, Felder, die *nicht* einfach unverändert von der sdist auf das Wheel kopiert werden, klar zu kennzeichnen.

Darüber hinaus macht dieses PEP das Dokument PyPA Specifications zum kanonischen Speicherort für die Spezifikation des Quellcode-Distributionsformats (indem es die Informationen aus PEP 517 und aus diesem PEP sammelt).

Ein neues Feld, Dynamic, wird zur Core Metadata Specification hinzugefügt. Dieses Feld kann mehrfach verwendet werden und darf den Namen eines anderen Core-Metadatenfeldes enthalten.

Wenn es im Metadaten einer Quellcode-Distribution gefunden wird, gelten die folgenden Regeln:

1. Wenn ein Feld *nicht* als Dynamic gekennzeichnet ist, dann MUSS der Wert des Feldes in jedem aus der sdist erstellten Wheel mit dem Wert in der sdist übereinstimmen. Wenn das Feld nicht in der sdist vorhanden ist und nicht als Dynamic gekennzeichnet ist, dann darf es NICHT im Wheel vorhanden sein.
2. Wenn ein Feld als Dynamic gekennzeichnet ist, kann es jeden gültigen Wert in einem aus der sdist erstellten Wheel enthalten (einschließlich keiner Anwesenheit).
3. Backends DÜRFEN ein Feld NICHT als Dynamic kennzeichnen, wenn sie feststellen können, dass es aus Daten generiert wurde, die sich zum Build-Zeitpunkt nicht ändern werden.

Backends KÖNNEN den berechneten Wert für ein Feld, das sie als Dynamic kennzeichnen, in einer Quellcode-Distribution aufzeichnen. Konsumenten DÜRFEN diesen Wert jedoch NICHT als kanonisch behandeln, können ihn aber als Hinweis verwenden, wie der endgültige Wert in einem Wheel aussehen könnte.

In jedem anderen Kontext als einer Quellcode-Distribution weist die Kennzeichnung eines Feldes als Dynamic darauf hin, dass der Wert zum Zeitpunkt des Wheel-Builds generiert wurde und möglicherweise nicht mit dem Wert in der sdist (oder in anderen Builds des Projekts) übereinstimmt. Backends sind jedoch nicht verpflichtet, diese Information aufzuzeichnen, und Konsumenten DÜRFEN NICHT annehmen, dass das Fehlen einer Dynamic-Kennzeichnung irgendeine Bedeutung hat, außer in einer Quellcode-Distribution.

Die Felder Name und Version DÜRFEN NICHT als Dynamic gekennzeichnet werden.

Da es ein neues Metadatenfeld hinzufügt, aktualisiert dieses PEP das Core-Metadatenformat auf Version 2.2.

Quellcode-Distributionen SOLLTEN die neueste Version der Core-Metadatenspezifikation verwenden, die zum Zeitpunkt ihrer Erstellung verfügbar war.

Build-Backends werden dringend ermutigt, Felder nur dann als Dynamic zu kennzeichnen, wenn es absolut notwendig ist, und Projekte zu ermutigen, Backend-Funktionen zu vermeiden, die die Verwendung von Dynamic erfordern. Projekte sollten stattdessen Umgebungsvariablenmarker bei statischen Werten bevorzugen, um sich an Details des Installationsortes anzupassen.

Abwärtskompatibilität

Da dieser Vorschlag die Core-Metadatenversion inkrementiert, ist er mit bestehenden Quellcode-Distributionen kompatibel, die eine ältere Metadatenversion verwenden werden. Tools können feststellen, ob eine Quellcode-Distribution mit diesem PEP konform ist, indem sie die Metadatenversion überprüfen.

Sicherheitsimplikationen

Da diese Spezifikation rein für die Speicherung von Daten dient, die öffentlich verfügbar sein sollen, gibt es keine Sicherheitsauswirkungen.

Wie man das lehrt

Dies ist ein Datenspeicherformat für Projektmetadaten und wird daher in der Regel nicht für Endbenutzer sichtbar sein. Es besteht daher keine Notwendigkeit, Benutzern die Verwendung des Formats beizubringen. Entwickler, die auf die Metadaten verweisen möchten, können die Details in den PyPA Specifications finden.

Abgelehnte Ideen

1. Anstatt Felder als Dynamic zu kennzeichnen, sollten Felder als dynamisch angenommen werden, es sei denn, sie sind explizit als Static gekennzeichnet.

   Dies ist logisch äquivalent zum aktuellen Vorschlag, impliziert aber, dass dynamische Felder die Norm sind. Packaging-Tools können in Gegenwart von Metadaten, die als statisch bekannt sind, viel effizienter sein, daher wählt das PEP, dynamische Felder zur Ausnahme zu machen und Backends zu verlangen, die Kennzeichnung eines Feldes als dynamisch zu „opt-in“ zu machen.

   Darüber hinaus werden in Zukunft, wenn immer mehr Metadaten statisch werden, Metadatendateien zunehmend Static-Deklarationen enthalten, wenn Dynamisch der Standard ist.

2. Anstatt eines Dynamic-Feldes, fügen Sie einen speziellen Wert hinzu, der angibt, dass ein Feld „noch nicht definiert“ ist.

   Auch dies ist logisch äquivalent zum aktuellen Vorschlag. Es macht das „dynamisch sein“ zu einer expliziten Wahl, erfordert aber einen speziellen Wert. Da einige Felder beliebigen Text enthalten können, ist die Wahl eines solchen Wertes etwas umständlich (obwohl sie praktisch wahrscheinlich kein Problem darstellt). Es scheint nicht genügend Vorteile für diesen Ansatz zu geben, um ihn anstelle des vorgeschlagenen Mechanismus zu verwenden.

3. Sonderbehandlung von Requires-Python.

   Frühe Entwürfe des PEP benötigten eine spezielle Diskussion über Requires-Python, da das Fehlen von Umgebungsvariablenmarkern für dieses Feld bedeutete, dass es schwierig sein könnte, es als statisch zu kennzeichnen. Die endgültige Form des PEP benötigt dies nicht mehr, da die Idee einer Whitelist von Feldern, die als dynamisch erlaubt sind, fallen gelassen wurde.

4. Beschränken Sie die Verwendung von Dynamic auf eine minimale „Whitelist“ von zulässigen Feldern.

   Dieser Ansatz war aufgrund der dynamischen Natur der Setuptools-Schnittstelle wahrscheinlich extrem schwierig für Setuptools, auf abwärtskompatible Weise zu implementieren. Stattdessen erlaubt der Vorschlag nun die meisten Felder dynamisch, ermutigt aber Backends, dynamische Werte zu vermeiden, es sei denn, sie sind unerlässlich.

Offene Fragen

Keine

Urheberrecht

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