Capsule 对象

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

Added in version 3.1.

type PyCapsule

这个 PyObject 的子类代表一个隐藏值，适用于需要将一个隐藏值（作为 void* 指针）通过 Python 代码传递到其他 C 代码的 C 扩展模块。它常常被用于使得在一个模块中定义的 C 函数指针在其他模块中可用，这样就可以使用常规导入机制来访问在动态加载的模块中定义的 C API。

PyTypeObject PyCapsule_Type

属于 稳定 ABI.

对应于 capsule 对象的类型对象。它与 Python 层级中的 types.CapsuleType 是同一对象。

type PyCapsule_Destructor

属于 稳定 ABI.

Capsule 的析构器回调的类型。定义如下：

typedef void (*PyCapsule_Destructor)(PyObject *);

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

int PyCapsule_CheckExact(PyObject *p)

Thread safety: Atomic.

如果参数是一个 PyCapsule 则返回真值。此函数总是会成功执行。

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

返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.

创建一个封装了 pointer 的 PyCapsule。 pointer 参数不可为 NULL。

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

字符串 name 可以是 NULL 或是一个指向有效的 C 字符串的指针。如果不为 NULL，则此字符串的存在时间必须长于 capsule。（虽然也允许在 destructor 中释放它。）

如果 destructor 参数不为 NULL，则当它被销毁时将附带 capsule 作为参数来调用。

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

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

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

提取保存在 capsule 中的 pointer。在失败时设置一个异常并返回 NULL。

name 参数必须与 capsule 中存储的名称完全一致。如果存储在 capsule 中的名称是 NULL，传入的 name 也必须是 NULL。Python 使用 C 函数 strcmp() 来比较 capsule 名称。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

返回保存在 capsule 中的当前析构器。在失败时设置一个异常并返回 NULL。

capsule 具有 NULL 析构器是合法的。这会使得 NULL 返回码有些歧义；请使用 PyCapsule_IsValid() 或 PyErr_Occurred() 来消除歧义。

void *PyCapsule_GetContext(PyObject *capsule)

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

返回保存在 capsule 中的当前上下文。在失败时设置一个异常并返回 NULL。

capsule 具有 NULL 上下文是合法的。这会使得 NULL 返回码有些歧义；请使用 PyCapsule_IsValid() 或 PyErr_Occurred() 来消除歧义。

const char *PyCapsule_GetName(PyObject *capsule)

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

返回保存在 capsule 中的当前名称。在失败时设置一个异常并返回 NULL。

capsule 具有 NULL 名称是合法的。这会使得 NULL 返回码有些歧义；请使用 PyCapsule_IsValid() 或 PyErr_Occurred() 来消除歧义。

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

属于 稳定 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

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 package.module.attribute. Modules are imported if needed, other components are looked up as attributes. The name stored in the capsule must match this string exactly.

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

在 3.3 版本发生变更: no_block 不再有任何影响。

在 3.16.0a0 (unreleased) 版本发生变更: Submodules are now imported if needed.

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

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

确定 capsule 是否是一个有效的 capsule。有效的 capsule 必须不为 NULL，传递 PyCapsule_CheckExact()，在其中存储一个不为 NULL 的指针，并且其内部名称与 name 形参相匹配。 （请参阅 PyCapsule_GetPointer() 了解如何对 capsule 名称进行比较的有关信息。）

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

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

int PyCapsule_SetContext(PyObject *capsule, void *context)

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

将 capsule 内部的上下文指针设为 context。

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

将 capsule 内部的析构器设为 destructor。

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

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

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

将 capsule 内部的名称设为 name。如果不为 NULL，则名称的存在期必须比 capsule 更长。如果之前保存在 capsule 中的 name 不为 NULL，则不会尝试释放它。

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

属于 稳定 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

将 capsule 内部的空指针设为 pointer。指针不可为 NULL。

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