Unstable C API tier

Die Python C-API ist derzeit in drei Stabilitätsstufen unterteilt.

• Begrenzte API mit hohen Kompatibilitätserwartungen
• Öffentliche API, die der Richtlinie zur Abwärtskompatibilität folgt und Deprecation-Warnungen vor Änderungen erfordert.
• Interne (private) API, die sich jederzeit ändern kann.

Tools, die Zugriff auf CPython-Interna benötigen (z. B. fortgeschrittene Debugger und JIT-Compiler), werden oft für Minor-Series-Releases von CPython erstellt und gehen davon aus, dass sich die intern verwendeten C-API-Interna in Patch-Releases nicht ändern. Um diese Tools zu unterstützen, benötigen wir eine Stufe zwischen der öffentlichen und der privaten C-API mit Garantien für die Stabilität über die gesamte Minor-Series-Version hinweg: die vorgeschlagene instabile Stufe.

Einige Funktionen wie PyCode_New() sind als instabil dokumentiert ("Calling [it] directly can bind you to a precise Python version") und ändern sich oft auch in der Praxis. Die instabile Stufe sollte ihren Status selbst für Leute offensichtlich machen, die die Dokumentation nicht sorgfältig genug lesen, und sie somit schwer versehentlich zu verwenden machen.

Reservierung von führenden Unterstrichen für die private API

Derzeit sind sich die CPython-Entwickler nicht einig über die genaue Bedeutung eines führenden Unterstrichs in API-Namen. Er wird für zwei verschiedene Dinge verwendet:

• API, die sich zwischen Minor-Versionen ändern kann, wie in der hier vorgeschlagenen instabilen Stufe (z. B. Funktionen, die in PEP 523 eingeführt wurden).
• API, die privat ist und überhaupt nicht außerhalb von CPython verwendet werden sollte (z. B. weil sie sich ohne Vorankündigung ändern kann oder auf undokumentierten Annahmen beruht, die Nicht-CPython-Code nicht garantieren kann).

Die unklare Bedeutung macht den Unterstrich weniger nützlich, als er sein könnte. Wenn er nur private API markieren würde, könnten CPython-Entwickler unterstrichene Funktionen ändern oder ungenutzte entfernen, ohne zu recherchieren, wie sie außerhalb von CPython dokumentiert oder verwendet werden.

Mit der Einführung einer dedizierten instabilen Stufe können wir die Bedeutung des führenden Unterstrichs klären. Er sollte nur private API markieren.

Kein unnötiges Brechen von Code

Diese PEP legt fest, dass die API der instabilen Stufe ein spezielles Namenspräfix haben soll. Das bedeutet, dass Funktionen (Makros usw.) umbenannt werden müssen. Nach einer Umbenennung sollte der alte Name weiterhin verfügbar sein, bis eine inkompatible Änderung vorgenommen wird (d. h. bis die Aufrufstellen sowieso aktualisiert werden müssen). Mit anderen Worten: Allein die Änderung der Stufe einer Funktion sollte den Code der Benutzer nicht brechen.

Führender Unterstrich

C-API, die mit einem führenden Unterstrich benannt ist, sowie API, die nur mit Py_BUILD_CORE verfügbar ist, werden als intern betrachtet. Das bedeutet:

• Sie kann sich ohne Vorankündigung in Minor-Releases (3.x.0, einschließlich Alpha- und Beta-Releases von 3.x.0) ändern oder entfernt werden. API-Änderungen in Patch-Releases oder Release Candidates sollten nur erfolgen, wenn es unbedingt notwendig ist.
• Sie sollte in Quellcode-Kommentaren oder nur im Devguide dokumentiert werden, nicht in der öffentlichen Dokumentation.
• API, die vor Python 3.12 eingeführt wurde und dokumentiert oder extern weit verbreitet ist, sollte wie oben beschrieben in die instabile Stufe verschoben werden.

  Dies kann lange nach der Annahme dieser PEP geschehen. Daher sollten die Kernentwickler einige Jahre lang recherchieren, bevor sie unterstrichene APIs ändern, insbesondere wenn sie kein Py_BUILD_CORE benötigen.

Benutzer der C-API werden ermutigt, ihren Code nach den Bezeichnerpräfixen _Py und _PY zu durchsuchen und alle Funde als Probleme zu behandeln, die schließlich behoben werden müssen – entweder durch Umstieg auf eine bestehende Alternative oder durch Eröffnung eines CPython-Issues, um die Bereitstellung öffentlicher API für ihren Anwendungsfall zu beantragen und schließlich darauf umzusteigen.

Initiale instabile API

Die folgende API wird in der initialen Implementierung als Proof of Concept in die instabile Stufe verschoben.

Konstruktoren für Code-Objekte

• PyUnstable_Code_New() (umbenannt von PyCode_New)
• PyUnstable_Code_NewWithPosOnlyArgs() (umbenannt von PyCode_NewWithPosOnlyArgs)

Zusatzinformationen für Code (PEP 523)

• PyUnstable_Eval_RequestCodeExtraIndex() (umbenannt von _PyEval_RequestCodeExtraIndex)
• PyUnstable_Code_GetExtra() (umbenannt von _PyCode_GetExtra)
• PyUnstable_Code_SetExtra() (umbenannt von _PyCode_SetExtra)

Weitere werden für Python 3.12 erwartet, ohne dass eine weitere PEP erforderlich ist.

Kein spezielles Präfix

In der initialen Version dieser PEP hatten instabile APIs nicht das Präfix PyUnstable. Stattdessen machte die Definition von Py_USING_UNSTABLE_API die API in einer bestimmten Quelldatei verfügbar, was die Anerkennung signalisierte, dass die Datei als Ganzes potenziell für jede Python-Version neu überarbeitet werden muss.

Es wurde jedoch entschieden, dass Instabilität in den einzelnen Namen sichtbar gemacht werden muss.

Unterstrich-Präfix

Es wäre möglich, sowohl private als auch instabile API mit führenden Unterstrichen zu kennzeichnen. Das würde jedoch die Bedeutung des Präfixes _Py verwässern. Die Reservierung des Präfixes nur für interne API macht es trivial, danach zu suchen.

Neues Header-Verzeichnis

Andere API-Stufen haben dedizierte Verzeichnisse für Header (Include/cpython/, Include/internal/).

Da die instabile Stufe eine sehr offensichtliche Namenskonvention verwendet und die Namen immer verfügbar sind, ist ein Verzeichnis wie Include/unstable/ unnötig.

Python API

Es könnte gut sein, eine ähnliche Stufe in der Python-API (nicht C-API) hinzuzufügen, z. B. für types.CodeType. Der Mechanismus dafür müsste jedoch anders sein. Dies liegt außerhalb des Rahmens der PEP.