C and C++ API¶

This section includes information for using the pure C or C++ API for manipulating bob.blitz objects in compiled code.

C API¶

The C API of bob.blitz allows users to leverage from automatic converters between numpy.ndarray and bob.blitz.array within their own python extensions. To use the C API, clients should first, include the header file <bob.blitz/capi.h> on their compilation units and then, make sure to call once import_bob_blitz() at their module instantiation, as explained at the Python manual.

Here is a dummy C example showing how to include the header and where to call the import function:

#include <bob.blitz/capi.h>

PyMODINIT_FUNC initclient(void) {

  PyObject* m Py_InitModule("client", ClientMethods);

  if (!m) return;

  // imports dependencies
  if (import_bob_blitz() < 0) {
    PyErr_Print();
    PyErr_SetString(PyExc_ImportError, "cannot import module");
    return 0;
  }

  return m;
}

Array Structure¶

type PyBlitzArrayObject¶

PyBlitzArrayObject¶

The basic array structure represents a bob.blitz.array instance from the C-side of the interpreter. You should avoid direct access to the structure components (it is presented just as an overview on the functionality). Instead, use the accessor methods described below.

typedef struct {
  PyObject_HEAD
  void* bzarr;
  void* data;
  int type_num;
  Py_ssize_t ndim;
  Py_ssize_t shape[BLITZ_ARRAY_MAXDIMS];
  Py_ssize_t stride[BLITZ_ARRAY_MAXDIMS];
  int writeable;
  PyObject* base;

} PyBlitzArrayObject;

BLITZ_ARRAY_MAXDIMS¶: The maximum number of dimensions supported by the current bob.blitz.array implementation.

void* bzarr¶: This is a pointer that points to the allocated blitz::Array structure. This pointer is cast to the proper type and number of dimensions when operations on the data are requested.

void* data¶: A pointer to the data entry in the blitz::Array<>. This is equivalent to the operation blitz::Array<>::data().

int type_num¶

The numpy type number that is compatible with the elements of this array. It is a C representation of the C++ template parameter T. Only some types are current supported, namely:

C/C++ type	Numpy Enum	Notes
`bool`	`NPY_BOOL`
`uint8_t`	`NPY_UINT8`
`uint16_t`	`NPY_UINT16`
`uint32_t`	`NPY_UINT32`
`uint64_t`	`NPY_UINT64`
`int8_t`	`NPY_INT8`
`int16_t`	`NPY_INT16`
`int32_t`	`NPY_INT32`
`int64_t`	`NPY_INT64`
`float`	`NPY_FLOAT32`
`double`	`NPY_FLOAT64`
`long double`	`NPY_FLOAT128`	Plat. Dependent
`std::complex<float>`	`NPY_COMPLEX64`
`std::complex<double>`	`NPY_COMPLEX128`
`std::complex<long double>`	`NPY_COMPLEX256`	Plat. Dependent

Py_ssize_t ndim¶: The rank of the blitz::Array<> allocated on bzarr.

Py_ssize_t shape[BLITZ_ARRAY_MAXDIMS]: The shape of the blitz::Array<> allocated on bzarr, in number of elements in each dimension.

Py_ssize_t stride[BLITZ_ARRAY_MAXDIMS]: The strides of the blitz::Array<> allocated on bzarr, in number of bytes to jump to read the next element in each dimensions.

int writeable¶: Assumes the value of 1 (true), if the data is read-write. 0 is set otherwise.

PyObject* base¶: If the memory pointed by the currently allocated blitz::Array<> belongs to another Python object, the object is Py_INCREF()’ed and a pointer is kept on this structure member.

Basic Properties and Checking¶

int PyBlitzArray_Check(PyObject* o)¶: Checks if the input object o is a PyBlitzArrayObject. Returns 1 if it is, and 0 otherwise.

int PyBlitzArray_CheckNumpyBase(PyArrayObject* o)¶: Checks if the input object o is a PyArrayObject (i.e. a numpy.ndarray), if so, checks if the base of the object is set and that it corresponds to the current PyArrayObject shape and stride settings. If so, returns 1. It returns 0 otherwise.

int PyBlitzArray_TYPE(PyBlitzArrayObject* o)¶: Returns integral type number (as defined by the Numpy C-API) of elements in this blitz::Array<>. This is the formal method to query for o->type_num.

PyArray_Descr* PyBlitzArray_PyDTYPE(PyBlitzArrayObject* o)¶: Returns a new reference to a numpy C-API PyArray_Descr* equivalent to the internal type element T.

Py_ssize_t PyBlitzArray_NDIM(PyBlitzArrayObject* o)¶: Returns the number of dimensions in a given bob.blitz.array. This is the formal way to check for o->ndim.

Py_ssize_t* PyBlitzArray_SHAPE(PyBlitzArrayObject* o)¶: Returns the C-stype shape for this blitz::Array<>. This is the formal method to query for o->shape. The shape represents the number of elements in each dimension of the array.

PyObject* PyBlitzArray_PySHAPE(PyBlitzArrayObject* o)¶: Returns a new reference to a Python tuple holding a copy of the shape for the given array. The shape represents the number of elements in each dimension of the array.

Py_ssize_t* PyBlitzArray_STRIDE(PyBlitzArrayObject* o)¶: Returns the C-stype stride for this blitz::Array<>. This is the formal method to query for o->stride. The strides in this object are represented in number of bytes and not in number of elements considering its type_num. This is compatible with the numpy.ndarray strategy.

PyObject* PyBlitzArray_PySTRIDE(PyBlitzArrayObject* o)¶: Returns a new reference to a Python tuple holding a copy of the strides for the given array. The strides in this object are represented in number of bytes and not in number of elements considering its type_num. This is compatible with the numpy.ndarray strategy.

int PyBlitzArray_WRITEABLE(PyBlitzArrayObject* o)¶: Returns 1 if the object is writeable, 0 otherwise. This is the formal way to check for o->writeable.

PyObject* PyBlitzArray_PyWRITEABLE(PyBlitzArrayObject* o)¶: Returns True if the object is writeable, False otherwise.

PyObject* PyBlitzArray_BASE(PyBlitzArrayObject* o)¶: Returns a borrowed reference to the base of this object. The return value of this function may be NULL.

PyObject* PyBlitzArray_PyBASE(PyBlitzArrayObject* o)¶: Returns a new reference to the base of this object. If the internal o->base is NULL, then returns Py_None. Use this when interfacing with the Python interpreter.

Indexing¶

PyObject* PyBlitzArray_GetItem(PyBlitzArrayObject* o, Py_ssize_t* pos)¶: Returns, as a PyObject, an item from the array. This will be a copy of the internal item. If you set it, it won’t set the original array. o should be the PyBlitzArrayObject to be queried. pos should be a C-style array indicating the precise position to fetch. It is considered to have the same number of entries as the current array shape.

int PyBlitzArray_SetItem(PyBlitzArrayObject* o, Py_ssize_t* pos, PyObject* value)¶: Sets an given position on the array using any Python or numpy scalar. o should be the PyBlitzArrayObject to be set. pos should be a C-style array indicating the precise position to set and value, the Python or numpy scalar to set the value to.

Construction and Destruction¶

PyObject* PyBlitzArray_New(PyTypeObject* type, PyObject *args, PyObject* kwds)¶: Allocates memory and pre-initializes a PyBlitzArrayObject* object. This is the base allocator - seldomly used in user code.

void PyBlitzArray_Delete(PyBlitzArrayObject* o)¶: Completely deletes a PyBlitzArrayObject* and associated memory areas. This is the base deallocator - seldomly used in user code.

PyObject* PyBlitzArray_SimpleNew(int typenum, Py_ssize_t ndim, Py_ssize_t* shape)¶: Allocates a new bob.blitz with a given (supported) type and return it as a python object. typenum should be set to the numpy type number of the array type (e.g. NPY_FLOAT64). ndim should be set to the total number of dimensions the array should have. shape should be set to the array shape.

PyObject* PyBlitzArray_SimpleNewFromData(int type_num, Py_ssize_t ndim, Py_ssize_t* shape, Py_ssize_t* stride, void* data, int writeable)¶

Allocates a new bob.blitz.array with a given (supported) type and return it as a python object. typenum should be set to the numpy type number of the array type (e.g. NPY_FLOAT64). ndim should be set to the total number of dimensions the array should have. shape should be set to the array shape. stride should be set to the array stride in the numpy style (in number of bits). data should be a pointer to the begin of the data area. writeable indicates if the resulting array should be writeble (set it to 1), or read-only (set it to 0).

The memory area pointed by data is stolen from the user, which should not delete it anymore.

int PyBlitzArray_SimpleInit(PyBlitzArrayObject* arr, int typenum, Py_ssize_t ndim, Py_ssize_t* shape)¶: Initializes the given PyBlitzArrayObject* with a new blitz::Array of the given typenum, dimensionality and shape. See PyBlitzArray_SimpleNew() for details on the parameters. This function does not check if the memory is already initialized. It returns 0 on success and -1 on failure.

To/From Numpy Converters¶

PyObject* PyBlitzArray_AsNumpyArray(PyBlitzArrayObject* o, PyArrayDescr* dtype)¶

Creates a shallow copy of the given bob.blitz.array as a numpy.ndarray. The argument dtype may be given, in which case if the current data type is not the same, then forces the creation of a copy conforming to the require data type, if possible. You may set dtype to NULL in case you don’t mind the resulting data type.

Returns a new reference.

PyObject* PyBlitzArray_FromNumpyArray(PyObject* o)¶

Creates a new bob.blitz.array from a numpy.ndarray object in a shallow manner.

Returns a new reference.

PyObject* PyBlitzArray_NUMPY_WRAP(PyObject* o)¶

Creates a shallow copy of the given bob.blitz.array as a numpy.ndarray. This function is a shortcut replacement for PyBlitzArray_AsNumpyArray(). It can be used when the input object o is surely of type PyBlitzArrayObject. It creates a wrapper PyArrayObject that contains, as base, a stolen reference to the input object o.

It is designed like this so you can easily wrap freshly created objects of type PyBlitzArrayObject as PyArrayObject. It assumes the input object is of the right type and wrap-able as a numpy.ndarray. It does not check the object base variable, assuming it is set to NULL (what is the case to freshly created PyBlitzArrayObject’s). If you are not sure about the nature of o, use the slower but safer PyBlitzArray_AsNumpyArray().

Note

The value of o can be NULL, in which case this function returns immediately, allowing you to propagate exceptions.

Converter Functions for PyArg_Parse* family¶

int PyBlitzArray_Converter(PyObject* o, PyBlitzArrayObject** a)¶

This function is meant to be used with PyArg_ParseTupleAndKeywords() family of functions in the Python C-API. It converts an arbitrary input object into a PyBlitzArrayObject that can be used as input into another function.

You should use this converter when you don’t need to write-back into the input array. As any other standard Python converter, it returns a new reference to a PyBlitzArrayObject.

It works efficiently if the input array is already a PyBlitzArrayObject or if it is a PyArrayObject (i.e., a :py:class:numpy.ndarray), with a matching base which is a PyBlitzArrayObject. Otherwise, it creates a new PyBlitzArrayObject by first creating a PyArrayObject and then shallow wrapping it with a PyBlitzArrayObject.