参考 为扩展模块提供 C API for more information on using these objects.
此子类型的 PyObject represents an opaque value, useful for C extension modules who need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.
The type of a destructor callback for a capsule. Defined as:
typedef void (*PyCapsule_Destructor)(PyObject *);
见 PyCapsule_New() for the semantics of PyCapsule_Destructor callbacks.
创建 PyCapsule encapsulating the pointer 。 pointer argument may not be NULL .
On failure, set an exception and return NULL .
The name string may either be NULL or a pointer to a valid C string. If non- NULL , this string must outlive the capsule. (Though it is permitted to free it inside the destructor )。
若 destructor argument is not NULL , it will be called with the capsule as its argument when it is destroyed.
If this capsule will be stored as an attribute of a module, the name should be specified as modulename.attributename . This will enable other modules to import the capsule using PyCapsule_Import() .
Retrieve the pointer stored in the capsule. On failure, set an exception and return NULL .
The name parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is NULL ， name passed in must also be NULL . Python uses the C function strcmp() to compare capsule names.
Return the current destructor stored in the capsule. On failure, set an exception and return NULL .
It is legal for a capsule to have a NULL destructor. This makes a NULL return code somewhat ambiguous; use PyCapsule_IsValid() or PyErr_Occurred() 以消除歧义。
Return the current context stored in the capsule. On failure, set an exception and return NULL .
It is legal for a capsule to have a NULL context. This makes a NULL return code somewhat ambiguous; use PyCapsule_IsValid() or PyErr_Occurred() 以消除歧义。
Return the current name stored in the capsule. On failure, set an exception and return NULL .
It is legal for a capsule to have a NULL name. This makes a NULL return code somewhat ambiguous; use PyCapsule_IsValid() or PyErr_Occurred() 以消除歧义。
Import a pointer to a C object from a capsule attribute in a module. The name parameter should specify the full name to the attribute, as in module.attribute 。 name stored in the capsule must match this string exactly. If no_block is true, import the module without blocking (using PyImport_ImportModuleNoBlock() )。若 no_block is false, import the module conventionally (using PyImport_ImportModule() ).
Return the capsule’s internal pointer on success. On failure, set an exception and return NULL 。不管怎样，若 PyCapsule_Import() failed to import the module, and no_block was true, no exception is set.
Determines whether or not capsule is a valid capsule. A valid capsule is non- NULL , passes PyCapsule_CheckExact() , has a non- NULL pointer stored in it, and its internal name matches the name parameter. (See PyCapsule_GetPointer() for information on how capsule names are compared.)
In other words, if PyCapsule_IsValid() returns a true value, calls to any of the accessors (any function starting with PyCapsule_Get() ) are guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in. Return 0 otherwise. This function will not fail.
Set the context pointer inside capsule to context .
Return 0 on success. Return nonzero and set an exception on failure.
Set the destructor inside capsule to destructor .
Return 0 on success. Return nonzero and set an exception on failure.
Set the name inside capsule to name . If non- NULL , the name must outlive the capsule. If the previous name stored in the capsule was not NULL , no attempt is made to free it.
Return 0 on success. Return nonzero and set an exception on failure.
