Capsules

Weitere Informationen zur Verwendung dieser Objekte finden Sie unter Bereitstellen einer C-API für ein Erweiterungsmodul.

Hinzugefügt in Version 3.1.

Typ PyCapsule

Dieser Untertyp von PyObject repräsentiert einen undurchsichtigen Wert, der für C-Erweiterungsmodule nützlich ist, die einen undurchsichtigen Wert (als void*-Zeiger) über Python-Code an anderen C-Code übergeben müssen. Er wird oft verwendet, um einen Funktionszeiger in C, der in einem Modul definiert ist, für andere Module verfügbar zu machen, damit der reguläre Importmechanismus zum Zugriff auf C-APIs verwendet werden kann, die in dynamisch geladenen Modulen definiert sind.

Typ PyCapsule_Destructor

Teil der Stable ABI.

Der Typ einer Destruktor-Callback für eine Kapsel. Definiert als

typedef void (*PyCapsule_Destructor)(PyObject *);

Die Semantik von PyCapsule_Destructor-Callbacks finden Sie unter PyCapsule_New().

int PyCapsule_CheckExact(PyObject *p)

Gibt `true` zurück, wenn das Argument eine PyCapsule ist. Diese Funktion ist immer erfolgreich.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

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

Erstellt eine PyCapsule, die den pointer kapselt. Das Argument pointer darf nicht NULL sein.

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

Der name-String kann entweder NULL oder ein Zeiger auf einen gültigen C-String sein. Wenn er nicht NULL ist, muss dieser String die Kapsel überdauern. (Es ist jedoch erlaubt, ihn innerhalb des destructor freizugeben.)

Wenn das Argument destructor nicht NULL ist, wird es mit der Kapsel als Argument aufgerufen, wenn diese zerstört wird.

Wenn diese Kapsel als Attribut eines Moduls gespeichert wird, sollte der name als modulename.attributename angegeben werden. Dadurch können andere Module die Kapsel mithilfe von PyCapsule_Import() importieren.

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

Teil der Stable ABI.

Ruft den in der Kapsel gespeicherten pointer ab. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Der Parameter name muss exakt mit dem in der Kapsel gespeicherten Namen übereinstimmen. Wenn der in der Kapsel gespeicherte Name NULL ist, muss auch der übergebene name NULL sein. Python verwendet die C-Funktion strcmp() zum Vergleichen von Kapselnamen.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

Teil der Stable ABI.

Gibt den aktuell in der Kapsel gespeicherten Destruktor zurück. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Es ist legal, dass eine Kapsel einen NULL-Destruktor hat. Dies macht einen NULL-Rückgabewert etwas mehrdeutig; verwenden Sie PyCapsule_IsValid() oder PyErr_Occurred() zur Unterscheidung.

void *PyCapsule_GetContext(PyObject *capsule)

Teil der Stable ABI.

Gibt den aktuell in der Kapsel gespeicherten Kontext zurück. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Es ist legal, dass eine Kapsel einen NULL-Kontext hat. Dies macht einen NULL-Rückgabewert etwas mehrdeutig; verwenden Sie PyCapsule_IsValid() oder PyErr_Occurred() zur Unterscheidung.

const char *PyCapsule_GetName(PyObject *capsule)

Teil der Stable ABI.

Gibt den aktuell in der Kapsel gespeicherten Namen zurück. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Es ist legal, dass eine Kapsel einen NULL-Namen hat. Dies macht einen NULL-Rückgabewert etwas mehrdeutig; verwenden Sie PyCapsule_IsValid() oder PyErr_Occurred() zur Unterscheidung.

void *PyCapsule_Import(const char *name, int no_block)

Teil der Stable ABI.

Importiert einen Zeiger auf ein C-Objekt aus einem Kapselattribut in einem Modul. Der Parameter name sollte den vollständigen Namen des Attributs angeben, z. B. modulename.attributename. Der in der Kapsel gespeicherte Name muss exakt mit diesem String übereinstimmen.

Diese Funktion teilt name anhand des Zeichens . auf und importiert das erste Element. Anschliessend werden weitere Elemente mittels Attribut-Lookups verarbeitet.

Gibt den internen pointer der Kapsel bei Erfolg zurück. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Hinweis

Wenn name auf ein Attribut eines Untermoduls oder einer Unterpakets zeigt, muss dieses Untermodul oder diese Unterpaket zuvor auf andere Weise importiert worden sein (z. B. durch Verwendung von PyImport_ImportModule()), damit die Attribut-Lookups erfolgreich sind.

Geändert in Version 3.3: no_block hat keine Auswirkung mehr.

int PyCapsule_IsValid(PyObject *capsule, const char *name)

Teil der Stable ABI.

Bestimmt, ob capsule eine gültige Kapsel ist. Eine gültige Kapsel ist nicht NULL, besteht PyCapsule_CheckExact(), enthält einen nicht NULL-Zeiger, und ihr interner Name stimmt mit dem Parameter name überein. (Siehe PyCapsule_GetPointer() für Informationen, wie Kapselnamen verglichen werden.)

Mit anderen Worten: Wenn PyCapsule_IsValid() einen wahren Wert zurückgibt, sind Aufrufe von beliebigen Zugriffsmethoden (Funktionen, die mit PyCapsule_Get beginnen) garantiert erfolgreich.

Gibt einen Wert ungleich Null zurück, wenn das Objekt gültig ist und mit dem übergebenen Namen übereinstimmt. Gibt andernfalls 0 zurück. Diese Funktion schlägt nicht fehl.

int PyCapsule_SetContext(PyObject *capsule, void *context)

Teil der Stable ABI.

Setzt den Kontextzeiger innerhalb von capsule auf context.

Gibt bei Erfolg 0 zurück. Gibt andernfalls einen Wert ungleich Null zurück und setzt eine Ausnahme.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Teil der Stable ABI.

Setzt den Destruktor innerhalb von capsule auf destructor.

Gibt bei Erfolg 0 zurück. Gibt andernfalls einen Wert ungleich Null zurück und setzt eine Ausnahme.

int PyCapsule_SetName(PyObject *capsule, const char *name)

Teil der Stable ABI.

Setzt den Namen innerhalb von capsule auf name. Wenn name nicht NULL ist, muss der Name die Kapsel überdauern. Wenn der vorherige in der Kapsel gespeicherte name nicht NULL war, wird keine Freigabe versucht.

Gibt bei Erfolg 0 zurück. Gibt andernfalls einen Wert ungleich Null zurück und setzt eine Ausnahme.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Teil der Stable ABI.

Setzt den Void-Zeiger innerhalb von capsule auf pointer. Der Zeiger darf nicht NULL sein.

Gibt bei Erfolg 0 zurück. Gibt andernfalls einen Wert ungleich Null zurück und setzt eine Ausnahme.