capsule.rst 5.69 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
.. highlightlang:: c

.. _capsules:

Capsules
--------

.. index:: object: Capsule

Refer to :ref:`using-capsules` for more information on using these objects.


13
.. c:type:: PyCapsule
14

15 16
   This subtype of :c:type:`PyObject` represents an opaque value, useful for C
   extension modules who need to pass an opaque value (as a :c:type:`void\*`
17 18 19 20 21
   pointer) through Python code to other C code.  It is often used to make a C
   function pointer defined in one module available to other modules, so the
   regular import mechanism can be used to access C APIs defined in dynamically
   loaded modules.

22
.. c:type:: PyCapsule_Destructor
23 24 25 26 27

   The type of a destructor callback for a capsule.  Defined as::

      typedef void (*PyCapsule_Destructor)(PyObject *);

28
   See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
29 30 31
   callbacks.


32
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
33

34
   Return true if its argument is a :c:type:`PyCapsule`.
35

Benjamin Peterson's avatar
Benjamin Peterson committed
36

37
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
38

39
   Create a :c:type:`PyCapsule` encapsulating the *pointer*.  The *pointer*
40 41
   argument may not be *NULL*.

Benjamin Peterson's avatar
Benjamin Peterson committed
42
   On failure, set an exception and return *NULL*.
43

Benjamin Peterson's avatar
Benjamin Peterson committed
44 45 46
   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*.)
47

Benjamin Peterson's avatar
Benjamin Peterson committed
48
   If the *destructor* argument is not *NULL*, it will be called with the
Georg Brandl's avatar
Georg Brandl committed
49
   capsule as its argument when it is destroyed.
50

Benjamin Peterson's avatar
Benjamin Peterson committed
51 52
   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
53
   to import the capsule using :c:func:`PyCapsule_Import`.
54 55


56
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
57

Georg Brandl's avatar
Georg Brandl committed
58
   Retrieve the *pointer* stored in the capsule.  On failure, set an exception
Benjamin Peterson's avatar
Benjamin Peterson committed
59
   and return *NULL*.
60 61

   The *name* parameter must compare exactly to the name stored in the capsule.
Benjamin Peterson's avatar
Benjamin Peterson committed
62
   If the name stored in the capsule is *NULL*, the *name* passed in must also
63
   be *NULL*.  Python uses the C function :c:func:`strcmp` to compare capsule
Benjamin Peterson's avatar
Benjamin Peterson committed
64
   names.
65 66


67
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
68

Benjamin Peterson's avatar
Benjamin Peterson committed
69 70
   Return the current destructor stored in the capsule.  On failure, set an
   exception and return *NULL*.
71

Benjamin Peterson's avatar
Benjamin Peterson committed
72
   It is legal for a capsule to have a *NULL* destructor.  This makes a *NULL*
73 74
   return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
   :c:func:`PyErr_Occurred` to disambiguate.
75 76


77
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
78

Benjamin Peterson's avatar
Benjamin Peterson committed
79 80
   Return the current context stored in the capsule.  On failure, set an
   exception and return *NULL*.
81

Benjamin Peterson's avatar
Benjamin Peterson committed
82
   It is legal for a capsule to have a *NULL* context.  This makes a *NULL*
83 84
   return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
   :c:func:`PyErr_Occurred` to disambiguate.
85 86


87
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
88

Benjamin Peterson's avatar
Benjamin Peterson committed
89 90
   Return the current name stored in the capsule.  On failure, set an exception
   and return *NULL*.
91

Benjamin Peterson's avatar
Benjamin Peterson committed
92
   It is legal for a capsule to have a *NULL* name.  This makes a *NULL* return
93 94
   code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
   :c:func:`PyErr_Occurred` to disambiguate.
95 96


97
.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
98

Georg Brandl's avatar
Georg Brandl committed
99
   Import a pointer to a C object from a capsule attribute in a module.  The
Benjamin Peterson's avatar
Benjamin Peterson committed
100 101 102
   *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
103 104
   (using :c:func:`PyImport_ImportModuleNoBlock`).  If *no_block* is false,
   import the module conventionally (using :c:func:`PyImport_ImportModule`).
105

Benjamin Peterson's avatar
Benjamin Peterson committed
106
   Return the capsule's internal *pointer* on success.  On failure, set an
107
   exception and return *NULL*.  However, if :c:func:`PyCapsule_Import` failed to
Benjamin Peterson's avatar
Benjamin Peterson committed
108
   import the module, and *no_block* was true, no exception is set.
109

110
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
111

Benjamin Peterson's avatar
Benjamin Peterson committed
112
   Determines whether or not *capsule* is a valid capsule.  A valid capsule is
113
   non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
Benjamin Peterson's avatar
Benjamin Peterson committed
114
   stored in it, and its internal name matches the *name* parameter.  (See
115
   :c:func:`PyCapsule_GetPointer` for information on how capsule names are
Benjamin Peterson's avatar
Benjamin Peterson committed
116
   compared.)
117

118 119
   In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
   any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
Benjamin Peterson's avatar
Benjamin Peterson committed
120
   guaranteed to succeed.
121

Benjamin Peterson's avatar
Benjamin Peterson committed
122
   Return a nonzero value if the object is valid and matches the name passed in.
123
   Return ``0`` otherwise.  This function will not fail.
124

125
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
126 127 128

   Set the context pointer inside *capsule* to *context*.

129
   Return ``0`` on success.  Return nonzero and set an exception on failure.
130

131
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
132 133 134

   Set the destructor inside *capsule* to *destructor*.

135
   Return ``0`` on success.  Return nonzero and set an exception on failure.
136

137
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
138

Benjamin Peterson's avatar
Benjamin Peterson committed
139 140 141
   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.
142

143
   Return ``0`` on success.  Return nonzero and set an exception on failure.
144

145
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
146

Benjamin Peterson's avatar
Benjamin Peterson committed
147 148
   Set the void pointer inside *capsule* to *pointer*.  The pointer may not be
   *NULL*.
149

150
   Return ``0`` on success.  Return nonzero and set an exception on failure.