Cython/Includes/python_pycapsule.pxd

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