Capsules¶

Refer toProviding a C API for an Extension Module for more information on using these objects.

typePyCapsule¶

This subtype ofPyObject represents an opaque value, useful for Cextension modules who need to pass an opaque value (as avoid*pointer) through Python code to other C code. It is often used to make a Cfunction pointer defined in one module available to other modules, so theregular import mechanism can be used to access C APIs defined in dynamicallyloaded modules.

typePyCapsule_Destructor¶

Part of theStable ABI.

The type of a destructor callback for a capsule. Defined as:

typedefvoid(*PyCapsule_Destructor)(PyObject*);

SeePyCapsule_New() for the semantics of PyCapsule_Destructorcallbacks.

intPyCapsule_CheckExact(PyObject*p)¶

Return true if its argument is aPyCapsule. This function alwayssucceeds.

PyObject*PyCapsule_New(void*pointer,constchar*name,PyCapsule_Destructordestructor)¶

Return value: New reference. Part of theStable ABI.

Create aPyCapsule encapsulating thepointer. Thepointerargument may not beNULL.

On failure, set an exception and returnNULL.

Thename string may either beNULL or a pointer to a valid C string. Ifnon-NULL, this string must outlive the capsule. (Though it is permitted tofree it inside thedestructor.)

If thedestructor argument is notNULL, it will be called with thecapsule as its argument when it is destroyed.

If this capsule will be stored as an attribute of a module, thename shouldbe specified asmodulename.attributename. This will enable other modulesto import the capsule usingPyCapsule_Import().

void*PyCapsule_GetPointer(PyObject*capsule,constchar*name)¶

Part of theStable ABI.

Retrieve thepointer stored in the capsule. On failure, set an exceptionand returnNULL.

Thename parameter must compare exactly to the name stored in the capsule.If the name stored in the capsule isNULL, thename passed in must alsobeNULL. Python uses the C functionstrcmp() to compare capsulenames.

PyCapsule_DestructorPyCapsule_GetDestructor(PyObject*capsule)¶

Part of theStable ABI.

Return the current destructor stored in the capsule. On failure, set anexception and returnNULL.

It is legal for a capsule to have aNULL destructor. This makes aNULLreturn code somewhat ambiguous; usePyCapsule_IsValid() orPyErr_Occurred() to disambiguate.

void*PyCapsule_GetContext(PyObject*capsule)¶

Part of theStable ABI.

Return the current context stored in the capsule. On failure, set anexception and returnNULL.

It is legal for a capsule to have aNULL context. This makes aNULLreturn code somewhat ambiguous; usePyCapsule_IsValid() orPyErr_Occurred() to disambiguate.

constchar*PyCapsule_GetName(PyObject*capsule)¶

Part of theStable ABI.

Return the current name stored in the capsule. On failure, set an exceptionand returnNULL.

It is legal for a capsule to have aNULL name. This makes aNULL returncode somewhat ambiguous; usePyCapsule_IsValid() orPyErr_Occurred() to disambiguate.

void*PyCapsule_Import(constchar*name,intno_block)¶

Part of theStable ABI.

Import a pointer to a C object from a capsule attribute in a module. Thename parameter should specify the full name to the attribute, as inmodule.attribute. Thename stored in the capsule must match thisstring exactly.

Return the capsule’s internalpointer on success. On failure, set anexception and returnNULL.

Changed in version 3.3:no_block has no effect anymore.

intPyCapsule_IsValid(PyObject*capsule,constchar*name)¶

Part of theStable ABI.

Determines whether or notcapsule is a valid capsule. A valid capsule isnon-NULL, passesPyCapsule_CheckExact(), has a non-NULL pointerstored in it, and its internal name matches thename parameter. (SeePyCapsule_GetPointer() for information on how capsule names arecompared.)

In other words, ifPyCapsule_IsValid() returns a true value, calls toany of the accessors (any function starting withPyCapsule_Get) areguaranteed to succeed.

Return a nonzero value if the object is valid and matches the name passed in.Return0 otherwise. This function will not fail.

intPyCapsule_SetContext(PyObject*capsule,void*context)¶

Part of theStable ABI.

Set the context pointer insidecapsule tocontext.

Return0 on success. Return nonzero and set an exception on failure.

intPyCapsule_SetDestructor(PyObject*capsule,PyCapsule_Destructordestructor)¶

Part of theStable ABI.

Set the destructor insidecapsule todestructor.

Return0 on success. Return nonzero and set an exception on failure.

intPyCapsule_SetName(PyObject*capsule,constchar*name)¶

Part of theStable ABI.

Set the name insidecapsule toname. If non-NULL, the name mustoutlive the capsule. If the previousname stored in the capsule was notNULL, no attempt is made to free it.

Return0 on success. Return nonzero and set an exception on failure.

intPyCapsule_SetPointer(PyObject*capsule,void*pointer)¶

Part of theStable ABI.

Set the void pointer insidecapsule topointer. The pointer may not beNULL.

Return0 on success. Return nonzero and set an exception on failure.