Capsules

有关使用这些对象的更多信息，请参考为扩展模块提供 C API。

3.1 版中的新Function。

PyCapsule
- PyObject的子类型表示不透明值，对于需要pass Python 代码将不透明值(作为void*指针)pass Python 代码传递给其他 C 代码的 C 扩展模块很有用。它通常用于使一个模块中定义的 C 函数指针可用于其他模块，因此常规导入机制可用于访问动态加载的模块中定义的 C API。
PyCapsule_Destructor
- 胶囊的析构函数回调的类型。定义为：

typedef void (*PyCapsule_Destructor)(PyObject *);

有关 PyCapsule_Destructor 回调的语义，请参见PyCapsule_New()。

int PyCapsule_CheckExact(PyObject ** p *)
- 如果其参数为PyCapsule，则返回 true。
PyObject * PyCapsule_New(void *pointer ，const char name *，PyCapsule_Destructor * destructor *)
- 返回值：新参考.

创建一个PyCapsule封装* pointer *。 * pointer *参数可能不是NULL。

失败时，设置一个异常并返回NULL。

name 字符串可以是NULL或指向有效 C 字符串的指针。如果不是NULL，则此字符串必须比胶囊有效。 (尽管可以在 destructor *内部释放它.)

如果* destructor *参数不是NULL，则销毁它时将以胶囊作为参数调用它。

如果此胶囊将作为模块的属性存储，则* name *应指定为modulename.attributename。这将使其他模块可以使用PyCapsule_Import()导入胶囊。

void * PyCapsule_GetPointer(PyObject *capsule ，const char name *)
- 检索存储在胶囊中的“指针”。失败时，设置一个异常并返回NULL。

name 参数必须与存储在胶囊中的名称精确比较。如果储存在胶囊中的名称是NULL，那么传入的 name *也必须是NULL。 Python 使用 C 函数strcmp()比较胶囊名称。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *胶囊)
- 返回存储在胶囊中的当前析构函数。失败时，设置一个异常并返回NULL。

胶囊具有NULL析构函数是合法的。这使得NULL返回代码有些含糊；使用PyCapsule_IsValid()或PyErr_Occurred()消除歧义。

胶囊具有NULL上下文是合法的。这使得NULL返回代码有些含糊；使用PyCapsule_IsValid()或PyErr_Occurred()消除歧义。

const char * PyCapsule_GetName(PyObject ** capsule *)
- 返回存储在胶囊中的当前名称。失败时，设置一个异常并返回NULL。

胶囊具有NULL名称是合法的。这使得NULL返回代码有些含糊；使用PyCapsule_IsValid()或PyErr_Occurred()消除歧义。

void * PyCapsule_Import(const char ** name *，int * no_block *)
- 从模块的胶囊属性导入指向 C 对象的指针。 * name 参数应指定属性的全名，如module.attribute所示。储存在胶囊中的 name 必须与该字符串完全匹配。如果 no_block 为 true，则导入模块时不要阻塞(使用PyImport_ImportModuleNoBlock())。如果 no_block *为 false，则按常规导入模块(使用PyImport_ImportModule())。

成功返回胶囊的内部指针。失败时，设置一个异常并返回NULL。

int PyCapsule_IsValid(PyObject *capsule ，const char name *)
- 确定* capsule 是否为有效胶囊。有效胶囊是非NULL，传递PyCapsule_CheckExact()，其中存储了非NULL指针，并且其内部名称与 name *参数匹配。 (有关如何比较胶囊名称的信息，请参见PyCapsule_GetPointer()。)

换句话说，如果PyCapsule_IsValid()返回的是真值，则可以保证对任何访问器(以PyCapsule_Get()开头的任何函数)的调用都能成功。

如果对象有效并且返回的名称匹配，则返回非零值。否则返回0。此Function不会失败。

int PyCapsule_SetContext(PyObject *capsule ，void context *)
- 将* capsule 内的上下文指针设置为 context *。

成功返回0。返回非零并在失败时设置异常。

int PyCapsule_SetDestructor(PyObject ** capsule *，PyCapsule_Destructor * destructor *)
- 将* capsule 内的析构函数设置为 destructor *。

成功返回0。返回非零并在失败时设置异常。

int PyCapsule_SetName(PyObject *capsule ，const char name *)
- 将* capsule 内的名称设置为 name 。如果不是NULL，则名称必须比胶囊长。如果存储在胶囊中的先前 name *不是NULL，则不会try释放它。

成功返回0。返回非零并在失败时设置异常。

int PyCapsule_SetPointer(PyObject *capsule ，void pointer *)
- 将* capsule 内部的 void 指针设置为 pointer *。指针可能不是NULL。

成功返回0。返回非零并在失败时设置异常。