Kapslar

Se Tillhandahålla ett C API för en tilläggsmodul för mer information om hur du använder dessa objekt.

Tillagd i version 3.1.

type PyCapsule

Denna subtyp av PyObject representerar ett opakt värde, användbart för C-tilläggsmoduler som behöver skicka ett opakt värde (som en void*-pekare) genom Python-kod till annan C-kod. Det används ofta för att göra en C-funktionspekare som definieras i en modul tillgänglig för andra moduler, så att den vanliga importmekanismen kan användas för att komma åt C API:er som definieras i dynamiskt laddade moduler.

type PyCapsule_Destructor
En del av Stabil ABI.

Typen av ett destruktoranrop för en kapsel. Definierad som:

typedef void (*PyCapsule_Destructor)(PyObject *);

Se PyCapsule_New() för semantiken för PyCapsule_Destructor callbacks.

int PyCapsule_CheckExact(PyObject *p)

Returnerar true om dess argument är en PyCapsule. Denna funktion lyckas alltid.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa en PyCapsule som kapslar in pekaren. Argumentet pekare får inte vara NULL.

Vid misslyckande, sätt ett undantag och returnera NULL.

Strängen name kan antingen vara NULL eller en pekare till en giltig C-sträng. Om den inte är NULL måste denna sträng överleva kapseln. (Det är dock tillåtet att frigöra den i destructor.)

Om argumentet destructor inte är NULL, kommer den att anropas med kapseln som argument när den förstörs.

Om denna kapsel skall lagras som ett attribut i en modul, skall namnet anges som modulename.attributename. Detta gör det möjligt för andra moduler att importera kapseln med hjälp av PyCapsule_Import().

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
En del av Stabil ABI.

Hämtar pekaren som finns lagrad i kapseln. Vid misslyckande, sätt ett undantag och returnera NULL.

Parametern name måste jämföras exakt med det namn som lagrats i kapseln. Om namnet som lagras i kapseln är NULL, måste name som skickas in också vara NULL. Python använder C-funktionen strcmp() för att jämföra kapselnamn.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
En del av Stabil ABI.

Returnerar den aktuella destruktorn som finns lagrad i kapseln. Vid misslyckande, sätt ett undantag och returnera NULL.

Det är lagligt för en kapsel att ha en NULL destruktor. Detta gör att en NULL returkod är något tvetydig; använd PyCapsule_IsValid() eller PyErr_Occurred() för att reda ut det.

void *PyCapsule_GetContext(PyObject *capsule)
En del av Stabil ABI.

Returnerar det aktuella sammanhanget som lagrats i kapseln. Vid misslyckande anges ett undantag och NULL returneras.

Det är lagligt för en kapsel att ha en NULL kontext. Detta gör att en NULL returkod är något tvetydig; använd PyCapsule_IsValid() eller PyErr_Occurred() för att reda ut det.

const char *PyCapsule_GetName(PyObject *capsule)
En del av Stabil ABI.

Returnerar det aktuella namnet som lagrats i kapseln. Vid misslyckande, sätt ett undantag och returnera NULL.

Det är lagligt för en kapsel att ha ett NULL namn. Detta gör att en NULL returkod är något tvetydig; använd PyCapsule_IsValid() eller PyErr_Occurred() för att reda ut det.

void *PyCapsule_Import(const char *name, int no_block)
En del av Stabil ABI.

Importerar en pekare till ett C-objekt från ett kapselattribut i en modul. Parametern name bör ange det fullständiga namnet på attributet, som i module.attribute. Det namn som lagras i kapseln måste matcha denna sträng exakt.

Denna funktion delar upp namn på tecknet . och importerar det första elementet. Den bearbetar sedan ytterligare element med hjälp av attributuppslagningar.

Returnerar kapselns interna pekare vid framgång. Vid misslyckande, sätt ett undantag och returnera NULL.

Anteckning

Om name pekar på ett attribut för en undermodul eller ett underpaket måste denna undermodul eller detta underpaket tidigare ha importerats på annat sätt (t.ex. genom att använda PyImport_ImportModule()) för att attributuppslagningarna ska lyckas.

Ändrad i version 3.3: no_block har ingen effekt längre.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
En del av Stabil ABI.

Avgör om capsule är en giltig kapsel eller inte. En giltig kapsel är inte NULL, klarar PyCapsule_CheckExact(), har en pekare som inte är NULL lagrad i den och dess interna namn matchar parametern name. (Se PyCapsule_GetPointer() för information om hur kapselnamn jämförs)

Med andra ord, om PyCapsule_IsValid() returnerar ett sant värde, kommer anrop till någon av accessorerna (alla funktioner som börjar med PyCapsule_Get) garanterat att lyckas.

Returnerar ett värde som inte är noll om objektet är giltigt och matchar namnet som skickades in. Returnerar annars 0. Denna funktion kommer inte att misslyckas.

int PyCapsule_SetContext(PyObject *capsule, void *context)
En del av Stabil ABI.

Ställ in kontextpekaren i capsule till context.

Returnera 0 vid framgång. Returnerar icke-noll och sätter ett undantag vid misslyckande.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
En del av Stabil ABI.

Ställ in destruktorn inuti capsule till destructor.

Returnera 0 vid framgång. Returnerar icke-noll och sätter ett undantag vid misslyckande.

int PyCapsule_SetName(PyObject *capsule, const char *name)
En del av Stabil ABI.

Ställ in namnet inuti kapsel till namn. Om det inte är NULL måste namnet överleva kapseln. Om det tidigare namn som lagrades i kapseln inte var NULL, görs inget försök att frigöra det.

Returnera 0 vid framgång. Returnerar icke-noll och sätter ett undantag vid misslyckande.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
En del av Stabil ABI.

Ställ in void-pekaren inuti capsule till pointer. Pekaren får inte vara NULL.

Returnera 0 vid framgång. Returnerar icke-noll och sätter ett undantag vid misslyckande.