Python/docs/3.9/c-api/capsule

胶囊

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

3.1 版中的新功能。

type PyCapsule

PyObject 的这个子类型表示不透明值，对于需要通过 Python 代码将不透明值（作为 void* 指针）传递给其他 C 代码的 C 扩展模块非常有用。 它通常用于使在一个模块中定义的 C 函数指针可用于其他模块，因此常规导入机制可用于访问动态加载模块中定义的 C API。

type PyCapsule_Destructor

胶囊的析构函数回调的类型。 定义为：

typedef void (*PyCapsule_Destructor)(PyObject *);

Copy

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

int PyCapsule_CheckExact(PyObject *p)

如果其参数是 PyCapsule，则返回 true。 此功能总是成功。

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

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

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

name 字符串可以是 NULL 或指向有效 C 字符串的指针。 如果非 NULL，则此字符串必须比胶囊存活时间长。 （尽管允许在 析构函数 中释放它。）

如果 destructor 参数不是 NULL，它会在被销毁时以胶囊为参数被调用。

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

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

检索存储在胶囊中的 指针 。 失败时，设置异常并返回 NULL。

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

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

返回存储在胶囊中的当前析构函数。 失败时，设置异常并返回 NULL。

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

void *PyCapsule_GetContext(PyObject *capsule)

返回存储在胶囊中的当前上下文。 失败时，设置异常并返回 NULL。

胶囊具有 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 为真，则在不阻塞的情况下导入模块（使用 PyImport_ImportModuleNoBlock()）。 如果 no_block 为 false，则按惯例导入模块（使用 PyImport_ImportModule()）。

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

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

确定 capsule 是否是有效的 Capsule。 一个有效的胶囊是非NULL，通过PyCapsule_CheckExact()，其中存储了一个非NULL指针，其内部名称匹配名称[ X158X] 参数。 （有关如何比较胶囊名称的信息，请参阅 PyCapsule_GetPointer()。）

换句话说，如果 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)

将 capsule 内的名称设置为 name。 如果非NULL，则名称必须比胶囊长。 如果之前存储在胶囊中的 name 不是 NULL，则不会尝试释放它。

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

将 capsule 内的 void 指针设置为 pointer。 指针可能不是 NULL。

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