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