Objektprotokoll¶

PyObject *Py_GetConstant(unsigned int constant_id)¶

Teil des Stable ABI seit Version 3.13.

Ruft eine starke Referenz auf eine Konstante ab.

Setzt eine Ausnahme und gibt NULL zurück, wenn constant_id ungültig ist.

constant_id muss einer der folgenden Konstantenbezeichner sein

Konstantenbezeichner	Wert	Zurückgegebenes Objekt
Py_CONSTANT_NONE¶	`0`	`None`
Py_CONSTANT_FALSE¶	`1`	`Falsch`
Py_CONSTANT_TRUE¶	`2`	`Wahr`
Py_CONSTANT_ELLIPSIS¶	`3`	`Ellipsis`
Py_CONSTANT_NOT_IMPLEMENTED¶	`4`	`NotImplemented`
Py_CONSTANT_ZERO¶	`5`	`0`
Py_CONSTANT_ONE¶	`6`	`1`
Py_CONSTANT_EMPTY_STR¶	`7`	`''`
Py_CONSTANT_EMPTY_BYTES¶	`8`	`b''`
Py_CONSTANT_EMPTY_TUPLE¶	`9`	`()`

Numerische Werte werden nur für Projekte angegeben, die die Konstantenbezeichner nicht verwenden können.

Hinzugefügt in Version 3.13.

CPython Implementierungsdetail: In CPython sind alle diese Konstanten unsterblich.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶

Teil des Stable ABI seit Version 3.13.

Ähnlich wie Py_GetConstant(), gibt aber eine geborgte Referenz zurück.

Diese Funktion ist hauptsächlich für die Abwärtskompatibilität gedacht: die Verwendung von Py_GetConstant() wird für neuen Code empfohlen.

Die Referenz wird vom Interpreter ausgeliehen und ist bis zur Finalisierung des Interpreters gültig.

Hinzugefügt in Version 3.13.

PyObject *Py_NotImplemented¶: Das NotImplemented Singleton, das verwendet wird, um anzuzeigen, dass eine Operation für die gegebene Typkombination nicht implementiert ist.

Py_RETURN_NOTIMPLEMENTED¶: Behandelt korrekt die Rückgabe von Py_NotImplemented aus einer C-Funktion heraus (d.h. erstellt eine neue starke Referenz auf NotImplemented und gibt diese zurück).

Py_PRINT_RAW¶: Flag, das mit mehreren Funktionen verwendet werden kann, die das Objekt ausgeben (wie z.B. PyObject_Print() und PyFile_WriteObject()). Wenn es übergeben wird, verwenden diese Funktionen die str() des Objekts anstelle der repr().

int PyObject_Print(PyObject *o, FILE *fp, int flags)¶: Gibt ein Objekt o auf der Datei fp aus. Gibt -1 bei einem Fehler zurück. Das Argument flags wird verwendet, um bestimmte Ausgabeoptionen zu aktivieren. Die einzige derzeit unterstützte Option ist Py_PRINT_RAW; wenn diese angegeben wird, wird die str() des Objekts anstelle der repr() ausgegeben.

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)¶: Teil des Stable ABI seit Version 3.13.
Gibt 1 zurück, wenn o das Attribut attr_name hat, und 0 andernfalls. Dies entspricht dem Python-Ausdruck hasattr(o, attr_name). Bei einem Fehler wird -1 zurückgegeben.

Hinzugefügt in Version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶: Teil des Stable ABI seit Version 3.13.
Dies ist dasselbe wie PyObject_HasAttrWithError(), aber attr_name wird als UTF-8-kodierter Byte-String vom Typ const char* angegeben, anstatt als PyObject*.

Hinzugefügt in Version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶: Teil der Stable ABI.
Gibt 1 zurück, wenn o das Attribut attr_name hat, und 0 andernfalls. Diese Funktion ist immer erfolgreich.

Hinweis

Ausnahmen, die auftreten, wenn diese Funktion die Methoden __getattr__() und __getattribute__() aufruft, werden nicht weitergegeben, sondern an sys.unraisablehook() übergeben. Für eine ordnungsgemäße Fehlerbehandlung verwenden Sie stattdessen PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() oder PyObject_GetAttr().

int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶: Teil der Stable ABI.
Dies ist dasselbe wie PyObject_HasAttr(), aber attr_name wird als UTF-8-kodierter Byte-String vom Typ const char* angegeben, anstatt als PyObject*.

Hinweis

Ausnahmen, die auftreten, wenn diese Funktion die Methoden __getattr__() und __getattribute__() aufruft oder während der Erstellung des temporären str-Objekts, werden stillschweigend ignoriert. Für eine ordnungsgemäße Fehlerbehandlung verwenden Sie stattdessen PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() oder PyObject_GetAttrString().

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Ruft ein Attribut mit dem Namen attr_name vom Objekt o ab. Gibt den Attributwert bei Erfolg oder NULL bei einem Fehler zurück. Dies ist das Äquivalent des Python-Ausdrucks o.attr_name.

Wenn das fehlende Attribut nicht als Fehler behandelt werden soll, können Sie stattdessen PyObject_GetOptionalAttr() verwenden.

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Dies ist dasselbe wie PyObject_GetAttr(), aber attr_name wird als UTF-8-kodierter Byte-String vom Typ const char* angegeben, anstatt als PyObject*.

Wenn das fehlende Attribut nicht als Fehler behandelt werden soll, können Sie stattdessen PyObject_GetOptionalAttrString() verwenden.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶

Teil des Stable ABI seit Version 3.13.

Variante von PyObject_GetAttr(), die keine AttributeError auslöst, wenn das Attribut nicht gefunden wird.

Wenn das Attribut gefunden wird, gibt die Funktion 1 zurück und setzt *result auf eine neue starke Referenz auf das Attribut. Wenn das Attribut nicht gefunden wird, gibt die Funktion 0 zurück und setzt *result auf NULL; die AttributeError wird unterdrückt. Wenn ein anderer Fehler als eine AttributeError auftritt, gibt die Funktion -1 zurück und setzt *result auf NULL.

Hinzugefügt in Version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶: Teil des Stable ABI seit Version 3.13.
Dies ist dasselbe wie PyObject_GetOptionalAttr(), aber attr_name wird als UTF-8-kodierter Byte-String vom Typ const char* angegeben, anstatt als PyObject*.

Hinzugefügt in Version 3.13.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Generische Attribut-Getter-Funktion, die für den tp_getattro Slot eines Typobjekts vorgesehen ist. Sie sucht nach einem Deskriptor im Wörterbuch der Klassen in der MRO des Objekts sowie nach einem Attribut im __dict__ des Objekts (falls vorhanden). Wie in Deskriptoren implementieren beschrieben, haben Daten-Deskriptoren Vorrang vor Instanzattributen, während Nicht-Daten-Deskriptoren dies nicht tun. Andernfalls wird eine AttributeError ausgelöst.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶

Teil der Stable ABI.

Setzt den Wert des Attributs mit dem Namen attr_name für das Objekt o auf den Wert v. Löst im Fehlerfall eine Ausnahme aus und gibt -1 zurück; gibt 0 bei Erfolg zurück. Dies ist das Äquivalent des Python-Statements o.attr_name = v.

Wenn v NULL ist, wird das Attribut gelöscht. Dieses Verhalten ist veraltet zugunsten der Verwendung von PyObject_DelAttr(), aber es gibt derzeit keine Pläne, es zu entfernen.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶

Teil der Stable ABI.

Dies ist dasselbe wie PyObject_SetAttr(), aber attr_name wird als UTF-8-kodierter Byte-String vom Typ const char* angegeben, anstatt als PyObject*.

Wenn v NULL ist, wird das Attribut gelöscht, aber diese Funktion ist veraltet zugunsten der Verwendung von PyObject_DelAttrString().

Die Anzahl der verschiedenen Attributnamen, die dieser Funktion übergeben werden, sollte gering gehalten werden, normalerweise durch Verwendung eines statisch zugewiesenen Strings als attr_name. Für zur Kompilierungszeit nicht bekannte Attributnamen ist es vorzuziehen, PyUnicode_FromString() und PyObject_SetAttr() direkt aufzurufen. Weitere Details finden Sie unter PyUnicode_InternFromString(), das intern zum Erstellen eines Schlüsselobjekts verwendet werden kann.

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶: Teil der Stable ABI.
Generische Attribut-Setter- und Deleter-Funktion, die für den tp_setattro Slot eines Typobjekts vorgesehen ist. Sie sucht nach einem Daten-Deskriptor im Wörterbuch der Klassen in der MRO des Objekts und bevorzugt diesen, wenn er gefunden wird, gegenüber dem Setzen oder Löschen des Attributs im Instanzwörterbuch. Andernfalls wird das Attribut im __dict__ des Objekts gesetzt oder gelöscht (falls vorhanden). Bei Erfolg wird 0 zurückgegeben, andernfalls wird eine AttributeError ausgelöst und -1 zurückgegeben.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶: Teil des Stable ABI seit Version 3.13.
Löscht das Attribut mit dem Namen attr_name für das Objekt o. Gibt -1 bei einem Fehler zurück. Dies ist das Äquivalent des Python-Statements del o.attr_name.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶

Teil des Stable ABI seit Version 3.13.

Dies ist dasselbe wie PyObject_DelAttr(), aber attr_name wird als UTF-8-kodierter Byte-String const char* angegeben, anstatt als PyObject*.

Die Anzahl der an diese Funktion übergebenen unterschiedlichen Attributnamen sollte klein gehalten werden, normalerweise durch Verwendung eines statisch zugewiesenen Strings als attr_name. Für Attributnamen, die zur Kompilierzeit nicht bekannt sind, ist es vorzuziehen, PyUnicode_FromString() und PyObject_DelAttr() direkt aufzurufen. Weitere Details finden Sie unter PyUnicode_InternFromString(), das intern verwendet werden kann, um ein Schlüsselobjekt für die Suche zu erstellen.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.10.

Eine generische Implementierung für den Getter eines __dict__-Deskriptors. Es erstellt das Dictionary bei Bedarf.

Diese Funktion kann auch aufgerufen werden, um das __dict__ des Objekts o abzurufen. Übergeben Sie NULL für context, wenn Sie sie aufrufen. Da diese Funktion möglicherweise Speicher für das Dictionary zuweisen muss, kann es effizienter sein, PyObject_GetAttr() aufzurufen, wenn auf ein Attribut des Objekts zugegriffen wird.

Bei einem Fehler wird NULL mit einer gesetzten Ausnahme zurückgegeben.

Hinzugefügt in Version 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶: Teil der Stable ABI seit Version 3.7.
Eine generische Implementierung für den Setter eines __dict__-Deskriptors. Diese Implementierung erlaubt nicht, das Dictionary zu löschen.

Hinzugefügt in Version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)¶

Gibt einen Zeiger auf __dict__ des Objekts obj zurück. Wenn kein __dict__ vorhanden ist, wird NULL zurückgegeben, ohne eine Ausnahme zu setzen.

Diese Funktion muss möglicherweise Speicher für das Dictionary zuweisen, daher kann es effizienter sein, PyObject_GetAttr() aufzurufen, wenn auf ein Attribut des Objekts zugegriffen wird.

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Vergleicht die Werte von o1 und o2 unter Verwendung der durch opid angegebenen Operation, die eine der folgenden sein muss: Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT oder Py_GE, entsprechend <, <=, ==, !=, > oder >=. Dies entspricht dem Python-Ausdruck o1 op o2, wobei op der Operator ist, der opid entspricht. Gibt bei Erfolg den Wert des Vergleichs zurück, bei Fehler NULL.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶: Teil der Stable ABI.
Vergleicht die Werte von o1 und o2 unter Verwendung der durch opid angegebenen Operation, wie PyObject_RichCompare(), gibt jedoch bei Fehlern -1, bei einem falschen Ergebnis 0 und ansonsten 1 zurück.

Hinweis

Wenn o1 und o2 dasselbe Objekt sind, gibt PyObject_RichCompareBool() für Py_EQ immer 1 und für Py_NE immer 0 zurück.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶

Teil der Stable ABI.

Formatiert obj unter Verwendung von format_spec. Dies entspricht dem Python-Ausdruck format(obj, format_spec).

format_spec kann NULL sein. In diesem Fall entspricht der Aufruf format(obj). Gibt bei Erfolg den formatierten String zurück, bei Fehler NULL.

PyObject *PyObject_Repr(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Berechnet eine String-Darstellung des Objekts o. Gibt bei Erfolg die String-Darstellung zurück, bei Fehler NULL. Dies entspricht dem Python-Ausdruck repr(o). Wird von der integrierten Funktion repr() aufgerufen.

Geändert in Version 3.4: Diese Funktion enthält jetzt eine Debug-Assertion, um sicherzustellen, dass sie keine aktive Ausnahme stillschweigend verwirft.

PyObject *PyObject_ASCII(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Wie PyObject_Repr() berechnet es eine String-Darstellung des Objekts o, maskiert jedoch die Nicht-ASCII-Zeichen im von PyObject_Repr() zurückgegebenen String mit \x-, \u- oder \U-Escapes. Dies erzeugt einen String, der dem von PyObject_Repr() in Python 2 zurückgegebenen ähnelt. Wird von der integrierten Funktion ascii() aufgerufen.

PyObject *PyObject_Str(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Berechnet eine String-Darstellung des Objekts o. Gibt bei Erfolg die String-Darstellung zurück, bei Fehler NULL. Dies entspricht dem Python-Ausdruck str(o). Wird von der integrierten Funktion str() und damit auch von der Funktion print() aufgerufen.

Geändert in Version 3.4: Diese Funktion enthält jetzt eine Debug-Assertion, um sicherzustellen, dass sie keine aktive Ausnahme stillschweigend verwirft.

PyObject *PyObject_Bytes(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Berechnet eine Byte-Darstellung des Objekts o. NULL wird bei Fehlern zurückgegeben und ein Bytes-Objekt bei Erfolg. Dies entspricht dem Python-Ausdruck bytes(o), wenn o keine Ganzzahl ist. Im Gegensatz zu bytes(o) wird bei einer Ganzzahl o ein TypeError ausgelöst, anstatt eines mit Nullen initialisierten Bytes-Objekts.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶

Teil der Stable ABI.

Gibt 1 zurück, wenn die Klasse derived identisch mit der Klasse cls ist oder von ihr abgeleitet ist, andernfalls gibt sie 0 zurück. Im Fehlerfall wird -1 zurückgegeben.

Wenn cls ein Tupel ist, wird die Prüfung gegen jeden Eintrag in cls durchgeführt. Das Ergebnis ist 1, wenn mindestens eine der Prüfungen 1 zurückgibt, andernfalls 0.

Wenn cls eine Methode __subclasscheck__() hat, wird diese aufgerufen, um den Unterklassenstatus zu bestimmen, wie in PEP 3119 beschrieben. Andernfalls ist derived eine Unterklasse von cls, wenn sie eine direkte oder indirekte Unterklasse ist, d.h. in cls.__mro__ enthalten ist.

Normalerweise werden nur Klassenobjekte, d.h. Instanzen von type oder einer abgeleiteten Klasse, als Klassen betrachtet. Objekte können dies jedoch überschreiben, indem sie ein Attribut __bases__ haben (das ein Tupel von Basisklassen sein muss).

int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶

Teil der Stable ABI.

Gibt 1 zurück, wenn inst eine Instanz der Klasse cls oder eine Unterklasse von cls ist, und 0, wenn nicht. Bei einem Fehler wird -1 zurückgegeben und eine Ausnahme gesetzt.

Wenn cls ein Tupel ist, wird die Prüfung gegen jeden Eintrag in cls durchgeführt. Das Ergebnis ist 1, wenn mindestens eine der Prüfungen 1 zurückgibt, andernfalls 0.

Wenn cls eine Methode __instancecheck__() hat, wird diese aufgerufen, um den Unterklassenstatus zu bestimmen, wie in PEP 3119 beschrieben. Andernfalls ist inst eine Instanz von cls, wenn ihre Klasse eine Unterklasse von cls ist.

Eine Instanz inst kann überschreiben, was als ihre Klasse gilt, indem sie ein Attribut __class__ hat.

Ein Objekt cls kann überschreiben, ob es als Klasse gilt und was seine Basisklassen sind, indem es ein Attribut __bases__ hat (das ein Tupel von Basisklassen sein muss).

Py_hash_t PyObject_Hash(PyObject *o)¶: Teil der Stable ABI.
Berechnet und gibt den Hashwert eines Objekts o zurück. Bei Fehler wird -1 zurückgegeben. Dies entspricht dem Python-Ausdruck hash(o).

Geändert in Version 3.2: Der Rückgabetyp ist jetzt Py_hash_t. Dies ist eine vorzeichenbehaftete Ganzzahl gleicher Größe wie Py_ssize_t.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶: Teil der Stable ABI.
Setzt einen TypeError, der angibt, dass type(o) nicht hashbar ist und gibt -1 zurück. Diese Funktion erhält eine besondere Behandlung, wenn sie in einem tp_hash-Slot gespeichert wird, wodurch ein Typ dem Interpreter explizit anzeigen kann, dass er nicht hashbar ist.

int PyObject_IsTrue(PyObject *o)¶: Teil der Stable ABI.
Gibt 1 zurück, wenn das Objekt o als wahr gilt, und 0 andernfalls. Dies entspricht dem Python-Ausdruck not not o. Bei einem Fehler wird -1 zurückgegeben.

int PyObject_Not(PyObject *o)¶: Teil der Stable ABI.
Gibt 0 zurück, wenn das Objekt o als wahr gilt, und 1 andernfalls. Dies entspricht dem Python-Ausdruck not o. Bei einem Fehler wird -1 zurückgegeben.

PyObject *PyObject_Type(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Wenn o nicht NULL ist, gibt diese Funktion ein Typobjekt zurück, das dem Objekttyp von Objekt o entspricht. Bei einem Fehler wird SystemError ausgelöst und NULL zurückgegeben. Dies entspricht dem Python-Ausdruck type(o). Diese Funktion erstellt eine neue starke Referenz auf den Rückgabewert. Es gibt keinen wirklichen Grund, diese Funktion anstelle der Funktion Py_TYPE() zu verwenden, die einen Zeiger vom Typ PyTypeObject* zurückgibt, außer wenn eine neue starke Referenz benötigt wird.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)¶: Gibt einen Wert ungleich Null zurück, wenn das Objekt o vom Typ type oder einer Unterklasse von type ist, und andernfalls 0. Beide Parameter dürfen nicht NULL sein.

Py_ssize_t PyObject_Size(PyObject *o)¶
Py_ssize_t PyObject_Length(PyObject *o)¶: Teil der Stable ABI.
Gibt die Länge des Objekts o zurück. Wenn das Objekt o entweder das Sequenz- oder das Mapping-Protokoll bereitstellt, wird die Sequenzlänge zurückgegeben. Bei einem Fehler wird -1 zurückgegeben. Dies entspricht dem Python-Ausdruck len(o).

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶: Gibt eine geschätzte Länge für das Objekt o zurück. Versucht zuerst, seine tatsächliche Länge zurückzugeben, dann eine Schätzung mithilfe von __length_hint__() und gibt schließlich den Standardwert zurück. Bei einem Fehler wird -1 zurückgegeben. Dies entspricht dem Python-Ausdruck operator.length_hint(o, defaultvalue).

Hinzugefügt in Version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Gibt das Element von o zurück, das dem Objekt key entspricht, oder NULL bei Fehler. Dies entspricht dem Python-Ausdruck o[key].

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶: Teil der Stable ABI.
Ordnet das Objekt key dem Wert v zu. Löst bei einem Fehler eine Ausnahme aus und gibt -1 zurück; gibt bei Erfolg 0 zurück. Dies entspricht der Python-Anweisung o[key] = v. Diese Funktion stiehlt keine Referenz an v.

int PyObject_DelItem(PyObject *o, PyObject *key)¶: Teil der Stable ABI.
Entfernt die Zuordnung für das Objekt key aus dem Objekt o. Gibt bei Fehler -1 zurück. Dies entspricht der Python-Anweisung del o[key].

int PyObject_DelItemString(PyObject *o, const char *key)¶: Teil der Stable ABI.
Dies ist dasselbe wie PyObject_DelItem(), aber key ist als ein UTF-8-kodierter Bytes-String vom Typ const char* angegeben, anstatt als ein PyObject*.

PyObject *PyObject_Dir(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Dies ist äquivalent zum Python-Ausdruck dir(o) und gibt eine (möglicherweise leere) Liste von Strings zurück, die für das Objekt-Argument geeignet sind, oder NULL, wenn ein Fehler aufgetreten ist. Wenn das Argument NULL ist, verhält es sich wie das Python dir() und gibt die Namen der aktuellen lokalen Variablen zurück. In diesem Fall wird NULL zurückgegeben, wenn kein Ausführungs-Frame aktiv ist, aber PyErr_Occurred() gibt falsch zurück.

PyObject *PyObject_GetIter(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Dies ist äquivalent zum Python-Ausdruck iter(o). Es gibt einen neuen Iterator für das Objekt-Argument zurück, oder das Objekt selbst, wenn das Objekt bereits ein Iterator ist. Löst TypeError aus und gibt NULL zurück, wenn das Objekt nicht iterierbar ist.

PyObject *PyObject_SelfIter(PyObject *obj)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Dies ist äquivalent zur Python-Methode __iter__(self): return self. Es ist für Iterator-Typen gedacht und wird im PyTypeObject.tp_iter-Slot verwendet.

PyObject *PyObject_GetAIter(PyObject *o)¶: Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.10.
Dies ist das Äquivalent zum Python-Ausdruck aiter(o). Nimmt ein AsyncIterable-Objekt und gibt einen AsyncIterator dafür zurück. Dies ist typischerweise ein neuer Iterator, aber wenn das Argument ein AsyncIterator ist, gibt es sich selbst zurück. Löst TypeError aus und gibt NULL zurück, wenn das Objekt nicht iterierbar ist.

Hinzugefügt in Version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶

Teil der Stable ABI seit Version 3.12.

Ruft einen Zeiger auf klassenspezifische Daten ab, die für cls reserviert sind.

Das Objekt o muss eine Instanz von cls sein, und cls muss unter Verwendung einer negativen PyType_Spec.basicsize erstellt worden sein. Python prüft dies nicht.

Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Hinzugefügt in Version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶

Teil der Stable ABI seit Version 3.12.

Gibt die Größe des für cls reservierten Instanzspeichers zurück, d.h. die Größe des Speichers, den PyObject_GetTypeData() zurückgibt.

Dies kann größer sein als mit -PyType_Spec.basicsize angefordert; es ist sicher, diese größere Größe zu verwenden (z. B. mit memset()).

Der Typ cls **muss** unter Verwendung einer negativen PyType_Spec.basicsize erstellt worden sein. Python prüft dies nicht.

Bei einem Fehler wird eine Ausnahme gesetzt und ein negativer Wert zurückgegeben.

Hinzugefügt in Version 3.12.

void *PyObject_GetItemData(PyObject *o)¶

Ruft zeigerspezifische Daten für eine Klasse mit gesetztem Py_TPFLAGS_ITEMS_AT_END ab.

Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben. TypeError wird ausgelöst, wenn o kein gesetztes Py_TPFLAGS_ITEMS_AT_END hat.

Hinzugefügt in Version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶

Besucht das verwaltete Dictionary von obj.

Diese Funktion darf nur in einer Traverse-Funktion des Typs aufgerufen werden, der das Flag Py_TPFLAGS_MANAGED_DICT gesetzt hat.

Hinzugefügt in Version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)¶

Löscht das verwaltete Dictionary von obj.

Diese Funktion darf nur in einer Clear-Funktion des Typs aufgerufen werden, der das Flag Py_TPFLAGS_MANAGED_DICT gesetzt hat.

Hinzugefügt in Version 3.13.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Aktiviert die Deferred Reference Counting für obj, falls vom Laufzeitsystem unterstützt. Im Free-Threaded-Build ermöglicht dies dem Interpreter, Anpassungen des Referenzzählers für obj zu vermeiden, was die Leistung bei Multi-Threading verbessern kann. Der Kompromiss besteht darin, dass obj erst vom Tracing-Garbage-Collector freigegeben wird und nicht, sobald der Interpreter keine Referenzen mehr darauf hat.

Diese Funktion gibt 1 zurück, wenn die Deferred Reference Counting für obj aktiviert ist, und 0, wenn die Deferred Reference Counting nicht unterstützt wird oder der Hinweis vom Interpreter ignoriert wurde, z. B. wenn die Deferred Reference Counting für obj bereits aktiviert ist. Diese Funktion ist thread-sicher und kann nicht fehlschlagen.

Diese Funktion tut nichts bei Builds mit aktiviertem GIL, die keine Deferred Reference Counting unterstützen. Sie tut auch nichts, wenn obj kein vom Garbage Collector verfolgtes Objekt ist (siehe gc.is_tracked() und PyObject_GC_IsTracked()).

Diese Funktion ist dazu gedacht, kurz nach der Erstellung von obj von dem Code, der es erstellt, verwendet zu werden, z. B. im tp_new-Slot des Objekts.

Hinzugefügt in Version 3.14.

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Prüft, ob obj ein eindeutiges temporäres Objekt ist. Gibt 1 zurück, wenn obj als eindeutiges temporäres Objekt bekannt ist, und andernfalls 0. Diese Funktion kann nicht fehlschlagen, aber die Prüfung ist konservativ und kann in einigen Fällen 0 zurückgeben, auch wenn obj ein eindeutiges temporäres Objekt ist.

Wenn ein Objekt ein eindeutiges temporäres Objekt ist, ist garantiert, dass der aktuelle Code die einzige Referenz auf das Objekt hat. Für Argumente an C-Funktionen sollte dies anstelle der Prüfung des Referenzzählers auf 1 verwendet werden. Ab Python 3.14 vermeidet der Interpreter intern einige Modifikationen des Referenzzählers beim Laden von Objekten auf den Operandenstapel, indem er Referenzen ausleiht, wann immer möglich. Das bedeutet, dass ein Referenzzähler von 1 allein nicht garantiert, dass ein Funktionsargument eindeutig referenziert wird.

Im folgenden Beispiel wird my_func mit einem eindeutigen temporären Objekt als Argument aufgerufen

my_func([1, 2, 3])

Im folgenden Beispiel wird my_func **nicht** mit einem eindeutigen temporären Objekt als Argument aufgerufen, auch wenn sein Referenzzähler 1 ist

my_list = [1, 2, 3]
my_func(my_list)

Siehe auch die Funktion Py_REFCNT().

Hinzugefügt in Version 3.14.

int PyUnstable_IsImmortal(PyObject *obj)¶: Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Diese Funktion gibt ungleich Null zurück, wenn obj unsterblich ist, und Null andernfalls. Diese Funktion kann nicht fehlschlagen.

Hinweis

Objekte, die in einer CPython-Version unsterblich sind, sind nicht garantiert in einer anderen Version unsterblich.

Hinzugefügt in Version 3.14.

int PyUnstable_TryIncRef(PyObject *obj)¶

Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Erhöht den Referenzzähler von obj, wenn dieser nicht Null ist. Gibt 1 zurück, wenn der Referenzzähler des Objekts erfolgreich erhöht wurde. Andernfalls gibt diese Funktion 0 zurück.

PyUnstable_EnableTryIncRef() muss zuvor für obj aufgerufen worden sein, sonst kann diese Funktion im Free Threading-Build fälschlicherweise 0 zurückgeben.

Diese Funktion ist logisch äquivalent zum folgenden C-Code, außer dass sie im Free Threading-Build atomar funktioniert

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   return 1;
}
return 0;

Dies ist als Baustein für die Verwaltung von schwachen Referenzen ohne den Overhead eines Python-schwachen Referenzobjekts gedacht.

Typischerweise erfordert die korrekte Verwendung dieser Funktion Unterstützung durch den Deallocator (tp_dealloc) von obj. Zum Beispiel könnte das folgende Gerüst angepasst werden, um eine "weakmap" zu implementieren, die sich wie ein WeakValueDictionary für einen bestimmten Typ verhält

PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result` is safe to use
        PyMutex_Unlock(&mutex);
        return result;
    }
    // if we get here, `result` is starting to be garbage-collected,
    // but has not been removed from the weakmap yet
    PyMutex_Unlock(&mutex);
    return NULL;
}

// tp_dealloc function for weakmap values
void
value_dealloc(PyObject *value)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

Hinzugefügt in Version 3.14.

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Aktiviert nachfolgende Verwendungen von PyUnstable_TryIncRef() auf obj. Der Aufrufer muss beim Aufruf dieser Funktion eine starke Referenz auf obj halten.

Hinzugefügt in Version 3.14.

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Ermittelt, ob op nur eine einzige Referenz hat.

Bei GIL-aktivierten Builds ist diese Funktion äquivalent zu Py_REFCNT(op) == 1.

Bei einem Free Threaded-Build prüft dies, ob der Referenzzähler von op gleich eins ist und prüft zusätzlich, ob op nur von diesem Thread verwendet wird. Py_REFCNT(op) == 1 ist bei Free Threaded Builds **nicht** thread-sicher; bevorzugen Sie diese Funktion.

Der Aufrufer muss einen angeschlossenen Thread-Zustand halten, obwohl diese Funktion nicht in den Python-Interpreter aufruft. Diese Funktion kann nicht fehlschlagen.

Hinzugefügt in Version 3.14.

Objektprotokoll¶

Vorheriges Thema

Nächstes Thema

Diese Seite