Pybi-spezifische Kernmetadaten

Hier ist ein Beispiel für die neuen METADATA-Felder, bevor wir die vollständigen Details angeben:

Pybi-Environment-Marker-Variables: {"implementation_name": "cpython", "implementation_version": "3.10.8", "os_name": "posix", "platform_machine": "x86_64", "platform_system": "Linux", "python_full_version": "3.10.8", "platform_python_implementation": "CPython", "python_version": "3.10", "sys_platform": "linux"}
Pybi-Paths: {"stdlib": "lib/python3.10", "platstdlib": "lib/python3.10", "purelib": "lib/python3.10/site-packages", "platlib": "lib/python3.10/site-packages", "include": "include/python3.10", "platinclude": "include/python3.10", "scripts": "bin", "data": "."}
Pybi-Wheel-Tag: cp310-cp310-PLATFORM
Pybi-Wheel-Tag: cp310-abi3-PLATFORM
Pybi-Wheel-Tag: cp310-none-PLATFORM
Pybi-Wheel-Tag: cp39-abi3-PLATFORM
Pybi-Wheel-Tag: cp38-abi3-PLATFORM
Pybi-Wheel-Tag: cp37-abi3-PLATFORM
Pybi-Wheel-Tag: cp36-abi3-PLATFORM
Pybi-Wheel-Tag: cp35-abi3-PLATFORM
Pybi-Wheel-Tag: cp34-abi3-PLATFORM
Pybi-Wheel-Tag: cp33-abi3-PLATFORM
Pybi-Wheel-Tag: cp32-abi3-PLATFORM
Pybi-Wheel-Tag: py310-none-PLATFORM
Pybi-Wheel-Tag: py3-none-PLATFORM
Pybi-Wheel-Tag: py39-none-PLATFORM
Pybi-Wheel-Tag: py38-none-PLATFORM
Pybi-Wheel-Tag: py37-none-PLATFORM
Pybi-Wheel-Tag: py36-none-PLATFORM
Pybi-Wheel-Tag: py35-none-PLATFORM
Pybi-Wheel-Tag: py34-none-PLATFORM
Pybi-Wheel-Tag: py33-none-PLATFORM
Pybi-Wheel-Tag: py32-none-PLATFORM
Pybi-Wheel-Tag: py31-none-PLATFORM
Pybi-Wheel-Tag: py30-none-PLATFORM
Pybi-Wheel-Tag: py310-none-any
Pybi-Wheel-Tag: py3-none-any
Pybi-Wheel-Tag: py39-none-any
Pybi-Wheel-Tag: py38-none-any
Pybi-Wheel-Tag: py37-none-any
Pybi-Wheel-Tag: py36-none-any
Pybi-Wheel-Tag: py35-none-any
Pybi-Wheel-Tag: py34-none-any
Pybi-Wheel-Tag: py33-none-any
Pybi-Wheel-Tag: py32-none-any
Pybi-Wheel-Tag: py31-none-any
Pybi-Wheel-Tag: py30-none-any

Spezifikation

• Pybi-Environment-Marker-Variables: Der Wert aller PEP 508-Umgebungsmarker-Variablen, die über Installationen dieses Pybi hinweg statisch sind, als JSON-Dictionary. Zum Beispiel:
  • python_version wird immer vorhanden sein, da ein Python-3.10-Paket immer python_version == "3.10" hat.
  • platform_version wird im Allgemeinen nicht vorhanden sein, da es detaillierte Informationen über das Betriebssystem liefert, auf dem Python ausgeführt wird, zum Beispiel:

    #60-Ubuntu SMP Thu May 6 07:46:32 UTC 2021
    

    platform_release hat ähnliche Probleme.

  • platform_machine wird *meistens* vorhanden sein, mit Ausnahme von macOS Universal2-Pybis: Diese können potenziell im x86-64- oder im ARM64-Modus ausgeführt werden, und wir wissen nicht, welcher Modus bis zur tatsächlichen Ausführung des Interpreters gilt, daher können wir ihn nicht in statischen Metadaten aufzeichnen.

  Begründung: In vielen Fällen sollte dies einem Resolver, der unter Linux läuft, ermöglichen, Paket-Pins für eine Python-Umgebung unter Windows oder umgekehrt zu berechnen, solange der Resolver Zugriff auf die .pybi-Datei der Zielplattform hat. (Beachten Sie, dass Requires-Python-Beschränkungen durch Verwendung des python_full_version-Werts überprüft werden können.) Obwohl wir einige Schlüssel manchmal weglassen müssen, sind sie entweder ziemlich nutzlos (platform_version, platform_release) oder können vom Resolver rekonstruiert werden (platform_machine).

  Die Marker sind auch allgemein nützliche Informationen, auf die zugegriffen werden kann. Wenn Sie beispielsweise ein pypy3-7.3.2-Pybi haben und wissen möchten, welche Python-Sprachversion dies unterstützt, dann ist dies im python_version-Marker aufgezeichnet.

  (Hinweis: Möglicherweise möchten wir platform_version und platform_release deprecaten/entfernen? Sie sind problematisch und ich kann keine Fälle finden, in denen sie nützlich sind. Aber das liegt außerhalb des Umfangs dieser speziellen PEP.)

• Pybi-Paths: Die für die Installation von Wheels benötigten Installationspfade (gleiche Schlüssel wie sysconfig.get_paths()), als relative Pfade ab dem Stammverzeichnis der Zip-Datei, als JSON-Dictionary.

  Diese Pfade MÜSSEN im Unix-Format mit Schrägstrichen als Trennzeichen und nicht mit Backslashes geschrieben werden.

  Es muss möglich sein, den Python-Interpreter aufzurufen, indem {paths["scripts"]}/python ausgeführt wird. Wenn alternative Interpreter-Einstiegspunkte vorhanden sind (z. B. pythonw für Windows-GUI-Anwendungen), sollten diese ebenfalls in diesem Verzeichnis unter ihren üblichen Namen ohne Versionsnummer aufgeführt sein. (Sie können *auch* einen python3.11-Symlink haben, wenn Sie möchten; es gibt keine Regel dagegen. Es ist nur so, dass python vorhanden und funktionsfähig sein muss.)

  Begründung: Pybi-Paths und Pybi-Wheel-Tags (siehe unten) reichen zusammen aus, damit ein Installer Wheels auswählen und sie in eine entpackte Pybi-Umgebung installieren kann, ohne Python aufrufen zu müssen. Außerdem müssen wir den Speicherort des Interpreters irgendwo festhalten, also ist das ein zweischneidiges Schwert.

• Pybi-Wheel-Tag: Die von diesem Interpreter unterstützten Wheel-Tags in bevorzugter Reihenfolge (am meisten bevorzugt zuerst, am wenigsten bevorzugt zuletzt), mit der Ausnahme, dass der spezielle Plattform-Tag PLATFORM alle Plattform-Tags ersetzen sollte, die vom endgültigen Installationssystem abhängen.

  Diskussion: Es wäre schön™, wenn Installer die entsprechenden Wheel-Tags eines Pybis im Voraus berechnen könnten, damit sie Wheels in das entpackte Pybi installieren könnten, ohne den Python-Interpreter tatsächlich aufrufen zu müssen, um seine Tags abzufragen – sowohl aus Effizienzgründen als auch um exotischere Anwendungsfälle wie die Einrichtung einer Windows-Umgebung von einem Linux-Host aus zu ermöglichen.

  Aber leider ist es unmöglich, die vollständige Menge der von einer Python-Installation unterstützten Plattform-Tags im Voraus zu berechnen, da sie vom endgültigen System abhängen können.

  • Ein Pybi mit dem Tag manylinux_2_12_x86_64 kann immer Wheels verwenden, die als manylinux_2_12_x86_64 getaggt sind. Es *kann* auch Wheels verwenden, die mit manylinux_2_17_x86_64 getaggt sind, aber nur, wenn das endgültige Installationssystem glibc 2.17+ hat.
  • Ein Pybi mit dem Tag macosx_11_0_universal2 (= x86-64 + ARM64-Unterstützung im selben Binärpaket) kann möglicherweise Wheels verwenden, die als macosx_11_0_arm64 getaggt sind, aber nur, wenn es auf einem „Apple Silicon“-Computer installiert ist und im ARM64-Modus ausgeführt wird.

  In diesen beiden Fällen kann ein Installationstool immer noch den geeigneten Satz von Wheel-Tags ermitteln, indem es die lokalen Plattform-Tags berechnet, die Wheel-Tag-Vorlagen aus Pybi-Wheel-Tag entnimmt und die tatsächlichen unterstützten Plattformen anstelle des magischen PLATFORM-Strings einsetzt.

  Es gibt jedoch andere, noch kompliziertere Fälle.

  • Sie können (normalerweise) sowohl 32-Bit- als auch 64-Bit-Anwendungen auf 64-Bit-Windows ausführen. Ein Pybi

    Installer könnte den Satz zulässiger Pybi-Tags auf der aktuellen Plattform als [win32, win_amd64] berechnen. Aber Sie können diesen Satz nicht einfach nehmen und ihn in die Wheel-Tag-Vorlage des Pybis einsetzen, sonst erhalten Sie Unsinn.

    [
      "cp39-cp39-win32",
      "cp39-cp39-win_amd64",
      "cp39-abi3-win32",
      "cp39-abi3-win_amd64",
      ...
    ]
    

    Um dies zu handhaben, muss der Installer irgendwie verstehen, dass ein manylinux_2_12_x86_64-Pybi ein manylinux_2_17_x86_64-Wheel verwenden kann, solange beides gültige Tags auf der aktuellen Maschine sind, aber ein win32-Pybi *kann kein* win_amd64-Wheel verwenden, auch wenn beides gültige Tags auf der aktuellen Maschine sind.

  • Ein Pybi mit dem Tag macosx_11_0_universal2 kann möglicherweise Wheels verwenden, die als macosx_11_0_x86_64 getaggt sind, aber nur, wenn es auf einer x86-64-Maschine installiert ist *oder* es auf einer ARM-Maschine installiert ist *und* der Interpreter mit dem magischen Zauberspruch aufgerufen wird, der macOS anweist, ein Binärpaket im x86-64-Modus auszuführen. Wie der Installer den Pybi aufrufen möchte, spielt also auch eine Rolle!

  Die tatsächliche Verwendung von Pybi-Wheel-Tag-Werten ist also weniger trivial, als es scheinen mag, und sie sind wahrscheinlich nur mit ziemlich ausgefeilten Tools nützlich. Aber intelligente Pybi-Installer müssen bereits viele dieser Plattformkompatibilitätsprobleme verstehen, um ein funktionierendes Pybi auswählen zu können, und für den Fall des plattformübergreifenden Pinning/Umgebungsaufbaus können Benutzer potenziell alle Informationen bereitstellen, die erforderlich sind, um genau zu disambiguieren, welche Plattform sie anvisieren. Daher ist es immer noch nützlich genug, um in die PyBI-Metadaten aufgenommen zu werden – Tools, die es nicht nützlich finden, können es einfach ignorieren.

Sie können diese Metadatenwerte wahrscheinlich generieren, indem Sie dieses Skript auf dem kompilierten Interpreter ausführen.

import packaging.markers
import packaging.tags
import sysconfig
import os.path
import json
import sys

marker_vars = packaging.markers.default_environment()
# Delete any keys that depend on the final installation
del marker_vars["platform_release"]
del marker_vars["platform_version"]
# Darwin binaries are often multi-arch, so play it safe and
# delete the architecture marker. (Better would be to only
# do this if the pybi actually is multi-arch.)
if marker_vars["sys_platform"] == "darwin":
    del marker_vars["platform_machine"]

# Copied and tweaked version of packaging.tags.sys_tags
tags = []
interp_name = packaging.tags.interpreter_name()
if interp_name == "cp":
    tags += list(packaging.tags.cpython_tags(platforms=["xyzzy"]))
else:
    tags += list(packaging.tags.generic_tags(platforms=["xyzzy"]))

tags += list(packaging.tags.compatible_tags(platforms=["xyzzy"]))

# Gross hack: packaging.tags normalizes platforms by lowercasing them,
# so we generate the tags with a unique string and then replace it
# with our special uppercase placeholder.
str_tags = [str(t).replace("xyzzy", "PLATFORM") for t in tags]

(base_path,) = sysconfig.get_config_vars("installed_base")
# For some reason, macOS framework builds report their
# installed_base as a directory deep inside the framework.
while "Python.framework" in base_path:
    base_path = os.path.dirname(base_path)
paths = {key: os.path.relpath(path, base_path).replace("\\", "/") for (key, path) in sysconfig.get_paths().items()}

json.dump({"marker_vars": marker_vars, "tags": str_tags, "paths": paths}, sys.stdout)

Dies gibt ein JSON-Dictionary auf stdout aus, mit separaten Einträgen für jede Gruppe von Pybi-spezifischen Tags.

Symlinks in Zip-Dateien darstellen

Der De-facto-Standard für die Darstellung von Symlinks in Zip-Dateien ist die Info-Zip-Symlink-Erweiterung, die wie folgt funktioniert:

• Der Zielpfad des Symlinks wird wie die Dateiinhalte gespeichert.
• Die obersten 4 Bits des Unix-Berechtigungsfeldes werden auf 0xa gesetzt, d.h.: permissions & 0xf000 == 0xa000.
• Das Unix-Berechtigungsfeld wird wiederum als die obersten 16 Bits des Feldes „externe Attribute“ gespeichert.

Wenn Sie also das zipfile-Modul von Python verwenden, können Sie prüfen, ob ein ZipInfo einen Symlink repräsentiert, indem Sie Folgendes tun:

(zip_info.external_attr >> 16) & 0xf000 == 0xa000

Oder wenn Sie die zip-Crate von Rust verwenden, ist die entsprechende Prüfung:

fn is_symlink(zip_file: &zip::ZipFile) -> bool {
    match zip_file.unix_mode() {
        Some(mode) => mode & 0xf000 == 0xa000,
        None => false,
    }
}

Wenn Sie unter Unix sind, verstehen Ihre zip- und unzip-Befehle dieses Format wahrscheinlich bereits.

Symlinks in RECORD-Dateien darstellen

Normalerweise listet eine RECORD-Datei jede Datei + ihren Hash + ihre Länge auf.

my/favorite/file,sha256=...,12345

Für Symlinks schreiben wir stattdessen:

name/of/symlink,symlink=path/to/symlink/target,

Das heißt: Wir verwenden eine spezielle „Hash-Funktion“ namens symlink und speichern dann das tatsächliche Symlink-Ziel als „Hash-Wert“. Die Länge bleibt leer.

Begründung: Wir sind bereits an die RECORD-Datei gebunden, die eine redundante Überprüfung von allem im Hauptarchiv enthält. Daher müssen wir für Symlinks zumindest eine Art von Hash speichern, plus eine Art von Flagge, um anzuzeigen, dass es sich um einen Symlink handelt. Da Symlink-Zielzeichenketten ungefähr die gleiche Größe wie ein Hash haben, können wir sie auch direkt speichern. Dies erleichtert auch den Zugriff auf die Symlink-Informationen für Tools, die die Info-Zip-Symlink-Erweiterung nicht verstehen, und ermöglicht das verlustfreie Entpacken und erneute Packen eines Unix-Pybis auf einem Windows-System, was jemand zu einem bestimmten Zeitpunkt praktisch finden könnte.

Speichern von Symlinks in pybi-Dateien

Wenn ein Pybi-Ersteller einen Symlink speichert, MUSS er beide oben genannten Mechanismen verwenden: Speichern im Zip-Archiv direkt unter Verwendung der Info-Zip-Darstellung und Aufzeichnung im RECORD-File.

Pybi-Konsumenten SOLLTEN überprüfen, ob die Symlinks im Archiv und in der RECORD-Datei miteinander übereinstimmen.

Wir haben auch erwogen, *nur* die RECORD-Datei zum Speichern von Symlinks zu verwenden, aber dann würde das normale unzip-Tool sie nicht entpacken können, und das würde die Installation eines Pybis aus einem Shell-Skript erschweren.

Einschränkungen

Symlinks ermöglichen eine Menge potenziellen Unrats. Um die Dinge unter Kontrolle zu halten, legen wir die folgenden Einschränkungen fest:

• Symlinks DÜRFEN NICHT in .pybis verwendet werden, die für Windows oder andere Plattformen mit fehlender First-Class-Symlink-Unterstützung bestimmt sind.
• Symlinks DÜRFEN NICHT innerhalb des Verzeichnisses pybi-info verwendet werden. (Begründung: Es gibt keinen Bedarf und es vereinfacht die Dinge für Resolver, die Informationen aus pybi-info extrahieren müssen, ohne das gesamte Archiv zu entpacken.)
• Symlink-Ziele MÜSSEN relative Pfade sein und MÜSSEN sich innerhalb des Pybi-Verzeichnisses befinden.
• Wenn A/B/... als Symlink im Archiv aufgezeichnet wird, darf es KEINE anderen Einträge im Archiv mit dem Namen A/B/.../C geben.

  Wenn beispielsweise ein Archiv einen Symlink foo -> bar hat und später im Archiv eine reguläre Datei namens foo/blah.py vorhanden ist, könnte ein naiver Entpacker potenziell eine Datei namens bar/blah.py schreiben. Seien Sie nicht naiv.

Entpacker MÜSSEN überprüfen, ob diese Regeln befolgt werden, denn ohne sie könnten Angreifer böswillige Symlinks wie foo -> /etc/passwd oder foo -> ../../../../../etc + foo/passwd -> ... erstellen und Unheil anrichten.