胶囊

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

3.1 新版功能.

PyCapsule

这个 PyObject 的子类型代表着一个任意值，当需要通过 Python 代码将任意值（以 void* 指针的形式）从 C 扩展模块传递给其他 C 代码时非常有用。它通常用于将指向一个模块中定义的 C 语言函数指针传递给其他模块，以便可以从那里调用它们。这允许通过正常的模块导入机制访问动态加载的模块中的 C API。

PyCapsule_Destructor

这种类型的一个析构器返回一个胶囊，定义如下：

typedef void (*PyCapsule_Destructor)(PyObject *);

参阅 PyCapsule_New() 来获取 PyCapsule_Destructor 返回值的语义。

int PyCapsule_CheckExact(PyObject *p)

如果参数是一个 PyCapsule 则返回 True

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

Return value: New reference.

Create a PyCapsule encapsulating the pointer. The 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.)

If the destructor argument is not NULL, it will be called with the capsule as its argument when it is destroyed.

如果此 capsule 将被保存为一个模块的属性，则 name 应当被指定为 modulename.attributename。 这将允许其他模块使用 PyCapsule_Import() 来导入此 capsule。

void* PyCapsule_GetPointer(PyObject *capsule, const char *name)

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, the name passed in must also be NULL. Python uses the C function strcmp() to compare capsule names.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

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() to disambiguate.

void* PyCapsule_GetContext(PyObject *capsule)

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() to disambiguate.

const char* PyCapsule_GetName(PyObject *capsule)

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() to disambiguate.

void* PyCapsule_Import(const char *name, int no_block)

从一个模块的 capsule 属性导入指向 C 对象的指针。 name 形参应当指定属性的完整名称，与 module.attribute 中的一致。 保存在 capsule 中的 name 必须完全匹配此字符串。 如果 no_block 为真值，则以无阻塞模式导入模块 (使用 PyImport_ImportModuleNoBlock())。 如果 no_block 为假值，则以传统模式导入模块 (使用 PyImport_ImportModule())。

Return the capsule’s internal pointer on success. On failure, set an exception and return NULL.

int PyCapsule_IsValid(PyObject *capsule, const char *name)

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

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

如果对象有效并且匹配传入的名称则返回非零值。 否则返回 0。 此函数一定不会失败。

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)

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.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Set the void pointer inside capsule to pointer. The pointer may not be NULL.

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