| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _capsules: |
| 4 |
|
| 5 |
Capsules |
| 6 |
-------- |
| 7 |
|
| 8 |
.. index:: pair: object; Capsule |
| 9 |
|
| 10 |
Refer to :ref:`using-capsules` for more information on using these objects. |
| 11 |
|
| 12 |
.. versionadded:: 3.1 |
| 13 |
|
| 14 |
|
| 15 |
.. c:type:: PyCapsule |
| 16 |
|
| 17 |
This subtype of :c:type:`PyObject` represents an opaque value, useful for C |
| 18 |
extension modules which need to pass an opaque value (as a :c:expr:`void*` |
| 19 |
pointer) through Python code to other C code. It is often used to make a C |
| 20 |
function pointer defined in one module available to other modules, so the |
| 21 |
regular import mechanism can be used to access C APIs defined in dynamically |
| 22 |
loaded modules. |
| 23 |
|
| 24 |
|
| 25 |
.. c:var:: PyTypeObject PyCapsule_Type |
| 26 |
|
| 27 |
The type object corresponding to capsule objects. This is the same object |
| 28 |
as :class:`types.CapsuleType` in the Python layer. |
| 29 |
|
| 30 |
|
| 31 |
.. c:type:: PyCapsule_Destructor |
| 32 |
|
| 33 |
The type of a destructor callback for a capsule. Defined as:: |
| 34 |
|
| 35 |
typedef void (*PyCapsule_Destructor)(PyObject *); |
| 36 |
|
| 37 |
See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor |
| 38 |
callbacks. |
| 39 |
|
| 40 |
|
| 41 |
.. c:function:: int PyCapsule_CheckExact(PyObject *p) |
| 42 |
|
| 43 |
Return true if its argument is a :c:type:`PyCapsule`. This function always |
| 44 |
succeeds. |
| 45 |
|
| 46 |
|
| 47 |
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor) |
| 48 |
|
| 49 |
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer* |
| 50 |
argument may not be ``NULL``. |
| 51 |
|
| 52 |
On failure, set an exception and return ``NULL``. |
| 53 |
|
| 54 |
The *name* string may either be ``NULL`` or a pointer to a valid C string. If |
| 55 |
non-``NULL``, this string must outlive the capsule. (Though it is permitted to |
| 56 |
free it inside the *destructor*.) |
| 57 |
|
| 58 |
If the *destructor* argument is not ``NULL``, it will be called with the |
| 59 |
capsule as its argument when it is destroyed. |
| 60 |
|
| 61 |
If this capsule will be stored as an attribute of a module, the *name* should |
| 62 |
be specified as ``modulename.attributename``. This will enable other modules |
| 63 |
to import the capsule using :c:func:`PyCapsule_Import`. |
| 64 |
|
| 65 |
|
| 66 |
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name) |
| 67 |
|
| 68 |
Retrieve the *pointer* stored in the capsule. On failure, set an exception |
| 69 |
and return ``NULL``. |
| 70 |
|
| 71 |
The *name* parameter must compare exactly to the name stored in the capsule. |
| 72 |
If the name stored in the capsule is ``NULL``, the *name* passed in must also |
| 73 |
be ``NULL``. Python uses the C function :c:func:`!strcmp` to compare capsule |
| 74 |
names. |
| 75 |
|
| 76 |
|
| 77 |
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule) |
| 78 |
|
| 79 |
Return the current destructor stored in the capsule. On failure, set an |
| 80 |
exception and return ``NULL``. |
| 81 |
|
| 82 |
It is legal for a capsule to have a ``NULL`` destructor. This makes a ``NULL`` |
| 83 |
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or |
| 84 |
:c:func:`PyErr_Occurred` to disambiguate. |
| 85 |
|
| 86 |
|
| 87 |
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule) |
| 88 |
|
| 89 |
Return the current context stored in the capsule. On failure, set an |
| 90 |
exception and return ``NULL``. |
| 91 |
|
| 92 |
It is legal for a capsule to have a ``NULL`` context. This makes a ``NULL`` |
| 93 |
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or |
| 94 |
:c:func:`PyErr_Occurred` to disambiguate. |
| 95 |
|
| 96 |
|
| 97 |
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule) |
| 98 |
|
| 99 |
Return the current name stored in the capsule. On failure, set an exception |
| 100 |
and return ``NULL``. |
| 101 |
|
| 102 |
It is legal for a capsule to have a ``NULL`` name. This makes a ``NULL`` return |
| 103 |
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or |
| 104 |
:c:func:`PyErr_Occurred` to disambiguate. |
| 105 |
|
| 106 |
|
| 107 |
.. c:function:: void* PyCapsule_Import(const char *name, int no_block) |
| 108 |
|
| 109 |
Import a pointer to a C object from a capsule attribute in a module. The |
| 110 |
*name* parameter should specify the full name to the attribute, as in |
| 111 |
``module.attribute``. The *name* stored in the capsule must match this |
| 112 |
string exactly. |
| 113 |
|
| 114 |
This function splits *name* on the ``.`` character, and imports the first |
| 115 |
element. It then processes further elements using attribute lookups. |
| 116 |
|
| 117 |
Return the capsule's internal *pointer* on success. On failure, set an |
| 118 |
exception and return ``NULL``. |
| 119 |
|
| 120 |
.. note:: |
| 121 |
|
| 122 |
If *name* points to an attribute of some submodule or subpackage, this |
| 123 |
submodule or subpackage must be previously imported using other means |
| 124 |
(for example, by using :c:func:`PyImport_ImportModule`) for the |
| 125 |
attribute lookups to succeed. |
| 126 |
|
| 127 |
.. versionchanged:: 3.3 |
| 128 |
*no_block* has no effect anymore. |
| 129 |
|
| 130 |
|
| 131 |
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name) |
| 132 |
|
| 133 |
Determines whether or not *capsule* is a valid capsule. A valid capsule is |
| 134 |
non-``NULL``, passes :c:func:`PyCapsule_CheckExact`, has a non-``NULL`` pointer |
| 135 |
stored in it, and its internal name matches the *name* parameter. (See |
| 136 |
:c:func:`PyCapsule_GetPointer` for information on how capsule names are |
| 137 |
compared.) |
| 138 |
|
| 139 |
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to |
| 140 |
any of the accessors (any function starting with ``PyCapsule_Get``) are |
| 141 |
guaranteed to succeed. |
| 142 |
|
| 143 |
Return a nonzero value if the object is valid and matches the name passed in. |
| 144 |
Return ``0`` otherwise. This function will not fail. |
| 145 |
|
| 146 |
|
| 147 |
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context) |
| 148 |
|
| 149 |
Set the context pointer inside *capsule* to *context*. |
| 150 |
|
| 151 |
Return ``0`` on success. Return nonzero and set an exception on failure. |
| 152 |
|
| 153 |
|
| 154 |
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor) |
| 155 |
|
| 156 |
Set the destructor inside *capsule* to *destructor*. |
| 157 |
|
| 158 |
Return ``0`` on success. Return nonzero and set an exception on failure. |
| 159 |
|
| 160 |
|
| 161 |
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name) |
| 162 |
|
| 163 |
Set the name inside *capsule* to *name*. If non-``NULL``, the name must |
| 164 |
outlive the capsule. If the previous *name* stored in the capsule was not |
| 165 |
``NULL``, no attempt is made to free it. |
| 166 |
|
| 167 |
Return ``0`` on success. Return nonzero and set an exception on failure. |
| 168 |
|
| 169 |
|
| 170 |
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer) |
| 171 |
|
| 172 |
Set the void pointer inside *capsule* to *pointer*. The pointer may not be |
| 173 |
``NULL``. |
| 174 |
|
| 175 |
Return ``0`` on success. Return nonzero and set an exception on failure. |