2
# available since Python 2.7!
5
cdef extern from "Python.h":
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.
16
ctypedef void (*PyCapsule_Destructor)(object o) noexcept
17
# The type of a destructor callback for a capsule.
19
# See PyCapsule_New() for the semantics of PyCapsule_Destructor
23
bint PyCapsule_CheckExact(object o)
24
# Return true if its argument is a PyCapsule.
27
object PyCapsule_New(void *pointer, const char *name,
28
PyCapsule_Destructor destructor)
29
# Return value: New reference.
31
# Create a PyCapsule encapsulating the pointer. The pointer
32
# argument may not be NULL.
34
# On failure, set an exception and return NULL.
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
41
# If the destructor argument is not NULL, it will be called with
42
# the capsule as its argument when it is destroyed.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.)
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.
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.
102
int PyCapsule_SetPointer(object capsule, void *pointer) except -1
103
# Set the void pointer inside capsule to pointer. The pointer may
106
# Return 0 on success. Return nonzero and set an exception on
110
int PyCapsule_SetDestructor(object capsule, PyCapsule_Destructor destructor) except -1
111
# Set the destructor inside capsule to destructor.
113
# Return 0 on success. Return nonzero and set an exception on
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.
122
# Return 0 on success. Return nonzero and set an exception on
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.
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()).
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