Capsules¶

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

PyCapsule¶

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.

PyCapsule_Destructor¶

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.

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

Return value: New reference.

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, const char *name)¶

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)¶

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)¶

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.

const char*PyCapsule_GetName(PyObject *capsule)¶

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(const char *name, int no_block)¶

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. Ifno_block is true, import the module without blocking(usingPyImport_ImportModuleNoBlock()). Ifno_block is false,import the module conventionally (usingPyImport_ImportModule()).

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

intPyCapsule_IsValid(PyObject *capsule, const char *name)¶

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)¶

Set the context pointer insidecapsule tocontext.

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

intPyCapsule_SetDestructor(PyObject *capsule,PyCapsule_Destructor destructor)¶

Set the destructor insidecapsule todestructor.

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

intPyCapsule_SetName(PyObject *capsule, const char *name)¶

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)¶

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

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