Zusammenfassung

Dieses PEP spezifiziert, wie Namen von Distribution Extras beim Vergleich normalisiert werden sollen. Dies verhindert, dass Tools entweder einen Extra-Namen nicht finden oder versehentlich mit einem unerwarteten Namen übereinstimmen.

Motivation

Die Kernmetadatenspezifikation Provides-Extra besagt, dass ein Extra-Name "ein gültiger Python-Bezeichner sein muss". PEP 508 spezifiziert, dass der Wert eines extra Markers nach dem ersten Zeichen einen Buchstaben, eine Ziffer oder eines der Zeichen ., - oder _ enthalten darf. Es gibt keine weitere PyPA-Spezifikation, die beschreibt, wie Extra-Namen für den Vergleich geschrieben oder normalisiert werden sollen. Aufgrund der Menge des bestehenden verpackungsbezogenen Codes ist es wichtig, die aktuellen Praktiken der Community zu bewerten und sich auf eine zu einigen, die die meisten bestehenden Codes nicht bricht und etwas ist, dem Toolautoren zustimmen können.

Das Problem, dass kein einheitlicher Standard existiert, wurde durch eine erste Diskussion aufgeworfen, die feststellte, dass das Extra adhoc-ssl von pip 22 nicht gleich dem Namen adhoc_ssl war.

Begründung

PEP 503 spezifiziert, wie Distributionsnamen normalisiert werden

re.sub(r"[-_.]+", "-", name).lower()

Dies fasst jede Sequenz der Zeichen -, _ und . zu einem einzigen - zusammen. Zum Beispiel werden --- . und __ alle zu nur - konvertiert. Dies erzeugt gemäß der Kernmetadatenspezifikation 2.2 für Extra-Namen **keinen** gültigen Python-Bezeichner.

Setuptools 60 führt eine Normalisierung durch mittels

re.sub(r'[^A-Za-z0-9-.]+', '_', name).lower()

Die Verwendung eines Unterstrichs/_ unterscheidet sich von der Verwendung eines Bindestrichs/- in PEP 503, und es werden auch Zeichen normalisiert, die außerhalb der von PEP 508 erlaubten Zeichen liegen. Sequenzen von . und - werden im Gegensatz zu PEP 503 **nicht** zu einem _ normalisiert, z.B. bleibt .. gleich. Anzumerken ist, dass dies inkonsistent mit dem Docstring dieser Funktion ist, der angibt, dass alle nicht-alphanumerischen Zeichen (einschließlich - und .) normalisiert und zusammengefasst werden.

Für pip 22 ist sein "Verhalten bei der Normalisierung von Extras ziemlich kompliziert und erratisch" [pip-erratic] und daher wird seine Verwendung nicht berücksichtigt.

Spezifikation

Beim Vergleich von Extra-Namen MÜSSEN Tools die verglichenen Namen gemäß den in PEP 503 für Namen beschriebenen Semantiken normalisieren.

re.sub(r"[-_.]+", "-", name).lower()

Die Spezifikation der Kernmetadaten wird aktualisiert, so dass die erlaubten Namen für Provides-Extra mit dem übereinstimmen, was PEP 508 für Namen spezifiziert. Dies bringt die Extra-Namensgebung mit der des Feldes Name in Einklang. Da dies die Gültigkeit von Namen ändert, wird dies zu einer Erhöhung der Kernmetadaten-Version auf 2.3 führen.

Für Tools, die Kernmetadaten schreiben, MÜSSEN sie die Extra-Namen in ihrer normalisierten Form ausgeben. Dies gilt für das Feld Provides-Extra und den Extra-Marker, wenn dieser im Feld Requires-Dist verwendet wird.

Tools, die Metadaten generieren, MÜSSEN einen Fehler ausgeben, wenn ein Benutzer zwei oder mehr Extra-Namen angibt, die zum selben Namen normalisiert würden. Tools, die Metadaten generieren, MÜSSEN einen Fehler ausgeben, wenn ein ungültiger Extra-Name gemäß der angegebenen Kernmetadatenversion bereitgestellt wird. Wenn die Metadaten eines Projekts eine ältere Kernmetadatenversion angeben und der Name mit neueren Kernmetadatenversionen ungültig wäre, SOLLTEN Tools den Benutzer warnen. Tools SOLLTEN Benutzer warnen, wenn ein ungültiger Extra-Name gelesen wird, und den Namen ignorieren, um Mehrdeutigkeiten zu vermeiden. Tools KÖNNEN stattdessen einen Fehler ausgeben, wenn sie einen ungültigen Namen lesen, falls sie dies wünschen.

Abwärtskompatibilität

Der Umstieg auf die Normalisierung nach PEP 503 und die Akzeptanz von Namen gemäß PEP 508 ermöglicht es, dass alle vorhandenen, gültigen Namen weiterhin gültig bleiben.

Basierend auf Recherchen, die eine Sammlung von Wheels auf PyPI untersuchten [pypi-results], ist das Risiko von Namenskonflikten bei Extras auf 73 Fälle beschränkt, wenn alle Extra-Namen auf PyPI betrachtet werden, ob gültig oder nicht (nicht nur diejenigen innerhalb eines einzelnen Pakets), während bei der Betrachtung **nur** gültiger Namen nur 3 Konflikte auftreten.

• dev-test: dev_test, dev-test, dev.test
• dev-lint: dev-lint, dev.lint, dev_lint
• apache-beam: apache-beam, apache.beam

Indem Tools, die Kernmetadaten schreiben, gezwungen werden, nur den normalisierten Namen aufzuzeichnen, sollte das Problem bestehender, ungültiger Extra-Namen im Laufe der Zeit abnehmen.

Sicherheitsimplikationen

Es ist möglich, dass für eine Distribution, die widersprüchliche Extra-Namen hat, ein Tool Abhängigkeiten installiert, die irgendwie die Sicherheit des Systems schwächen. Dies ist nur hypothetisch und falls es vorkommen würde, wäre es wahrscheinlich eher ein Sicherheitsproblem für die Distributionen, die solche Extra-Namen angeben, als für die Distribution, die sie zusammenzieht.

Wie man das lehrt

Dies sollte für Benutzer im täglichen Gebrauch transparent sein. Es liegt an den Tools, Benutzer zu informieren/zu stoppen, wenn sie Extra-Namen auswählen, die Konflikte verursachen.

Referenzimplementierung

Es wird keine Referenzimplementierung bereitgestellt, abgesehen vom obigen Code, aber die Erwartung ist, dass das packaging-Projekt eine Funktion in seinem Modul packaging.utils bereitstellen wird, die die Normalisierung von Extra-Namen implementiert. Es wird auch die Extra-Namensvergleiche entsprechend implementieren. Schließlich, falls das Projekt jemals die Möglichkeit erhält, Metadaten auszugeben, wird es auch dieses PEP implementieren.

Migrationsplan

Es besteht das Risiko, dass ein Build-Tool Kernmetadaten erstellt, die Version 2.3 und damit dieses PEP entsprechen, aber von einem Tool konsumiert werden, das von diesem PEP nicht weiß (falls dieses Tool versucht, eine Kernmetadatenversion zu lesen, die es nicht direkt unterstützt). In einem solchen Fall besteht die Möglichkeit, dass ein Benutzer ein Extra mit einem nicht normalisierten Namen angibt, der zuvor funktionierte, jetzt aber fehlschlägt.

Daher sollten Verbraucher dieses PEP stärker priorisiert werden als Produzenten, damit Benutzer benachrichtigt werden können, dass sie Extra-Namen angeben, die nicht normalisiert sind (und daher in Zukunft fehlschlagen könnten).

Abgelehnte Ideen

Offene Fragen

N/A

Urheberrecht

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