Oberklasse

Das Feld cc_parent (zugegriffen z. B. durch einen Deskriptor __parent__ oder __objclass__ aus Python-Code) kann jedes Python-Objekt oder NULL sein. Benutzerdefinierte Klassen können cc_parent frei nach Belieben setzen. Es wird nur vom C-Aufrufprotokoll verwendet, wenn das Flag CCALL_OBJCLASS gesetzt ist.

Für Methoden von Erweiterungstypen zeigt cc_parent auf die Klasse, die die Methode definiert (was eine Oberklasse von type(self) sein kann). Dies ist derzeit schwierig aus dem Code einer Methode abzurufen. Zukünftig kann dies verwendet werden, um über die definierende Klasse auf den Modulstatus zuzugreifen. Siehe die Begründung für PEP 573 für Details.

Wenn das Flag CCALL_OBJCLASS gesetzt ist (wie es bei Methoden von Erweiterungstypen der Fall sein wird), wird cc_parent für Typüberprüfungen wie die folgende verwendet:

>>> list.append({}, "x")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor 'append' requires a 'list' object but received a 'dict'

Für Funktionen eines Moduls wird cc_parent auf das Modul gesetzt. Derzeit ist dies genau dasselbe wie __self__. Die Verwendung von __self__ für das Modul ist jedoch eine Eigenart der aktuellen Implementierung: Zukünftig möchten wir Funktionen zulassen, die __self__ auf normale Weise verwenden, um Methoden zu implementieren. Solche Funktionen können weiterhin stattdessen cc_parent verwenden, um auf das Modul zu verweisen.

Die Oberklasse würde typischerweise auch zur Implementierung von __qualname__ verwendet. Die neue C-API-Funktion PyCCall_GenericGetQualname() tut genau das.

Verwendung von tp_print

Wir schlagen vor, das bestehende ungenutzte Feld tp_print durch tp_ccalloffset zu ersetzen. Da Py_TPFLAGS_HAVE_CCALL *nicht* zu Py_TPFLAGS_DEFAULT hinzugefügt würde, ist dies vollständig abwärtskompatibel für bestehende Erweiterungsmodule, die tp_print setzen. Es bedeutet auch, dass wir verlangen können, dass tp_ccalloffset ein gültiger Offset ist, wenn Py_TPFLAGS_HAVE_CCALL angegeben ist: wir müssen nicht tp_ccalloffset != 0 überprüfen. In zukünftigen Python-Versionen könnten wir entscheiden, dass tp_print bedingungslos zu tp_ccalloffset wird, das Flag Py_TPFLAGS_HAVE_CCALL fallen lassen und stattdessen tp_ccalloffset != 0 prüfen.

HINWEIS: Das genaue Layout von PyTypeObject ist kein Teil der stabilen ABI. Daher sollte die Änderung des Feldes tp_print von einem printfunc (ein Funktionszeiger) zu einem Py_ssize_t kein Problem darstellen, auch wenn dies das Speicherlayout der PyTypeObject-Struktur verändert. Darüber hinaus ist auf allen Systemen, für die Binärdateien üblicherweise erstellt werden (Windows, Linux, macOS), die Größe von printfunc und Py_ssize_t gleich, sodass das Problem der binären Kompatibilität ohnehin nicht auftreten wird.

Überprüfung von __objclass__

Wenn das Flag CCALL_OBJCLASS gesetzt ist und cr_self NULL ist (dies ist bei ungebundenen Methoden von Erweiterungstypen der Fall), dann wird eine Typüberprüfung durchgeführt: die Funktion muss mit mindestens einem Positionsargument aufgerufen werden und das erste (typischerweise self genannt) muss eine Instanz von cc_parent (welche eine Klasse sein muss) sein. Andernfalls wird ein TypeError ausgelöst.

Selbstreferenz-Slicing

Wenn cr_self nicht NULL ist oder wenn das Flag CCALL_SELFARG in cc_flags nicht gesetzt ist, dann ist das als self übergebene Argument einfach cr_self.

Wenn cr_self NULL ist und das Flag CCALL_SELFARG gesetzt ist, dann wird das erste Positionsargument von args entfernt und stattdessen als self-Argument an die C-Funktion übergeben. Effektiv wird das erste Positionsargument als __self__ behandelt. Wenn keine Positionsargumente vorhanden sind, wird ein TypeError ausgelöst.

Dieser Vorgang wird als „Selbstreferenz-Slicing“ bezeichnet und eine Funktion soll Selbstreferenz-Slicing haben, wenn cr_self NULL ist und CCALL_SELFARG gesetzt ist.

Beachten Sie, dass eine CCALL_NOARGS-Funktion mit Selbstreferenz-Slicing effektiv ein Argument hat, nämlich self. Analog dazu hat eine CCALL_O-Funktion mit Selbstreferenz-Slicing zwei Argumente.

Deskriptorverhalten

Klassen, die das C-Aufrufprotokoll unterstützen, müssen das Deskriptorprotokoll auf eine bestimmte Weise implementieren.

Dies ist für eine effiziente Implementierung von gebundenen Methoden erforderlich: Wenn anderer Code Annahmen darüber treffen kann, was __get__ tut, ermöglicht dies Optimierungen, die sonst nicht möglich wären. Insbesondere möchten wir die gemeinsame Nutzung der PyCCallDef-Struktur zwischen gebundenen und ungebundenen Methoden ermöglichen. Wir benötigen auch eine korrekte Implementierung von _PyObject_GetMethod, das von der Optimierung LOAD_METHOD/CALL_METHOD verwendet wird.

Zunächst einmal, wenn func das C-Aufrufprotokoll unterstützt, dann dürfen func.__set__ und func.__delete__ nicht implementiert sein.

Zweitens muss func.__get__ wie folgt verhalten:

• Wenn cr_self nicht NULL ist, dann muss __get__ ein No-Op sein in dem Sinne, dass func.__get__(obj, cls)(*args, **kwds) sich exakt gleich verhält wie func(*args, **kwds). Es ist auch erlaubt, dass __get__ überhaupt nicht implementiert ist.
• Wenn cr_self NULL ist, dann muss func.__get__(obj, cls)(*args, **kwds) (mit obj nicht None) äquivalent zu func(obj, *args, **kwds) sein. Insbesondere muss __get__ in diesem Fall implementiert sein. Dies steht in keinem Zusammenhang mit Selbstreferenz-Slicing: obj kann als self-Argument an die C-Funktion übergeben werden oder es kann das erste Positionsargument sein.
• Wenn cr_self NULL ist, dann muss func.__get__(None, cls)(*args, **kwds) äquivalent zu func(*args, **kwds) sein.

Es gibt keine Einschränkungen für das Objekt func.__get__(obj, cls). Letzteres muss zum Beispiel nicht das C-Aufrufprotokoll implementieren. Wir geben nur an, was func.__get__(obj, cls).__call__ tut.

Für Klassen, die __self__ und __get__ überhaupt nicht interessieren, ist die einfachste Lösung, cr_self = Py_None (oder irgendeinen anderen Wert ungleich NULL) zuzuweisen.

Das __name__ Attribut

Das C-Aufrufprotokoll verlangt, dass die Funktion ein Attribut __name__ vom Typ str (keine Unterklasse) besitzt.

Darüber hinaus muss das Objekt, das von __name__ zurückgegeben wird, irgendwo gespeichert werden; es darf kein temporäres Objekt sein. Dies ist erforderlich, da PyEval_GetFuncName eine geliehene Referenz auf das Attribut __name__ verwendet (siehe auch [2]).

Generische API-Funktionen

Dieser Abschnitt listet die neuen öffentlichen API-Funktionen oder Makros auf, die sich mit dem C-Aufrufprotokoll befassen.

• int PyCCall_Check(PyObject *op): gibt wahr zurück, wenn op das C-Aufrufprotokoll implementiert.

Alle nachfolgenden Funktionen und Makros gelten für jede Instanz, die das C-Aufrufprotokoll unterstützt. Mit anderen Worten, PyCCall_Check(func) muss wahr sein.

• PyObject *PyCCall_Call(PyObject *func, PyObject *args, PyObject *kwds): ruft func mit den Positionsargumenten args und den Schlüsselwortargumenten kwds auf (kwds kann NULL sein). Diese Funktion ist dafür gedacht, in den tp_call-Slot eingefügt zu werden.
• PyObject *PyCCall_FastCall(PyObject *func, PyObject *const *args, Py_ssize_t nargs, PyObject *kwds): ruft func mit nargs Positionsargumenten, die von args[0] bis args[nargs-1] gegeben sind, auf. Der Parameter kwds kann NULL sein (keine Schlüsselwortargumente), ein Dict mit name:value-Items oder ein Tupel mit Schlüsselwortnamen. Im letzteren Fall werden die Schlüsselwortwerte im args-Array gespeichert, beginnend bei args[nargs].

Makros zum Zugriff auf die Strukturen PyCCallRoot und PyCCallDef

• const PyCCallRoot *PyCCall_CCALLROOT(PyObject *func): Zeiger auf die PyCCallRoot-Struktur innerhalb von func.
• const PyCCallDef *PyCCall_CCALLDEF(PyObject *func): Abkürzung für PyCCall_CCALLROOT(func)->cr_ccall.
• uint32_t PyCCall_FLAGS(PyObject *func): Abkürzung für PyCCall_CCALLROOT(func)->cr_ccall->cc_flags.
• PyObject *PyCCall_SELF(PyOject *func): Abkürzung für PyCCall_CCALLROOT(func)->cr_self.

Generische Getter, die in das tp_getset-Array eingefügt werden sollen

• PyObject *PyCCall_GenericGetParent(PyObject *func, void *closure): gibt cc_parent zurück. Löst AttributeError aus, wenn cc_parent NULL ist.
• PyObject *PyCCall_GenericGetQualname(PyObject *func, void *closure): gibt einen String zurück, der als __qualname__ verwendet werden kann. Dies verwendet das __qualname__ von cc_parent, wenn möglich. Es verwendet auch das Attribut __name__.

Profiling

Die Profiling-Events c_call, c_return und c_exception werden nur beim Aufrufen von tatsächlichen Instanzen von builtin_function_or_method oder method_descriptor generiert. Dies geschieht aus Gründen der Einfachheit und auch aus Gründen der Abwärtskompatibilität (damit die Profil-Funktion keine Objekte erhält, die sie nicht erkennt). In einer zukünftigen PEP könnten wir das C-Level-Profiling auf beliebige Klassen erweitern, die das C-Aufrufprotokoll implementieren.

C-API-Funktionen

Die folgende Funktion wird hinzugefügt (auch zur stable ABI)

• PyObject * PyCFunction_ClsNew(PyTypeObject *cls, PyMethodDef *ml, PyObject *self, PyObject *module, PyObject *parent): Erstellt ein neues Objekt mit der Objektstruktur PyCFunctionObject und der Klasse cls. Die Einträge der PyMethodDef Struktur werden verwendet, um das neue Objekt zu konstruieren, aber der Zeiger auf die PyMethodDef Struktur wird nicht gespeichert. Die Flags für das C-Aufrufprotokoll werden automatisch in Bezug auf ml->ml_flags, self und parent ermittelt.

Die bestehenden Funktionen PyCFunction_New, PyCFunction_NewEx und PyDescr_NewMethod werden in Bezug auf PyCFunction_ClsNew implementiert.

Die undokumentierten Funktionen PyCFunction_GetFlags und PyCFunction_GET_FLAGS sind veraltet. Sie werden immer noch künstlich unterstützt, indem die ursprünglichen METH_... Flags in einem Bitfeld innerhalb von cc_flags gespeichert werden. Obwohl PyCFunction_GetFlags technisch Teil der stable ABI ist, ist es höchst unwahrscheinlich, dass sie so verwendet wird: Erstens ist sie nicht einmal dokumentiert. Zweitens ist das Flag METH_FASTCALL kein Teil der stable ABI, aber es ist sehr verbreitet (wegen Argument Clinic). Wenn man also METH_FASTCALL nicht unterstützen kann, ist es schwer, einen Anwendungsfall für PyCFunction_GetFlags vorzustellen. Die Tatsache, dass PyCFunction_GET_FLAGS und PyCFunction_GetFlags von CPython außerhalb von Objects/call.c gar nicht verwendet werden, zeigt weiter, dass diese Funktionen nicht besonders nützlich sind.

Warum ist das besser als PEP 575?

Eine der Hauptbeschwerden von PEP 575 war, dass sie Funktionalität (das Aufruf- und Introspektionsprotokoll) mit der Klassenhierarchie koppelte: Eine Klasse konnte von den neuen Features nur profitieren, wenn sie eine Unterklasse von base_function war. Für bestehende Klassen kann dies schwierig sein, da sie andere Einschränkungen hinsichtlich des Layouts der C-Objektstruktur haben könnten, die von einer bestehenden Basisklasse oder Implementierungsdetails herrühren. Zum Beispiel kann functools.lru_cache PEP 575 nicht wie vorgesehen implementieren.

Es komplizierte auch die Implementierung gerade deswegen, weil sowohl in den Implementierungsdetails als auch in der Klassenhierarchie Änderungen erforderlich waren.

Der aktuelle PEP hat diese Probleme nicht.

Warum den Funktionszeiger in der Instanz speichern?

Die tatsächlichen Informationen, die zum Aufrufen eines Objekts benötigt werden, werden in der Instanz (in der PyCCallDef Struktur) anstatt in der Klasse gespeichert. Dies unterscheidet sich vom tp_call Slot oder früheren Versuchen, einen tp_fastcall Slot zu implementieren [1].

Der Hauptanwendungsfall sind eingebaute Funktionen und Methoden. Für diese hängt die aufzurufende C-Funktion von der Instanz ab.

Beachten Sie, dass das aktuelle Protokoll die Unterstützung für den Fall erleichtert, dass die gleiche C-Funktion für alle Instanzen aufgerufen wird: Verwenden Sie einfach eine einzige statische PyCCallDef Struktur für jede Instanz.

Warum CCALL_OBJCLASS?

Das Flag CCALL_OBJCLASS ist dazu gedacht, verschiedene Fälle zu unterstützen, in denen die Klasse eines self-Arguments überprüft werden muss, wie z.B.

>>> list.append({}, None)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: append() requires a 'list' object but received a 'dict'

>>> list.__len__({})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor '__len__' requires a 'list' object but received a 'dict'

>>> float.__dict__["fromhex"](list, "0xff")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor 'fromhex' for type 'float' doesn't apply to type 'list'

In der Referenzimplementierung nutzt nur die erste dieser Anwendungen den neuen Code. Die anderen Beispiele zeigen, dass diese Art von Prüfungen an mehreren Stellen vorkommen, sodass es sinnvoll ist, generische Unterstützung dafür hinzuzufügen.

Warum CCALL_SELFARG?

Das Flag CCALL_SELFARG und das Konzept des Self-Slicings sind notwendig, um Methoden zu unterstützen: Die C-Funktion sollte nicht darauf angewiesen sein, ob sie als ungebundene Methode oder als gebundene Methode aufgerufen wird. In beiden Fällen sollte ein self-Argument vorhanden sein, und dies ist einfach das erste Positionsargument eines Aufrufs einer ungebundenen Methode.

Zum Beispiel ist list.append eine METH_O-Methode. Sowohl die Aufrufe list.append([], 42) als auch [].append(42) sollten zu dem C-Aufruf list_append([], 42) übersetzt werden.

Dank des vorgeschlagenen C-Aufrufprotokolls können wir dies so unterstützen, dass sowohl die ungebundene als auch die gebundene Methode eine PyCCallDef Struktur (mit dem gesetzten Flag CCALL_SELFARG) gemeinsam nutzen.

Daher hat CCALL_SELFARG zwei Vorteile: Es gibt keine zusätzliche Indirektionsebene für den Aufruf von Methoden, und die Erstellung von gebundenen Methoden erfordert nicht die Einrichtung einer PyCCallDef Struktur.

Ein weiterer kleiner Vorteil ist, dass wir die Fehlermeldungen für eine falsche Aufrufsignatur zwischen Python-Methoden und eingebauten Methoden einheitlicher gestalten könnten. Im folgenden Beispiel ist sich Python nicht sicher, ob eine Methode 1 oder 2 Argumente annimmt

>>> class List(list):
...     def myappend(self, item):
...         self.append(item)
>>> List().myappend(1, 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: myappend() takes 2 positional arguments but 3 were given
>>> List().append(1, 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: append() takes exactly one argument (2 given)

Es ist derzeit für PyCFunction_Call unmöglich, die tatsächliche Anzahl benutzer-sichtbarer Argumente zu kennen, da es zur Laufzeit nicht zwischen einer Funktion (ohne self-Argument) und einer gebundenen Methode (mit self-Argument) unterscheiden kann. Das Flag CCALL_SELFARG macht diesen Unterschied explizit.

Warum CCALL_DEFARG?

Das Flag CCALL_DEFARG gibt dem Aufgerufenen Zugriff auf das PyCCallDef *. Dafür gibt es verschiedene Anwendungsfälle

1. Der Aufgerufene kann das Feld cc_parent verwenden, was für PEP 573 nützlich ist.
2. Anwendungen können die PyCCallDef Struktur frei mit benutzerdefinierten Feldern erweitern, auf die dann analog zugegriffen werden kann.
3. In dem Fall, dass die PyCCallDef Struktur Teil der Objektstruktur ist (was z.B. für PyCFunctionObject zutrifft), kann ein geeigneter Offset vom PyCCallDef Zeiger abgezogen werden, um einen Zeiger auf das aufrufbare Objekt zu erhalten, das diese PyCCallDef definiert.

Eine frühere Version dieses PEP definierte ein Flag CCALL_FUNCARG anstelle von CCALL_DEFARG, das das aufrufbare Objekt an den Aufgerufenen übergeben hätte. Dies hatte ähnliche Anwendungsfälle, aber es gab eine gewisse Mehrdeutigkeit bei gebundenen Methoden: Sollte das "aufrufbare Objekt" das gebundene Methodenobjekt oder die vom Methode umschlossene ursprüngliche Funktion sein? Durch die Übergabe des PyCCallDef * stattdessen entfällt diese Mehrdeutigkeit, da die gebundene Methode die PyCCallDef * von der umschlossenen Funktion verwendet.

Ersetzen von tp_print

Wir verwenden tp_print als tp_ccalloffset wieder, da dies externen Projekten das Zurückportieren des C-Aufrufprotokolls auf frühere Python-Versionen erleichtert. Insbesondere das Cython-Projekt hat Interesse daran gezeigt (siehe https://mail.python.org/pipermail/python-dev/2018-June/153927.html).