Hintergrund

Pythons Stable ABI, wie in PEP 384 und PEP 652 definiert, bietet eine Möglichkeit, Erweiterungsmodule zu kompilieren, die auf mehreren Minor-Versionen des CPython-Interpreters geladen werden können. Mehrere Projekte nutzen dies, um die Anzahl der zu bauenden und zu verteilenden Wheels (binäre Artefakte) für jede Veröffentlichung zu begrenzen und/oder um das Testen mit Vorabversionen von Python zu erleichtern.

Da Free-Threaded Builds (PEP 703) auf dem besten Weg sind, schließlich zum Standard zu werden (PEP 779), benötigen wir eine Möglichkeit, die Stable ABI für diese Builds verfügbar zu machen.

Um gegen die Stable ABI zu bauen, muss die Erweiterung eine *Limited API* verwenden, d.h. nur eine Teilmenge der Funktionen, Strukturen usw., die CPython bereitstellt. Die Limited API ist versioniert, und das Bauen gegen Limited API 3.X liefert eine Erweiterung, die ABI-kompatibel mit CPython 3.X und *jeder* späteren Version ist (obwohl Fehler in CPython manchmal praktisch zu Inkompatibilitäten führen). Außerdem ist die Limited API nicht „stabil“: neuere Versionen können APIs entfernen, die Teil älterer Versionen waren.

Dieser PEP schlägt die bisher bedeutendste solche Entfernung vor.

Opaque PyObject

Version 3.15 der Limited API wird

• die folgenden Strukturen zu *opak* machen (oder in C-Terminologie, *unvollständige Typen*)
  • PyObject
  • PyVarObject
  • PyModuleDef_Base
  • PyModuleDef
• die folgenden Makros nicht mehr enthalten
  • PyObject_HEAD
  • _PyObject_EXTRA_INIT
  • PyObject_HEAD_INIT
  • PyObject_VAR_HEAD
  • Py_SET_TYPE()
• die folgenden als Funktionen in der ABI exportieren, anstatt als Makros
  • Py_SIZE()
  • Py_SET_SIZE()

Neuer Export Hook (PEP 793)

Die Implementierung dieses PEP erfordert, dass PEP 793 (PyModExport): Ein neuer Einstiegspunkt für C-Erweiterungsmodule) akzeptiert wird, der einen neuen „Export Hook“ für die Definition von C-Erweiterungsmodulen bereitstellt. Die Verwendung des neuen Hooks wird in der Limited API 3.15 obligatorisch.

Laufzeit-ABI-Prüfungen

Benutzer – oder besser gesagt die Werkzeuge, die sie zum Bauen und Installieren von Erweiterungen verwenden – werden weiterhin dafür verantwortlich sein, keine inkompatiblen Erweiterungen in Pythons Importpfade zu legen. Diese Entscheidung ist sinnvoll, da Werkzeuge typischerweise viel reichhaltigere Metadaten haben als das, was CPython überprüfen kann.

CPython wird jedoch eine Verteidigungslinie gegen veraltete oder falsch konfigurierte Werkzeuge oder menschliche Fehler in Form eines neuen *Modul-Slots* hinzufügen, der grundlegende ABI-Informationen enthält. Diese Informationen werden beim Laden eines Moduls überprüft, und inkompatible Erweiterungen werden abgelehnt. Die genauen Details bleiben der C API Working Group überlassen (siehe Issue 72).

Dieser Slot wird mit dem neuen Export Hook, der in PEP 793 hinzugefügt wird, *obligatorisch*. (Dieser PEP sagt derzeit „es gibt keine erforderlichen Slots“; er wird aktualisiert.)

Der abi3t Wheel-Tag

Wheels, die eine Stable ABI verwenden, die mit Free-Threaded CPython-Builds kompatibel ist, sollten einen neuen ABI-Tag verwenden: abi3t. Der Name ist so gewählt, dass er die Tatsache widerspiegelt, dass diese ABI abi3 ähnelt, außer den notwendigen Änderungen zur Unterstützung von Free-Threading (das den Buchstaben t in bestehenden, versionsspezifischen ABI-Tags wie cp314t verwendet).

Da Wheels, die mit Limited API 3.15 erstellt wurden, sowohl mit GIL-aktivierten als auch mit Free-Threaded Builds kompatibel sein werden, sollten sie die komprimierte ABI-Tag-Menge abi3.abi3t verwenden.

Neue API

Die Implementierung dieses PEP ermöglicht das Bauen von Erweiterungen, die auf Free-Threaded Python erfolgreich geladen werden können, aber nicht notwendigerweise solche, die ohne GIL Thread-sicher sind.

Limited API zur Ermöglichung von Thread-Sicherheit ohne GIL – vermutlich PyMutex, PyCriticalSection und ähnliche – werden über die C API Working Group oder in einem Folge-PEP hinzugefügt.

Kompatibilitätsübersicht

Die folgende Tabelle fasst die Kompatibilität von Wheel-Tags mit CPython-Interpretern zusammen. „GIL“ steht für GIL-aktivierten Interpreter; „FT“ steht für einen Free-Threaded.

Die folgende Tabelle fasst zusammen, welcher Wheel-Tag für eine mit einem bestimmten Interpreter und dem Py_LIMITED_API Makro erstellte Erweiterung verwendet werden sollte.

Werte in der Spalte *Hinweis*

• *bestehend*: Der Wheel-Tag wird derzeit verwendet
• *fortgesetzt*: Der Wheel-Tag setzt das bestehende Schema fort
• *eingestellt*: Der Wheel-Tag setzt das bestehende Schema fort, wird aber nicht mehr empfohlen. Ältere Werkzeuge können ihn möglicherweise noch generieren.
• *neu*: Vorgeschlagen in diesem PEP.

Eine alternative stabile ABI für Free-Threading hinzufügen

Es wäre möglich, Folgendes zu tun:

• Eine neue stabile ABI („abi3t“) speziell für Free-Threading hinzuzufügen, die mit der bestehenden abi3 inkompatibel wäre. Erweiterungen bräuchten keine Code-Änderungen, um abi3t zu targeten, und Builds wären mit Free-Threaded CPython (3.14 und höher) kompatibel.
• Ein zusätzliches Makro („Py_OPAQUE_PYOBJECT“) zu definieren, das PyObject opak macht, wie in diesem PEP. Erweiterungen bräuchten Code-Änderungen wie in diesem PEP, und wie in diesem PEP wären kompilierte Erweiterungen („abi3.abi3t“) mit allen Builds von CPython 3.15+ kompatibel.

Dieses Schema wurde als zu komplex abgelehnt. Es würde auch das Free-Threading-Speicherlayout von PyObject zum Teil der Stable ABI machen und zukünftige Anpassungen verhindern.

Shims zur Kompatibilität mit CPython 3.14

Das Hauptproblem, das die Kompatibilität mit Python 3.14 verhindert, ist, dass mit opakem PyObject und PyModuleDef die Initialisierung eines Erweiterungsmoduls nicht machbar ist. Die Lösung, PEP 793, wird erst in Python 3.15 hinzugefügt.

Es ist möglich, dies zu umgehen, indem die Tatsache genutzt wird, dass die ABIs von 3.14 (sowohl Free-Threaded als auch GIL-aktiviert) „eingefroren“ sind, sodass eine Erweiterung den laufenden Interpreter abfragen kann und für 3.14 eine struct-Definition verwendet, die dem PyModuleDef des erkannten Builds entspricht.

Dies ist im Moment zu aufwendig, um es in Pythons Limited API zu unterstützen und zu testen, könnte aber in Zukunft erlaubt sein.

Verwendung des Python Wheel-Tags zur Bestimmung der Kompatibilität

Eine frühere Version dieses PEP vermied das Hinzufügen eines neuen Wheel-Tags (abi3t) und gab an, dass Wheels mit dem Tag abi3 mit Free-Threading kompatibel wären, wenn das *Python-Tag* cp315 oder höher wäre.

Ein solches Schema würde für diesen PEP funktionieren, kann aber nicht ausdrücken, dass eine Erweiterung sowohl mit GIL-aktivierten als auch mit Free-Threaded Builds von CPython 3.14 oder niedriger kompatibel ist. Das Hinzufügen eines neuen expliziten Tags bedeutet, dass *falls* wir solche Wheels in Zukunft zulassen, Paketierungs-Tools keine zusätzlichen Änderungen benötigen, um sie zu unterstützen. Sie würden als cp314-abi3.abi3t getaggt.

Hinzufügen eines abi4 Wheel-Tags

Anstelle von abi3t könnten wir die Version hochstufen und abi4 als Wheel-ABI-Tag verwenden. Im Wheel-Tag ist der Unterschied größtenteils kosmetischer Natur.

Allerdings schlägt dieser PEP nicht vor, den *Dateinamen*-Tag zu ändern: Erweiterungen werden mit Erweiterungen wie .abi3.so benannt. Dies zu ändern und gleichzeitig die Kompatibilität mit GIL-aktivierten Builds zu erhalten, wäre eine unnötige technische Änderung.

Die Verwendung von abi3.abi4 in Wheel-Tags, aber nur .abi3 in Dateinamen, würde inkonsistenter aussehen als abi3.abi3t und .abi3.