Capsules

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

Added in version 3.1.

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
Μέρος τουΣταθερό 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)
Επιστρεφόμενη τιμή: New reference. Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό 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.

Άλλαξε στην έκδοση 3.3:no_block has no effect anymore.

intPyCapsule_IsValid(PyObject*capsule,constchar*name)
Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό ABI.

Set the context pointer insidecapsule tocontext.

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

intPyCapsule_SetDestructor(PyObject*capsule,PyCapsule_Destructordestructor)
Μέρος τουΣταθερό ABI.

Set the destructor insidecapsule todestructor.

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

intPyCapsule_SetName(PyObject*capsule,constchar*name)
Μέρος τουΣταθερό 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)
Μέρος τουΣταθερό ABI.

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

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