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¶

為穩定 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)¶

回傳值：新的參照。 為穩定 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.