Zusammenfassung

Gemäß PEP 440 kann eine Distribution durch einen Namen und entweder eine Version oder eine direkte URL-Referenz identifiziert werden (siehe PEP440 Direct References). Nach der Installation werden der Name und die Version in den Projektmetadaten erfasst, aber derzeit gibt es keine Möglichkeit, Details der URL abzurufen, die verwendet wurde, als die Distribution durch eine direkte URL-Referenz identifiziert wurde.

Dieser Vorschlag definiert zusätzliche Metadaten, die vom Installation-Frontend zur installierten Distribution hinzugefügt werden sollen und den direkten URL-Ursprung für die Verwendung durch Konsumenten erfassen, die die Datenbank der installierten Pakete untersuchen (siehe PEP 376).

Motivation

Die ursprüngliche Motivation dieses PEP war es, Werkzeugen mit einer „freeze“-Operation zu ermöglichen, eine Python-Umgebung wiederherstellbar zu machen, und dies in einem breiteren Spektrum von Situationen.

Insbesondere entstand der PEP aus dem Wunsch, pip issue #609 zu lösen: d. h. das Verhalten von pip freeze im Beisein von Distributionen, die aus direkten URL-Referenzen installiert wurden, zu verbessern. Er folgt einem Thread auf discuss.python.org über den besten Vorgehensweg zur Umsetzung.

Begründung

Dieser PEP spezifiziert eine neue Metadaten-Datei direct_url.json im Verzeichnis .dist-info einer installierten Distribution.

Die spezifizierten Felder sind ausreichend, um das Quellarchiv und die von pip unterstützten VCS-URLs zu reproduzieren. Sie sind auch ausreichend, um PEP440 Direct References sowie Pipfile und Pipfile.lock-Einträge zu reproduzieren. Schließlich reichen sie aus, um den Branch-, Tag- und/oder Git-Ref-Ursprung der installierten Version aufzuzeichnen, der dank eines vorhandenen VCS-Checkouts bereits für editierbare Installationen verfügbar ist.

Da es bereits mindestens drei verschiedene Möglichkeiten gibt, diese Art von Informationen zu kodieren, verwendet dieser PEP ein Dictionary-Format, um keine Annahmen darüber zu treffen, wie eine direkte URL-Referenz letztendlich in einer Anforderung oder einer Lockdatei kodiert werden muss. Siehe auch den Abschnitt Alternativen unten für weitere Diskussionen über diese Wahl.

Informationen wurden aus dem Handbuch von Rubys Bundler übernommen, um zu überprüfen, ob es ähnliche Fähigkeiten hat und um die Auswahl und Benennung von Feldern in diesen Spezifikationen zu informieren.

Das JSON-Format erlaubt die Hinzufügung zusätzlicher Felder in der Zukunft.

Spezifikation

Dieser PEP spezifiziert eine Datei direct_url.json im Verzeichnis .dist-info einer installierten Distribution, um den direkten URL-Ursprung der Distribution aufzuzeichnen.

Die kanonische Quelle für den Namen und die Semantik dieser Metadatendatei ist das Dokument Erfassung des direkten URL-Ursprungs installierter Distributionen.

Diese Datei MUSS von Installationsprogrammen erstellt werden, wenn eine Distribution aus einer Anforderung installiert wird, die eine direkte URL-Referenz (einschließlich einer VCS-URL) spezifiziert.

Diese Datei darf NICHT erstellt werden, wenn eine Distribution aus einer anderen Art von Anforderung installiert wird (d. h. Name plus Versionsspezifizierer).

Diese JSON-Datei MUSS ein Dictionary sein, konform mit RFC 8259 und UTF-8-kodiert.

Falls vorhanden, MUSS sie mindestens zwei Felder enthalten. Das erste Feld ist url vom Typ string. Abhängig davon, worauf sich url bezieht, MUSS das zweite Feld eines von vcs_info (wenn url eine VCS-Referenz ist), archive_info (wenn url ein Quellarchiv oder ein Wheel ist) oder dir_info (wenn url ein lokales Verzeichnis ist) sein. Diese Info-Felder haben ein (möglicherweise leeres) Subdictionary als Wert, mit den unten definierten möglichen Schlüsseln.

url MUSS aus Sicherheitsgründen von allen sensiblen Authentifizierungsinformationen bereinigt werden.

Der Benutzer:Passwort-Teil der URL KANN jedoch aus Umgebungsvariablen bestehen, die dem folgenden regulären Ausdruck entsprechen

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

Zusätzlich KANN der Benutzer:Passwort-Teil der URL eine bekannte, nicht sicherheitsrelevante Zeichenkette sein. Ein typisches Beispiel ist git im Falle einer URL wie ssh://git@gitlab.com.

Wenn url sich auf ein VCS-Repository bezieht, MUSS der Schlüssel vcs_info als Dictionary mit den folgenden Schlüsseln vorhanden sein

• Ein Schlüssel vcs (Typ string) MUSS vorhanden sein und den Namen des VCS enthalten (d. h. eines von git, hg, bzr, svn). Andere VCS’s SOLLTEN registriert werden, indem ein PEP geschrieben wird, um diese Spezifikation zu ergänzen. Der Wert von url MUSS mit dem entsprechenden VCS kompatibel sein, sodass ein Installationsprogramm ihn ohne Transformation an einen Checkout/Download-Befehl des VCS übergeben kann.
• Ein Schlüssel requested_revision (Typ string) KANN vorhanden sein und einen Branch/Tag/Ref/Commit/Revision/etc. (in einem für das VCS kompatiblen Format) zum Installieren benennen.
• Ein Schlüssel commit_id (Typ string) MUSS vorhanden sein und die exakte Commit/Revision-Nummer enthalten, die installiert wurde. Wenn das VCS Commit-Hash-basierte Revisionsbezeichner unterstützt, MUSS ein solcher Commit-Hash als commit_id verwendet werden, um die unveränderliche Version des installierten Quellcodes zu referenzieren.
• Wenn das Installationsprogramm zusätzliche Informationen über die angeforderte Revision ermitteln konnte, KANN es ein Feld resolved_revision und/oder resolved_revision_type hinzufügen. Wenn in der angeforderten URL keine Revision angegeben wurde, KANN resolved_revision den installierten Standard-Branch enthalten und resolved_revision_type wird branch sein. Wenn das Installationsprogramm feststellt, dass requested_revision ein Tag war, KANN es resolved_revision_type mit dem Wert tag hinzufügen.

Wenn url sich auf ein Quellarchiv oder ein Wheel bezieht, MUSS der Schlüssel archive_info als Dictionary mit dem folgenden Schlüssel vorhanden sein

• Ein Schlüssel hash (Typ string) SOLLTE vorhanden sein, mit dem Wert <hash-algorithm>=<expected-hash>. Es wird EMPOHLEN, nur Hashes zu verwenden, die bedingungslos von der neuesten Version des hashlib-Moduls der Standardbibliothek bereitgestellt werden, für Quellarchiv-Hashes. Zum Zeitpunkt der Erstellung besteht diese Liste aus „md5“, „sha1“, „sha224“, „sha256“, „sha384“ und „sha512“.

Wenn url sich auf ein lokales Verzeichnis bezieht, MUSS der Schlüssel dir_info als Dictionary mit dem folgenden Schlüssel vorhanden sein

• editable (Typ: boolean): true, wenn die Distribution im Editier-Modus installiert wurde, andernfalls false. Wenn abwesend, Standard ist false.

Wenn url sich auf ein lokales Verzeichnis bezieht, MUSS es das Schema file haben und konform mit RFC 8089 sein. Insbesondere muss der Pfadkomponente absolut sein. Symbolische Links SOLLTEN bei der Umwandlung von relativen Pfaden in absolute beibehalten werden.

Ein Top-Level-Feld subdirectory KANN vorhanden sein, das einen Verzeichnispfad enthält, relativ zum Stamm des VCS-Repositories, Quellarchivs oder lokalen Verzeichnisses, um anzugeben, wo sich pyproject.toml oder setup.py befindet.

Beispiele

{
    "url": "https://github.com/pypa/pip/archive/1.3.1.zip",
    "archive_info": {
        "hash": "sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8"
    }
}

{
    "url": "https://github.com/pypa/pip.git",
    "vcs_info": {
        "vcs": "git",
        "requested_revision": "1.3.1",
        "resolved_revision_type": "tag",
        "commit_id": "7921be1537eac1e97bc40179a57f0349c2aee67d"
    }
}

{
    "url": "file:///home/user/project",
    "dir_info": {}
}

{
    "url": "file:///home/user/project",
    "dir_info": {
        "editable": true
    }
}

Anwendungsfälle

Umgebung „einfrieren“

Werkzeuge wie pip freeze, die Anforderungen aus der Datenbank der installierten Python-Distributionen generieren, SOLLTEN direct_url.json nutzen, wenn es vorhanden ist, und ihm Vorrang vor den Versionsmetadaten geben, um eine Ausgabe mit höherer Genauigkeit zu generieren. Im Beisein einer direkten URL-Referenz vom Typ vcs SOLLTE das Feld commit_id vorrangig verwendet werden, um die höchstmögliche Genauigkeit für die ursprünglich installierte Version zu gewährleisten. Wenn es von ihrem Anforderungsformat unterstützt wird, werden Werkzeuge ermutigt, auch den Wert tag auszugeben, falls vorhanden, da dieser unveränderliche Semantik hat. Werkzeuge KÖNNEN einen anderen Ansatz wählen, abhängig von den Bedürfnissen ihrer Benutzer.

Beachten Sie, dass die anfängliche Iteration dieses PEP nicht versucht, Umgebungen, die editierbare Installationen oder Installationen aus lokalen Verzeichnissen enthalten, reproduzierbar zu machen, aber sie versucht, sie leicht identifizierbar zu machen. Durch die Lokalisierung des lokalen Projektverzeichnisses über die Felder url und dir_info dieser Spezifikation können Werkzeuge jede Strategie implementieren, die zu ihren Anwendungsfällen passt.

Abwärtskompatibilität

Da dieser PEP eine neue Datei im Verzeichnis .dist-info spezifiziert, gibt es keine Abwärtskompatibilitätsprobleme.

Alternativen

Danksagungen

Verschiedene Personen haben dazu beigetragen, diesen PEP zu realisieren. Paul F. Moore lieferte die Essenz des Abstracts. Alyssa Coghlan schlug den Namen direct_url vor.

Urheberrecht

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