Capsule 对象¶
有关使用这些对象的更多信息请参阅 给扩展模块提供C API。
3.1 新版功能.
-
PyCapsule
¶ 这个
PyObject
的子类型代表一个隐藏的值,适用于需要将隐藏值(作为void*
指针)通过 Python 代码传递到其他 C 代码的 C 扩展模块。 它常常被用来让在一个模块中定义的 C 函数指针在其他模块中可用,这样就可以使用常规导入机制来访问在动态加载的模块中定义的 C API。
-
PyCapsule_Destructor
¶ Capsule 的析构器回调的类型。 定义如下:
typedef void (*PyCapsule_Destructor)(PyObject *);
参阅
PyCapsule_New()
来获取 PyCapsule_Destructor 返回值的语义。
-
PyObject*
PyCapsule_New
(void *pointer, const char *name, PyCapsule_Destructor destructor)¶ - Return value: New reference.
创建一个封装了 pointer 的
PyCapsule
。 pointer 参考可以不为NULL
。在失败时设置一个异常并返回
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.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 usingPyCapsule_Import()
.
-
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 beNULL
. Python uses the C functionstrcmp()
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 aNULL
return code somewhat ambiguous; usePyCapsule_IsValid()
orPyErr_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 aNULL
return code somewhat ambiguous; usePyCapsule_IsValid()
orPyErr_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 aNULL
return code somewhat ambiguous; usePyCapsule_IsValid()
orPyErr_Occurred()
to disambiguate.
-
void*
PyCapsule_Import
(const char *name, int no_block)¶ 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
. The name stored in the capsule must match this string exactly. If no_block is true, import the module without blocking (usingPyImport_ImportModuleNoBlock()
). If no_block is false, import the module conventionally (usingPyImport_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
, passesPyCapsule_CheckExact()
, has a non-NULL
pointer stored in it, and its internal name matches the name parameter. (SeePyCapsule_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 withPyCapsule_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.
-
int
PyCapsule_SetContext
(PyObject *capsule, void *context)¶ Set the context pointer inside capsule to context.
Return
0
on success. Return nonzero and set an exception on failure.
-
int
PyCapsule_SetDestructor
(PyObject *capsule, PyCapsule_Destructor destructor)¶ Set the destructor inside capsule to destructor.
Return
0
on success. Return nonzero and set an exception on failure.
-
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 notNULL
, no attempt is made to free it.Return
0
on success. Return nonzero and set an exception on failure.