Zusammenfassung

Dieses Dokument beschreibt Erweiterungen für die Kommunikation zwischen Build-Backend und Frontend (wie eingeführt durch PEP 517), um Projekten die Installation im Editable-Modus durch die Einführung von virtuellen Wheels zu ermöglichen.

Motivation

Während der Entwicklung bevorzugen viele Python-Benutzer die Installation ihrer Bibliotheken so, dass Änderungen am zugrundeliegenden Quellcode und an den Ressourcen in nachfolgenden Interpreter-Aufrufen automatisch widergespiegelt werden, ohne einen zusätzlichen Installationsschritt. Dieser Modus wird üblicherweise als "Entwicklungsmodus" oder "Editable Installs" bezeichnet. Derzeit gibt es keine standardisierte Methode, um dies zu erreichen, da dies aufgrund der Komplexität der tatsächlich beobachteten Verhaltensweisen explizit von PEP 517 ausgeschlossen wurde.

Derzeit führen Benutzer, um dieses Verhalten zu erzielen, eines der folgenden durch:

• Nur für Python-Code, indem die relevanten Quellverzeichnisse zu sys.path hinzugefügt werden (konfigurierbar über die Kommandozeile mittels der Umgebungsvariable PYTHONPATH). Beachten Sie, dass in diesem Fall die Benutzer die Projekt-Abhängigkeiten selbst installieren müssen und keine Entry Points oder Projektmetadaten generiert werden.
• setuptools bietet den setup.py develop Mechanismus: dieser installiert eine pth-Datei, die den Projekt-Root beim Interpreter-Start in sys.path einfügt, die Projekt-Metadaten generiert und auch die Projekt-Abhängigkeiten installiert. pip stellt das Aufrufen dieses Mechanismus über die pip install -e Kommandozeilenschnittstelle bereit.
• flit bietet den flit install –symlink Befehl, der die Projektdateien in den purelib-Ordner des Interpreters symlinkt, die Projekt-Metadaten generiert und auch Abhängigkeiten installiert. Beachten Sie, dass dies auch die Unterstützung von Ressourcen-Dateien ermöglicht.

Wie diese Beispiele zeigen, kann eine Editable Installation auf verschiedene Arten erreicht werden und derzeit gibt es keine standardisierte Methode dafür. Darüber hinaus ist unklar, wessen Verantwortung es ist, eine Editable Installation zu erreichen und zu definieren.

1. ermöglicht es dem Build-Backend, diese zu definieren und zu materialisieren,
2. ermöglicht es dem Build-Frontend, diese zu definieren und zu materialisieren,
3. definiert und standardisiert explizit eine Methode aus den möglichen Optionen.

Der Autor dieses PEP ist der Meinung, dass es hier keine Einheitslösung gibt, jede Methode zur Erzielung des Editable-Effekts hat ihre Vor- und Nachteile. Daher lehnt dieses PEP Option drei ab, da es unwahrscheinlich ist, dass sich die Community auf eine einzige Lösung einigen wird. Darüber hinaus bleibt die Frage, ob das Frontend oder das Build-Backend für diese Verantwortung zuständig sein sollte. PEP 660 schlägt vor, dass das Build-Backend dafür verantwortlich ist, während das aktuelle PEP primär das Frontend vorschlägt, aber dem Backend dennoch erlaubt, die Kontrolle zu übernehmen, wenn es dies wünscht.

Begründung

PEP 517 hat "Editable Installs" aufgeschoben, da dies die Einführung weiter verzögert hätte und es keine Einigung darüber gab, wie Editable Installs erreicht werden sollten. Aufgrund der Popularität der Projekte setuptools und pip setzte sich der Status Quo durch, und das Backend konnte den Editable-Modus durch die Bereitstellung einer setup.py develop Implementierung erreichen, die der Benutzer über pip install -e auslösen konnte. Durch die Definition einer Editable-Schnittstelle zwischen dem Build-Backend und dem Frontend können wir die setup.py-Datei und ihre derzeitige Kommunikationsmethode eliminieren.

Terminologie und Ziele

Dieses PEP zielt darauf ab, die Rollen des Frontends und des Backends klar abzugrenzen und den Entwicklern beider Seiten maximale Möglichkeiten zu geben, wertvolle Funktionen für ihre Benutzer bereitzustellen. In diesem Vorschlag besteht die Rolle des Backends darin, das Projekt für eine Editable Installation vorzubereiten und dem Frontend dann genügend Informationen zur Verfügung zu stellen, damit das Frontend die Editable Installation manifestieren und erzwingen kann.

Die vom Backend an das Frontend gelieferten Informationen sind ein Wheel, das der bestehenden Spezifikation in PEP 427 folgt. Die Wheel-Metadaten über das Archiv selbst ({distribution}-{version}.dist-info/WHEEL) müssen auch den Schlüssel Editable mit dem Wert true enthalten.

Anstatt die Projektdateien innerhalb des Wheels bereitzustellen, muss es jedoch eine editable.json-Datei (auf der Root-Ebene des Wheels) enthalten, die die vom Frontend bereitzustellenden Dateien definiert. Der Inhalt dieser Datei ist als Zuordnung von absoluten Quellcodebaum-Pfaden zu relativen Ziel-Interpreter-Pfaden innerhalb einer Schema-Zuordnung formuliert.

Ein Wheel, das die beiden vorhergehenden Absätze erfüllt, ist ein virtuelles Wheel. Die Rolle des Frontends besteht darin, das virtuelle Wheel zu nehmen und das Projekt im Editable-Modus zu installieren. Wie es dies erreicht, liegt vollständig beim Frontend und gilt als Implementierungsdetail.

Der Editable-Installationsmodus impliziert, dass der Quellcode des installierten Projekts in einem lokalen Verzeichnis verfügbar ist. Sobald das Projekt im Editable-Modus installiert ist, werden einige Änderungen am Projektcode im lokalen Quellcodebaum wirksam, ohne dass ein neuer Installationsschritt erforderlich ist. Mindestens Änderungen am Text von Nicht-Generierungs-Dateien, die zum Zeitpunkt der Installation vorhanden waren, sollten beim anschließenden Import des Pakets reflektiert werden.

Einige Arten von Änderungen, wie das Hinzufügen oder Ändern von Entry Points oder neuen Abhängigkeiten, erfordern einen neuen Installationsschritt, um wirksam zu werden. Diese Änderungen werden typischerweise in Build-Backend-Konfigurationsdateien (wie pyproject.toml) vorgenommen. Diese Anforderung steht im Einklang mit der allgemeinen Erwartung der Benutzer, dass solche Modifikationen erst nach einer Neuinstallation wirksam werden.

Obwohl Benutzer erwarten, dass sich Editable Installs identisch zu Standardinstallationen verhalten, ist dies möglicherweise nicht immer möglich und steht im Konflikt mit anderen Erwartungen der Benutzer. Abhängig davon, wie ein Frontend den Editable-Modus implementiert, können einige Unterschiede sichtbar sein, wie z. B. das Vorhandensein zusätzlicher Dateien (im Vergleich zu einer typischen Installation), entweder im Quellcodebaum oder im Installationspfad des Interpreters.

Frontends sollten bestrebt sein, Unterschiede zwischen dem Verhalten von Editable- und Standardinstallationen zu minimieren und bekannte Unterschiede zu dokumentieren.

Zur Referenz funktioniert eine Nicht-Editable-Installation wie folgt:

1. Der **Entwickler** verwendet ein Werkzeug, das wir hier als **Frontend** bezeichnen, um die Projektentwicklung voranzutreiben (z. B. pip). Wenn der Benutzer den Build und die Installation eines Projekts auslösen möchte, kommuniziert er mit dem **Frontend**.
2. Das Frontend verwendet ein **Build-Frontend**, um den Build eines Wheels auszulösen (z. B. build). Das Build-Frontend verwendet PEP 517, um mit dem **Build-Backend** zu kommunizieren (z. B. setuptools) – wobei das Build-Backend in einer PEP 518-Umgebung installiert ist. Nach dem Aufruf gibt das Backend ein Wheel zurück.
3. Das Frontend nimmt das Wheel und übergibt es an einen **Installer** (z. B. installer), um das Wheel in den Ziel-Python-Interpreter zu installieren.

Der Mechanismus

Dieses PEP fügt zwei optionale Hooks zur PEP 517-Backend-Schnittstelle hinzu. Einer der Hooks wird verwendet, um die Build-Abhängigkeiten einer Editable Installation anzugeben. Der andere Hook liefert über das Build-Frontend die notwendigen Informationen, die das Frontend zum Erstellen einer Editable Installation benötigt.

def get_requires_for_build_editable(config_settings=None):
    ...

def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
    ...

def build_editable(self, wheel_directory, config_settings=None,
                    metadata_directory=None):
    ...

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://pypa.io/editables.json",
  "type": "object",
  "title": "Virtual wheel editable schema.",
  "required": ["version", "scheme"],
  "properties": {
    "version": {
      "$id": "#/properties/version",
      "type": "integer",
      "minimum": 1,
      "maximum": 1,
      "title": "The version of the schema."
    },
    "scheme": {
      "$id": "#/properties/scheme",
      "type": "object",
      "title": "Files to expose.",
      "required": ["purelib", "platlib", "data", "headers", "scripts"],
      "properties": {
        "purelib": { "$ref": "#/$defs/mapping" },
        "platlib": { "$ref": "#/$defs/mapping" },
        "data": { "$ref": "#/$defs/mapping" },
        "headers": { "$ref": "#/$defs/mapping" },
        "scripts": { "$ref": "#/$defs/mapping" }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true,
  "$defs": {
    "mapping": {
      "type": "object",
      "description": "A mapping of source to target paths. The source is absolute path, the destination is relative path.",
      "additionalProperties": true
    }
  }
}

{
   "version": 1,
   "scheme": {
      "purelib": {"/src/tree/a.py": "tree/a.py"},
      "platlib": {},
      "data": {"/src/tree/py.typed": "tree/py.typed"},
      "headers": {},
      "scripts": {}
   }
}

{
  {"version": 1, "scheme": {"purelib": {"<project dir>": "<project dir>"}}}
}

{
   "version": 1,
   "scheme": {
      "purelib": {
        "<project dir>/.editable/_register_importer.pth": "<project dir>/_register_importer.pth".
        "<project dir>/.editable/_editable_importer.py": "<project dir>/_editable_importer.py"
      }
    }
  }
}

Abgelehnte Ideen

Dieses PEP konkurriert mit PEP 660 und lehnt diesen Vorschlag ab, da wir der Meinung sind, dass der Mechanismus zur Erreichung einer Editable Installation beim Frontend und nicht beim Build-Backend liegen sollte. Darüber hinaus ermöglicht dieser Ansatz dem Ökosystem, alternative Mittel zur Erzielung des Editable-Installations-Effekts zu nutzen (z. B. das Einfügen von Pfaden in sys.path oder Symlinks anstelle der reinen Implikation des Loose-Wheel-Modus des in diesem PEP beschriebenen Backends).

Prominenterweise erlaubt PEP 660 nicht die Verwendung von Symlinks zur Bereitstellung von Code und Datendateien, ohne auch den Wheel-Dateistandard um die Unterstützung von Symlinks zu erweitern. Es ist unklar, wie das Wheel-Format erweitert werden könnte, um Symlinks zu unterstützen, die nicht auf Dateien innerhalb des Wheels selbst verweisen, sondern auf Dateien, die nur auf der lokalen Festplatte verfügbar sind. Es ist wichtig zu beachten, dass das Backend selbst (oder vom Backend generierter Code) diese Symlinks nicht generieren darf (z. B. beim Interpreter-Start), da dies mit der Buchhaltung des Frontends, welche Dateien deinstalliert werden müssen, kollidieren würde.

Schließlich fügt PEP 660 nur Unterstützung für purelib- und platlib-Dateien hinzu. Es vermeidet bewusst die Unterstützung anderer Arten von Informationen, die das Wheel-Format unterstützt: include, data und scripts. Mit diesem Weg kann das Frontend diese auf Best-Effort-Basis über den Symlink-Mechanismus unterstützen (obwohl diese Funktion nicht universell verfügbar ist – unter Windows muss sie aktiviert werden). Wir glauben, dass es vorteilhaft ist, Best-Effort-Unterstützung für diese Dateitypen hinzuzufügen, anstatt die Möglichkeit, sie überhaupt zu unterstützen, auszuschließen.

Urheberrecht

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