1
2# available since Python 3.1!
3
4
5cdef extern from "Python.h":
6
7    ctypedef struct PyCapsule_Type
8    # This subtype of PyObject represents an opaque value, useful for
9    # C extension modules who need to pass an opaque value (as a void*
10    # pointer) through Python code to other C code. It is often used
11    # to make a C function pointer defined in one module available to
12    # other modules, so the regular import mechanism can be used to
13    # access C APIs defined in dynamically loaded modules.
14
15
16    ctypedef void (*PyCapsule_Destructor)(object o)
17    # The type of a destructor callback for a capsule.
18    #
19    # See PyCapsule_New() for the semantics of PyCapsule_Destructor
20    # callbacks.
21
22
23    bint PyCapsule_CheckExact(object o)
24    # Return true if its argument is a PyCapsule.
25
26
27    object PyCapsule_New(void *pointer, const char *name,
28                         PyCapsule_Destructor destructor)
29    # Return value: New reference.
30    #
31    # Create a PyCapsule encapsulating the pointer. The pointer
32    # argument may not be NULL.
33    #
34    # On failure, set an exception and return NULL.
35    #
36    # The name string may either be NULL or a pointer to a valid C
37    # string. If non-NULL, this string must outlive the
38    # capsule. (Though it is permitted to free it inside the
39    # destructor.)
40    #
41    # If the destructor argument is not NULL, it will be called with
42    # the capsule as its argument when it is destroyed.
43    #
44    # If this capsule will be stored as an attribute of a module, the
45    # name should be specified as modulename.attributename. This will
46    # enable other modules to import the capsule using
47    # PyCapsule_Import().
48
49
50    void* PyCapsule_GetPointer(object capsule, const char *name) except? NULL
51    # Retrieve the pointer stored in the capsule. On failure, set an
52    # exception and return NULL.
53    #
54    # The name parameter must compare exactly to the name stored in
55    # the capsule. If the name stored in the capsule is NULL, the name
56    # passed in must also be NULL. Python uses the C function strcmp()
57    # to compare capsule names.
58
59
60    PyCapsule_Destructor PyCapsule_GetDestructor(object capsule) except? NULL
61    # Return the current destructor stored in the capsule. On failure,
62    # set an exception and return NULL.
63    #
64    # It is legal for a capsule to have a NULL destructor. This makes
65    # a NULL return code somewhat ambiguous; use PyCapsule_IsValid()
66    # or PyErr_Occurred() to disambiguate.
67
68
69    const char* PyCapsule_GetName(object capsule) except? NULL
70    # Return the current name stored in the capsule. On failure, set
71    # an exception and return NULL.
72    #
73    # It is legal for a capsule to have a NULL name. This makes a NULL
74    # return code somewhat ambiguous; use PyCapsule_IsValid() or
75    # PyErr_Occurred() to disambiguate.
76
77
78    void* PyCapsule_GetContext(object capsule) except? NULL
79    # Return the current context stored in the capsule. On failure,
80    # set an exception and return NULL.
81    #
82    # It is legal for a capsule to have a NULL context. This makes a
83    # NULL return code somewhat ambiguous; use PyCapsule_IsValid() or
84    # PyErr_Occurred() to disambiguate.
85
86
87    bint PyCapsule_IsValid(object capsule, const char *name)
88    # Determines whether or not capsule is a valid capsule. A valid
89    # capsule is non-NULL, passes PyCapsule_CheckExact(), has a
90    # non-NULL pointer stored in it, and its internal name matches the
91    # name parameter. (See PyCapsule_GetPointer() for information on
92    # how capsule names are compared.)
93    #
94    # In other words, if PyCapsule_IsValid() returns a true value,
95    # calls to any of the accessors (any function starting with
96    # PyCapsule_Get()) are guaranteed to succeed.
97    #
98    # Return a nonzero value if the object is valid and matches the
99    # name passed in. Return 0 otherwise. This function will not fail.
100
101
102    int PyCapsule_SetPointer(object capsule, void *pointer) except -1
103    # Set the void pointer inside capsule to pointer. The pointer may
104    # not be NULL.
105    #
106    # Return 0 on success. Return nonzero and set an exception on
107    # failure.
108
109
110    int PyCapsule_SetDestructor(object capsule, PyCapsule_Destructor destructor) except -1
111    # Set the destructor inside capsule to destructor.
112    #
113    # Return 0 on success. Return nonzero and set an exception on
114    # failure.
115
116
117    int PyCapsule_SetName(object capsule, const char *name) except -1
118    # Set the name inside capsule to name. If non-NULL, the name must
119    # outlive the capsule. If the previous name stored in the capsule
120    # was not NULL, no attempt is made to free it.
121    #
122    # Return 0 on success. Return nonzero and set an exception on
123    # failure.
124
125
126    int PyCapsule_SetContext(object capsule, void *context) except -1
127    # Set the context pointer inside capsule to context.  Return 0 on
128    # success. Return nonzero and set an exception on failure.
129
130
131    void* PyCapsule_Import(const char *name, int no_block) except? NULL
132    # Import a pointer to a C object from a capsule attribute in a
133    # module. The name parameter should specify the full name to the
134    # attribute, as in module.attribute. The name stored in the
135    # capsule must match this string exactly. If no_block is true,
136    # import the module without blocking (using
137    # PyImport_ImportModuleNoBlock()). If no_block is false, import
138    # the module conventionally (using PyImport_ImportModule()).
139    #
140    # Return the capsule’s internal pointer on success. On failure,
141    # set an exception and return NULL. However, if PyCapsule_Import()
142    # failed to import the module, and no_block was true, no exception
143    # is set.
144
145