User guide

NumPy User Guide, Release 1.9.0
5.1.4 Dealing with array objects
Most extension modules for NumPy will need to access the memory for an ndarray object (or one of it’s sub-classes).
The easiest way to do this doesn’t require you to know much about the internals of NumPy. The method is to
1. Ensure you are dealing with a well-behaved array (aligned, in machine byte-order and single-segment) of the
correct type and number of dimensions.
(a) By converting it from some Python object using PyArray_FromAny or a macro built on it.
(b) By constructing a new ndarray of your desired shape and type using PyArray_NewFromDescr or a
simpler macro or function based on it.
2. Get the shape of the array and a pointer to its actual data.
3. Pass the data and shape information on to a subroutine or other section of code that actually performs the
computation.
4. If you are writing the algorithm, then I recommend that you use the stride information contained in the array to
access the elements of the array (the PyArray_GETPTR macros make this painless). Then, you can relax your
requirements so as not to force a single-segment array and the data-copying that might result.
Each of these sub-topics is covered in the following sub-sections.
Converting an arbitrary sequence object
The main routine for obtaining an array from any Python object that can be converted to an array is
PyArray_FromAny. This function is very flexible with many input arguments. Several macros make it easier
to use the basic function. PyArray_FROM_OTF is arguably the most useful of these macros for the most common
uses. It allows you to convert an arbitrary Python object to an array of a specific builtin data-type ( e.g. float), while
specifying a particular set of requirements ( e.g. contiguous, aligned, and writeable). The syntax is
PyObject *PyArray_FROM_OTF(PyObject* obj, int typenum, int requirements)
Return an ndarray from any Python object, obj, that can be converted to an array. The number of dimensions
in the returned array is determined by the object. The desired data-type of the returned array is provided in
typenum which should be one of the enumerated types. The requirements for the returned array can be any
combination of standard array flags. Each of these arguments is explained in more detail below. You receive a
new reference to the array on success. On failure, NULL is returned and an exception is set.
obj
The object can be any Python object convertable to an ndarray. If the object is already (a subclass of)
the ndarray that satisfies the requirements then a new reference is returned. Otherwise, a new array
is constructed. The contents of obj are copied to the new array unless the array interface is used so
that data does not have to be copied. Objects that can be converted to an array include: 1) any nested
sequence object, 2) any object exposing the array interface, 3) any object with an __array__
method (which should return an ndarray), and 4) any scalar object (becomes a zero-dimensional
array). Sub-classes of the ndarray that otherwise fit the requirements will be passed through. If you
want to ensure a base-class ndarray, then use NPY_ENSUREARRAY in the requirements flag. A copy
is made only if necessary. If you want to guarantee a copy, then pass in NPY_ENSURECOPY to the
requirements flag.
typenum
One of the enumerated types or NPY_NOTYPE if the data-type should be determined from the object
itself. The C-based names can be used:
NPY_BOOL, NPY_BYTE, NPY_UBYTE, NPY_SHORT, NPY_USHORT, NPY_INT,
NPY_UINT, NPY_LONG, NPY_ULONG, NPY_LONGLONG, NPY_ULONGLONG,
5.1. How to extend NumPy 57