Ziel: Einfach zu verwendender Modulzustand

Es ist derzeit umständlich oder unmöglich, alles zu tun, was die C-API bietet, während Module isoliert bleiben. Ermöglicht durch PEP 384, zielen Änderungen in PEP 489 und PEP 573 (und zukünftige geplante) darauf ab, es *möglich* zu machen, Module auf diese Weise zu bauen, und dann *einfach* zu machen, neue Module auf diese Weise zu schreiben und alte zu konvertieren, damit es ein natürlicher Standard werden kann.

Selbst wenn Modul-spezifischer Zustand zum Standard wird, wird es Anwendungsfälle für verschiedene Ebenen der Kapselung geben: prozess-, pro-Interpreter-, pro-Thread- oder pro-Aufgaben-Zustand. Das Ziel ist, diese als Ausnahmefälle zu behandeln: Sie sollten möglich sein, aber Erweiterungsautoren müssen sorgfältiger darüber nachdenken.

Keine Ziele: Geschwindigkeitssteigerungen und die GIL

Es gibt einige Bemühungen, CPython auf Multi-Core-CPUs zu beschleunigen, indem die GIL pro Interpreter verwaltet wird. Während die Isolierung von Interpretern diese Bemühungen unterstützt, wird die Standardeinstellung auf Modul-spezifischen Zustand auch dann vorteilhaft sein, wenn keine Geschwindigkeitssteigerung erzielt wird, da sie die Unterstützung mehrerer Interpreter standardmäßig sicherer macht.

Isolierte Modulobjekte

Der wichtigste Punkt, den Sie bei der Entwicklung eines Erweiterungsmoduls beachten sollten, ist, dass aus einer einzelnen gemeinsam genutzten Bibliothek mehrere Modulobjekte erstellt werden können. Zum Beispiel

>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # create a new module object
>>> old_binascii == binascii
False

Als Faustregel sollten die beiden Module vollständig unabhängig sein. Alle Objekte und Zustände, die für das Modul spezifisch sind, sollten innerhalb des Modulobjekts gekapselt, nicht mit anderen Modulobjekten geteilt und beim Löschen des Modulobjekts bereinigt werden. Ausnahmen sind möglich (siehe Verwaltung globalen Zustands), aber sie erfordern mehr Gedanken und Aufmerksamkeit für Grenzfälle als Code, der dieser Faustregel folgt.

Obwohl einige Module mit weniger strengen Einschränkungen auskommen könnten, erleichtern isolierte Module es, klare Erwartungen (und Richtlinien) festzulegen, die über eine Vielzahl von Anwendungsfällen hinweg funktionieren.

Überraschende Grenzfälle

Beachten Sie, dass isolierte Module einige überraschende Grenzfälle erzeugen. Am bemerkenswertesten ist, dass jedes Modulobjekt seine Klassen und Ausnahmen typischerweise nicht mit anderen ähnlichen Modulen teilt. Wenn wir von dem Beispiel oben ausgehen, beachten Sie, dass old_binascii.Error und binascii.Error separate Objekte sind. Im folgenden Code wird die Ausnahme *nicht* abgefangen.

>>> old_binascii.Error == binascii.Error
False
>>> try:
...     old_binascii.unhexlify(b'qwertyuiop')
... except binascii.Error:
...     print('boo')
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
binascii.Error: Non-hexadecimal digit found

Dies ist beabsichtigt. Beachten Sie, dass rein-python-Module das Gleiche verhalten: Es ist Teil der Funktionsweise von Python.

Das Ziel ist es, Erweiterungsmodule auf C-Ebene sicher zu machen, nicht Hacks intuitiv zu machen. Das "manuelle" Modifizieren von sys.modules zählt als Hack.

Verwaltung globalen Zustands

Manchmal ist der Zustand eines Python-Moduls nicht spezifisch für dieses Modul, sondern für den gesamten Prozess (oder etwas "Globaleres" als ein Modul). Zum Beispiel

• Das Modul readline verwaltet *das* Terminal.
• Ein Modul, das auf einer Platine läuft, möchte die *eingebaute* LED steuern.

In diesen Fällen sollte das Python-Modul *Zugriff* auf den globalen Zustand bereitstellen, anstatt ihn zu *besitzen*. Wenn möglich, schreiben Sie das Modul so, dass mehrere Kopien davon unabhängig auf den Zustand zugreifen können (zusammen mit anderen Bibliotheken, sei es für Python oder andere Sprachen).

Wenn dies nicht möglich ist, erwägen Sie explizites Sperren.

Wenn es notwendig ist, prozessweiten globalen Zustand zu verwenden, ist der einfachste Weg, Probleme mit mehreren Interpretern zu vermeiden, explizit zu verhindern, dass ein Modul mehr als einmal pro Prozess geladen wird – siehe Opt-Out: Beschränkung auf ein Modulobjekt pro Prozess.

Verwaltung Modul-spezifischen Zustands

Um Modul-spezifischen Zustand zu verwenden, nutzen Sie die Multi-Phase-Initialisierung von Erweiterungsmodulen, die in PEP 489 eingeführt wurde. Dies signalisiert, dass Ihr Modul mehrere Interpreter korrekt unterstützt.

Setzen Sie PyModuleDef.m_size auf eine positive Zahl, um so viele Bytes Speicher lokal für das Modul anzufordern. Normalerweise wird dies auf die Größe einer modulspezifischen struct gesetzt, die den gesamten C-Level-Zustand des Moduls speichern kann. Insbesondere sollten Sie hier Zeiger auf Klassen (einschließlich Ausnahmen, aber ausschließlich statischer Typen) und Einstellungen (z. B. die field_size_limit von csv) speichern, die der C-Code zur Funktion benötigt.

Wenn der Modulzustand PyObject-Zeiger enthält, muss das Modulobjekt Referenzen auf diese Objekte halten und die Modul-Hooks m_traverse, m_clear und m_free implementieren. Diese funktionieren ähnlich wie tp_traverse, tp_clear und tp_free einer Klasse. Ihre Hinzufügung erfordert einige Arbeit und verlängert den Code; dies ist der Preis für Module, die sauber entladen werden können.

Ein Beispiel für ein Modul mit Modul-spezifischem Zustand ist derzeit als xxlimited verfügbar; die Beispielmodulinitialisierung ist am Ende der Datei zu sehen.

Opt-Out: Beschränkung auf ein Modulobjekt pro Prozess

Eine nicht-negative PyModuleDef.m_size signalisiert, dass ein Modul mehrere Interpreter korrekt unterstützt. Wenn dies für Ihr Modul noch nicht der Fall ist, können Sie Ihr Modul explizit nur einmal pro Prozess ladbar machen. Zum Beispiel

static int loaded = 0;

static int
exec_module(PyObject* module)
{
    if (loaded) {
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    }
    loaded = 1;
    // ... rest of initialization
}

Zugriff auf Modulzustand aus Funktionen

Der Zugriff auf den Zustand aus Funktionen auf Modulebene ist unkompliziert. Funktionen erhalten das Modulobjekt als erstes Argument; zur Extraktion des Zustands können Sie PyModule_GetState verwenden.

static PyObject *
func(PyObject *module, PyObject *args)
{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) {
        return NULL;
    }
    // ... rest of logic
}

Definition von Heap-Typen

Heap-Typen können durch Ausfüllen einer PyType_Spec-Struktur, einer Beschreibung oder einer "Blaupause" einer Klasse, und durch Aufruf von PyType_FromModuleAndSpec() zur Konstruktion eines neuen Klassenobjekts erstellt werden.

Die Klasse sollte im Allgemeinen *sowohl* im Modulzustand (für sicheren Zugriff von C) *als auch* im __dict__ des Moduls (für Zugriff aus Python-Code) gespeichert werden.

Garbage-Collection-Protokoll

Instanzen von Heap-Typen halten eine Referenz auf ihren Typ. Dies stellt sicher, dass der Typ nicht zerstört wird, bevor alle seine Instanzen zerstört sind, kann aber zu Referenzzyklen führen, die vom Garbage Collector unterbrochen werden müssen.

Um Speicherlecks zu vermeiden, müssen Instanzen von Heap-Typen das Garbage-Collection-Protokoll implementieren. Das heißt, Heap-Typen sollten

• Das Flag Py_TPFLAGS_HAVE_GC haben.
• Eine Traversierungsfunktion mit Py_TP_TRAVERSE definieren, die den Typ besucht (z. B. mit Py_VISIT(Py_TYPE(self));).

Bitte beachten Sie die Dokumentation von Py_TPFLAGS_HAVE_GC und tp_traverse <https://docs.pythonlang.de/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse> für zusätzliche Überlegungen.

Wenn Ihre Traversierungsfunktion an die tp_traverse ihrer Basisklasse (oder eines anderen Typs) delegiert, stellen Sie sicher, dass Py_TYPE(self) nur einmal besucht wird. Beachten Sie, dass nur Heap-Typen erwarten, den Typ in tp_traverse zu besuchen.

Zum Beispiel, wenn Ihre Traversierungsfunktion enthält

base->tp_traverse(self, visit, arg)

…und base ein statischer Typ sein kann, dann sollte sie auch enthalten

if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
    // a heap type's tp_traverse already visited Py_TYPE(self)
} else {
    Py_VISIT(Py_TYPE(self));
}

Es ist nicht notwendig, die Referenzzählung des Typs in tp_new und tp_clear zu behandeln.

Zugriff auf Modulzustand aus Klassen

Wenn Sie ein Typobjekt haben, das mit PyType_FromModuleAndSpec() definiert wurde, können Sie PyType_GetModule aufrufen, um das zugehörige Modul zu erhalten, und dann PyModule_GetState, um den Modulzustand zu erhalten.

Um mühsame Boilerplate-Code für die Fehlerbehandlung zu sparen, können Sie diese beiden Schritte mit PyType_GetModuleState kombinieren, was zu folgendem führt:

my_struct *state = (my_struct*)PyType_GetModuleState(type);
if (state === NULL) {
    return NULL;
}

Zugriff auf Modulzustand aus regulären Methoden

Der Zugriff auf den Modulzustand aus Methoden einer Klasse ist etwas komplizierter, aber dank der in PEP 573 eingeführten Änderungen möglich. Um den Zustand zu erhalten, müssen Sie zuerst die *definierende Klasse* erhalten und dann von ihr den Modulzustand abrufen.

Die größte Hürde ist das Erhalten der *Klasse, in der eine Methode definiert wurde*, oder kurz gesagt, die "definierende Klasse" dieser Methode. Die definierende Klasse kann eine Referenz auf das Modul haben, zu dem sie gehört.

Verwechseln Sie die definierende Klasse nicht mit Py_TYPE(self). Wenn die Methode für eine *Unterklasse* Ihres Typs aufgerufen wird, bezieht sich Py_TYPE(self) auf diese Unterklasse, die möglicherweise in einem anderen Modul als Ihrem definiert ist.

class Base:
    def get_defining_class(self):
        return __class__

class Sub(Base):
    pass

Damit eine Methode ihre "definierende Klasse" erhält, muss sie die METH_METHOD | METH_FASTCALL | METH_KEYWORDS-Aufrufkonvention und die entsprechende PyCMethod-Signatur verwenden.

PyObject *PyCMethod(
    PyObject *self,               // object the method was called on
    PyTypeObject *defining_class, // defining class
    PyObject *const *args,        // C array of arguments
    Py_ssize_t nargs,             // length of "args"
    PyObject *kwnames)            // NULL, or dict of keyword arguments

Sobald Sie die definierende Klasse haben, rufen Sie PyType_GetModuleState auf, um den Zustand ihres zugehörigen Moduls zu erhalten.

Zum Beispiel:

static PyObject *
example_method(PyObject *self,
        PyTypeObject *defining_class,
        PyObject *const *args,
        Py_ssize_t nargs,
        PyObject *kwnames)
{
    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);
    if (state === NULL) {
        return NULL;
    }
    ... // rest of logic
}

PyDoc_STRVAR(example_method_doc, "...");

static PyMethodDef my_methods[] = {
    {"example_method",
      (PyCFunction)(void(*)(void))example_method,
      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,
      example_method_doc}
    {NULL},
}

Zugriff auf Modulzustand aus Slot-Methoden, Getter und Setter

Slot-Methoden – die schnellen C-Äquivalente für spezielle Methoden, wie nb_add für __add__ oder tp_new für die Initialisierung – haben eine sehr einfache API, die das Übergeben der definierenden Klasse nicht erlaubt, im Gegensatz zu PyCMethod. Das Gleiche gilt für Getter und Setter, die mit PyGetSetDef definiert wurden.

Um in diesen Fällen auf den Modulzustand zuzugreifen, verwenden Sie die Funktion PyType_GetModuleByDef und übergeben Sie die Moduldefinition. Sobald Sie das Modul haben, rufen Sie PyModule_GetState auf, um den Zustand zu erhalten.

PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);
my_struct *state = (my_struct*)PyModule_GetState(module);
if (state === NULL) {
    return NULL;
}

PyType_GetModuleByDef funktioniert, indem es die MRO (d. h. alle Superklassen) durchsucht, um die erste Superklasse zu finden, die ein entsprechendes Modul hat.

Lebensdauer des Modulzustands

Wenn ein Modulobjekt garbage collected wird, wird sein Modulzustand freigegeben. Für jeden Zeiger auf (einen Teil) des Modulzustands müssen Sie eine Referenz auf das Modulobjekt halten.

Normalerweise ist dies kein Problem, da Typen, die mit PyType_FromModuleAndSpec erstellt wurden, und ihre Instanzen eine Referenz auf das Modul halten. Sie müssen jedoch bei der Referenzzählung vorsichtig sein, wenn Sie Modulzustand von anderen Orten aus referenzieren, z. B. bei Rückrufen für externe Bibliotheken.

Typüberprüfung

Derzeit (Stand Python 3.10) haben Heap-Typen keine gute API, um Py*_Check-Funktionen (wie PyUnicode_Check für str, einen statischen Typ) zu schreiben, und daher ist es nicht einfach sicherzustellen, dass Instanzen ein bestimmtes C-Layout haben.

Metaklassen

Derzeit (Stand Python 3.10) gibt es keine gute API, um die *Metaklasse* eines Heap-Typs anzugeben; das heißt, das Feld ob_type des Typobjekts.

Pro-Klassen-Gültigkeitsbereich

Es ist auch nicht möglich, Zustand an *Typen* anzuhängen. Obwohl PyHeapTypeObject ein Objekt variabler Größe (PyVarObject) ist, wird sein Speicher variabler Größe derzeit von Slots belegt. Die Behebung dieses Problems wird durch die Tatsache erschwert, dass mehrere Klassen in einer Vererbungshierarchie möglicherweise etwas Zustand reservieren müssen.

Verlustfreie Konvertierung in Heap-Typen

Die Heap-Typ-API war nicht für eine "verlustfreie" Konvertierung von statischen Typen ausgelegt; das heißt, die Erstellung eines Typs, der sich exakt wie ein gegebener statischer Typ verhält. Die beste Lösung wäre wahrscheinlich, einen Leitfaden zu schreiben, der bekannte "Fallstricke" abdeckt.