Array API#

Data access#

These functions and macros provide easy access to elements of the ndarray from C. These work for all arrays. You may need to take care when accessing the data in the array, however, if it is not in machine byte-order, misaligned, or not writeable. In other words, be sure to respect the state of the flags unless you know what you are doing, or have previously guaranteed an array that is writeable, aligned, and in machine byte-order using PyArray_FromAny. If you wish to handle all types of arrays, the copyswap function for each type is useful for handling misbehaved arrays. Some platforms (e.g. Solaris) do not like misaligned data and will crash if you de-reference a misaligned pointer. Other platforms (e.g. x86 Linux) will just work more slowly with misaligned data.

void *PyArray_GetPtr(PyArrayObject *aobj, npy_intp *ind)#

Return a pointer to the data of the ndarray, aobj, at the N-dimensional index given by the c-array, ind, (which must be at least aobj ->nd in size). You may want to typecast the returned pointer to the data type of the ndarray.

void *PyArray_GETPTR1(PyArrayObject *obj, npy_intp i)#

void *PyArray_GETPTR2(PyArrayObject *obj, npy_intp i, npy_intp j)#

void *PyArray_GETPTR3(PyArrayObject *obj, npy_intp i, npy_intp j, npy_intp k)#

void *PyArray_GETPTR4(PyArrayObject *obj, npy_intp i, npy_intp j, npy_intp k, npy_intp l)#

Quick, inline access to the element at the given coordinates in the ndarray, obj, which must have respectively 1, 2, 3, or 4 dimensions (this is not checked). The corresponding i, j, k, and l coordinates can be any integer but will be interpreted as npy_intp. You may want to typecast the returned pointer to the data type of the ndarray.

From scratch#

PyObject *PyArray_NewFromDescr(PyTypeObject *subtype, PyArray_Descr *descr, int nd, npy_intp const *dims, npy_intp const *strides, void *data, int flags, PyObject *obj)#

This function steals a reference to descr. The easiest way to get one is using PyArray_DescrFromType.

This is the main array creation function. Most new arrays are created with this flexible function.

The returned object is an object of Python-type subtype, which must be a subtype of PyArray_Type. The array has nd dimensions, described by dims. The data-type descriptor of the new array is descr.

If subtype is of an array subclass instead of the base &PyArray_Type, then obj is the object to pass to the __array_finalize__ method of the subclass.

If data is NULL, then new unitinialized memory will be allocated and flags can be non-zero to indicate a Fortran-style contiguous array. Use PyArray_FILLWBYTE to initialize the memory.

If data is not NULL, then it is assumed to point to the memory to be used for the array and the flags argument is used as the new flags for the array (except the state of NPY_ARRAY_OWNDATA, NPY_ARRAY_WRITEBACKIFCOPY flag of the new array will be reset).

In addition, if data is non-NULL, then strides can also be provided. If strides is NULL, then the array strides are computed as C-style contiguous (default) or Fortran-style contiguous (flags is nonzero for data = NULL or flags & NPY_ARRAY_F_CONTIGUOUS is nonzero non-NULL data). Any provided dims and strides are copied into newly allocated dimension and strides arrays for the new array object.

PyArray_CheckStrides can help verify non- NULL stride information.

If data is provided, it must stay alive for the life of the array. One way to manage this is through PyArray_SetBaseObject

PyObject *PyArray_NewLikeArray(PyArrayObject *prototype, NPY_ORDER order, PyArray_Descr *descr, int subok)#

New in version 1.6.

This function steals a reference to descr if it is not NULL. This array creation routine allows for the convenient creation of a new array matching an existing array’s shapes and memory layout, possibly changing the layout and/or data type.

When order is NPY_ANYORDER, the result order is NPY_FORTRANORDER if prototype is a fortran array, NPY_CORDER otherwise. When order is NPY_KEEPORDER, the result order matches that of prototype, even when the axes of prototype aren’t in C or Fortran order.

If descr is NULL, the data type of prototype is used.

If subok is 1, the newly created array will use the sub-type of prototype to create the new array, otherwise it will create a base-class array.

PyObject *PyArray_New(PyTypeObject *subtype, int nd, npy_intp const *dims, int type_num, npy_intp const *strides, void *data, int itemsize, int flags, PyObject *obj)#

This is similar to PyArray_NewFromDescr (…) except you specify the data-type descriptor with type_num and itemsize, where type_num corresponds to a builtin (or user-defined) type. If the type always has the same number of bytes, then itemsize is ignored. Otherwise, itemsize specifies the particular size of this array.

PyObject *PyArray_SimpleNew(int nd, npy_intp const *dims, int typenum)#

Create a new uninitialized array of type, typenum, whose size in each of nd dimensions is given by the integer array, dims.The memory for the array is uninitialized (unless typenum is NPY_OBJECT in which case each element in the array is set to NULL). The typenum argument allows specification of any of the builtin data-types such as NPY_FLOAT or NPY_LONG. The memory for the array can be set to zero if desired using PyArray_FILLWBYTE (return_object, 0).This function cannot be used to create a flexible-type array (no itemsize given).

PyObject *PyArray_SimpleNewFromData(int nd, npy_intp const *dims, int typenum, void *data)#

Create an array wrapper around data pointed to by the given pointer. The array flags will have a default that the data area is well-behaved and C-style contiguous. The shape of the array is given by the dims c-array of length nd. The data-type of the array is indicated by typenum. If data comes from another reference-counted Python object, the reference count on this object should be increased after the pointer is passed in, and the base member of the returned ndarray should point to the Python object that owns the data. This will ensure that the provided memory is not freed while the returned array is in existence.

PyObject *PyArray_SimpleNewFromDescr(int nd, npy_int const *dims, PyArray_Descr *descr)#

This function steals a reference to descr.

Create a new array with the provided data-type descriptor, descr, of the shape determined by nd and dims.

void PyArray_FILLWBYTE(PyObject *obj, int val)#

Fill the array pointed to by obj —which must be a (subclass of) ndarray—with the contents of val (evaluated as a byte). This macro calls memset, so obj must be contiguous.

PyObject *PyArray_Zeros(int nd, npy_intp const *dims, PyArray_Descr *dtype, int fortran)#

Construct a new nd -dimensional array with shape given by dims and data type given by dtype. If fortran is non-zero, then a Fortran-order array is created, otherwise a C-order array is created. Fill the memory with zeros (or the 0 object if dtype corresponds to NPY_OBJECT ).

PyObject *PyArray_ZEROS(int nd, npy_intp const *dims, int type_num, int fortran)#

Macro form of PyArray_Zeros which takes a type-number instead of a data-type object.

PyObject *PyArray_Empty(int nd, npy_intp const *dims, PyArray_Descr *dtype, int fortran)#

Construct a new nd -dimensional array with shape given by dims and data type given by dtype. If fortran is non-zero, then a Fortran-order array is created, otherwise a C-order array is created. The array is uninitialized unless the data type corresponds to NPY_OBJECT in which case the array is filled with Py_None.

PyObject *PyArray_EMPTY(int nd, npy_intp const *dims, int typenum, int fortran)#

Macro form of PyArray_Empty which takes a type-number, typenum, instead of a data-type object.

PyObject *PyArray_Arange(double start, double stop, double step, int typenum)#

Construct a new 1-dimensional array of data-type, typenum, that ranges from start to stop (exclusive) in increments of step . Equivalent to arange (start, stop, step, dtype).

PyObject *PyArray_ArangeObj(PyObject *start, PyObject *stop, PyObject *step, PyArray_Descr *descr)#

Construct a new 1-dimensional array of data-type determined by descr, that ranges from start to stop (exclusive) in increments of step. Equivalent to arange( start, stop, step, typenum ).

int PyArray_SetBaseObject(PyArrayObject *arr, PyObject *obj)#

New in version 1.7.

This function steals a reference to obj and sets it as the base property of arr.

If you construct an array by passing in your own memory buffer as a parameter, you need to set the array’s base property to ensure the lifetime of the memory buffer is appropriate.

The return value is 0 on success, -1 on failure.

If the object provided is an array, this function traverses the chain of base pointers so that each array points to the owner of the memory directly. Once the base is set, it may not be changed to another value.

From other objects#

PyObject *PyArray_FromAny(PyObject *op, PyArray_Descr *dtype, int min_depth, int max_depth, int requirements, PyObject *context)#

This is the main function used to obtain an array from any nested sequence, or object that exposes the array interface, op. The parameters allow specification of the required dtype, the minimum (min_depth) and maximum (max_depth) number of dimensions acceptable, and other requirements for the array. This function steals a reference to the dtype argument, which needs to be a PyArray_Descr structure indicating the desired data-type (including required byteorder). The dtype argument may be NULL, indicating that any data-type (and byteorder) is acceptable. Unless NPY_ARRAY_FORCECAST is present in flags, this call will generate an error if the data type cannot be safely obtained from the object. If you want to use NULL for the dtype and ensure the array is not swapped then use PyArray_CheckFromAny. A value of 0 for either of the depth parameters causes the parameter to be ignored. Any of the following array flags can be added (e.g. using |) to get the requirements argument. If your code can handle general (e.g. strided, byte-swapped, or unaligned arrays) then requirements may be 0. Also, if op is not already an array (or does not expose the array interface), then a new array will be created (and filled from op using the sequence protocol). The new array will have NPY_ARRAY_DEFAULT as its flags member. The context argument is unused.

NPY_ARRAY_C_CONTIGUOUS

Make sure the returned array is C-style contiguous

NPY_ARRAY_F_CONTIGUOUS

Make sure the returned array is Fortran-style contiguous.

NPY_ARRAY_ALIGNED

Make sure the returned array is aligned on proper boundaries for its data type. An aligned array has the data pointer and every strides factor as a multiple of the alignment factor for the data-type- descriptor.

NPY_ARRAY_WRITEABLE

Make sure the returned array can be written to.

NPY_ARRAY_ENSURECOPY

Make sure a copy is made of op. If this flag is not present, data is not copied if it can be avoided.

NPY_ARRAY_ENSUREARRAY

Make sure the result is a base-class ndarray. By default, if op is an instance of a subclass of ndarray, an instance of that same subclass is returned. If this flag is set, an ndarray object will be returned instead.

NPY_ARRAY_FORCECAST

Force a cast to the output type even if it cannot be done safely. Without this flag, a data cast will occur only if it can be done safely, otherwise an error is raised.

NPY_ARRAY_WRITEBACKIFCOPY

If op is already an array, but does not satisfy the requirements, then a copy is made (which will satisfy the requirements). If this flag is present and a copy (of an object that is already an array) must be made, then the corresponding NPY_ARRAY_WRITEBACKIFCOPY flag is set in the returned copy and op is made to be read-only. You must be sure to call PyArray_ResolveWritebackIfCopy to copy the contents back into op and the op array will be made writeable again. If op is not writeable to begin with, or if it is not already an array, then an error is raised.

Combinations of array flags can also be added.

PyObject *PyArray_CheckFromAny(PyObject *op, PyArray_Descr *dtype, int min_depth, int max_depth, int requirements, PyObject *context)#

Nearly identical to PyArray_FromAny (…) except requirements can contain NPY_ARRAY_NOTSWAPPED (over-riding the specification in dtype) and NPY_ARRAY_ELEMENTSTRIDES which indicates that the array should be aligned in the sense that the strides are multiples of the element size.

PyObject *PyArray_FromArray(PyArrayObject *op, PyArray_Descr *newtype, int requirements)#

Special case of PyArray_FromAny for when op is already an array but it needs to be of a specific newtype (including byte-order) or has certain requirements.

PyObject *PyArray_FromStructInterface(PyObject *op)#

Returns an ndarray object from a Python object that exposes the __array_struct__ attribute and follows the array interface protocol. If the object does not contain this attribute then a borrowed reference to Py_NotImplemented is returned.

PyObject *PyArray_FromInterface(PyObject *op)#

Returns an ndarray object from a Python object that exposes the __array_interface__ attribute following the array interface protocol. If the object does not contain this attribute then a borrowed reference to Py_NotImplemented is returned.

PyObject *PyArray_FromArrayAttr(PyObject *op, PyArray_Descr *dtype, PyObject *context)#

Return an ndarray object from a Python object that exposes the __array__ method. The third-party implementations of __array__ must take dtype and copy keyword arguments. context is unused.

PyObject *PyArray_ContiguousFromAny(PyObject *op, int typenum, int min_depth, int max_depth)#

This function returns a (C-style) contiguous and behaved function array from any nested sequence or array interface exporting object, op, of (non-flexible) type given by the enumerated typenum, of minimum depth min_depth, and of maximum depth max_depth. Equivalent to a call to PyArray_FromAny with requirements set to NPY_ARRAY_DEFAULT and the type_num member of the type argument set to typenum.

PyObject *PyArray_ContiguousFromObject(PyObject *op, int typenum, int min_depth, int max_depth)#

This function returns a well-behaved C-style contiguous array from any nested sequence or array-interface exporting object. The minimum number of dimensions the array can have is given by min_depth while the maximum is max_depth. This is equivalent to call PyArray_FromAny with requirements NPY_ARRAY_DEFAULT and NPY_ARRAY_ENSUREARRAY.

PyObject *PyArray_FromObject(PyObject *op, int typenum, int min_depth, int max_depth)#

Return an aligned and in native-byteorder array from any nested sequence or array-interface exporting object, op, of a type given by the enumerated typenum. The minimum number of dimensions the array can have is given by min_depth while the maximum is max_depth. This is equivalent to a call to PyArray_FromAny with requirements set to BEHAVED.

PyObject *PyArray_EnsureArray(PyObject *op)#

This function steals a reference to op and makes sure that op is a base-class ndarray. It special cases array scalars, but otherwise calls PyArray_FromAny ( op, NULL, 0, 0, NPY_ARRAY_ENSUREARRAY, NULL).

PyObject *PyArray_FromString(char *string, npy_intp slen, PyArray_Descr *dtype, npy_intp num, char *sep)#

Construct a one-dimensional ndarray of a single type from a binary or (ASCII) text string of length slen. The data-type of the array to-be-created is given by dtype. If num is -1, then copy the entire string and return an appropriately sized array, otherwise, num is the number of items to copy from the string. If sep is NULL (or “”), then interpret the string as bytes of binary data, otherwise convert the sub-strings separated by sep to items of data-type dtype. Some data-types may not be readable in text mode and an error will be raised if that occurs. All errors return NULL.

PyObject *PyArray_FromFile(FILE *fp, PyArray_Descr *dtype, npy_intp num, char *sep)#

Construct a one-dimensional ndarray of a single type from a binary or text file. The open file pointer is fp, the data-type of the array to be created is given by dtype. This must match the data in the file. If num is -1, then read until the end of the file and return an appropriately sized array, otherwise, num is the number of items to read. If sep is NULL (or “”), then read from the file in binary mode, otherwise read from the file in text mode with sep providing the item separator. Some array types cannot be read in text mode in which case an error is raised.

PyObject *PyArray_FromBuffer(PyObject *buf, PyArray_Descr *dtype, npy_intp count, npy_intp offset)#

Construct a one-dimensional ndarray of a single type from an object, buf, that exports the (single-segment) buffer protocol (or has an attribute __buffer__ that returns an object that exports the buffer protocol). A writeable buffer will be tried first followed by a read- only buffer. The NPY_ARRAY_WRITEABLE flag of the returned array will reflect which one was successful. The data is assumed to start at offset bytes from the start of the memory location for the object. The type of the data in the buffer will be interpreted depending on the data- type descriptor, dtype. If count is negative then it will be determined from the size of the buffer and the requested itemsize, otherwise, count represents how many elements should be converted from the buffer.

int PyArray_CopyInto(PyArrayObject *dest, PyArrayObject *src)#

Copy from the source array, src, into the destination array, dest, performing a data-type conversion if necessary. If an error occurs return -1 (otherwise 0). The shape of src must be broadcastable to the shape of dest. NumPy checks for overlapping memory when copying two arrays.

int PyArray_CopyObject(PyArrayObject *dest, PyObject *src)#

Assign an object src to a NumPy array dest according to array-coercion rules. This is basically identical to PyArray_FromAny, but assigns directly to the output array. Returns 0 on success and -1 on failures.

PyArrayObject *PyArray_GETCONTIGUOUS(PyObject *op)#

If op is already (C-style) contiguous and well-behaved then just return a reference, otherwise return a (contiguous and well-behaved) copy of the array. The parameter op must be a (sub-class of an) ndarray and no checking for that is done.

PyObject *PyArray_FROM_O(PyObject *obj)#

Convert obj to an ndarray. The argument can be any nested sequence or object that exports the array interface. This is a macro form of PyArray_FromAny using NULL, 0, 0, 0 for the other arguments. Your code must be able to handle any data-type descriptor and any combination of data-flags to use this macro.

PyObject *PyArray_FROM_OF(PyObject *obj, int requirements)#

Similar to PyArray_FROM_O except it can take an argument of requirements indicating properties the resulting array must have. Available requirements that can be enforced are NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_NOTSWAPPED, NPY_ARRAY_ENSURECOPY, NPY_ARRAY_WRITEBACKIFCOPY, NPY_ARRAY_FORCECAST, and NPY_ARRAY_ENSUREARRAY. Standard combinations of flags can also be used:

PyObject *PyArray_FROM_OT(PyObject *obj, int typenum)#

Similar to PyArray_FROM_O except it can take an argument of typenum specifying the type-number the returned array.

PyObject *PyArray_FROM_OTF(PyObject *obj, int typenum, int requirements)#

Combination of PyArray_FROM_OF and PyArray_FROM_OT allowing both a typenum and a flags argument to be provided.

PyObject *PyArray_FROMANY(PyObject *obj, int typenum, int min, int max, int requirements)#

Similar to PyArray_FromAny except the data-type is specified using a typenumber. PyArray_DescrFromType (typenum) is passed directly to PyArray_FromAny. This macro also adds NPY_ARRAY_DEFAULT to requirements if NPY_ARRAY_ENSURECOPY is passed in as requirements.

PyObject *PyArray_CheckAxis(PyObject *obj, int *axis, int requirements)#

Encapsulate the functionality of functions and methods that take the axis= keyword and work properly with None as the axis argument. The input array is obj, while *axis is a converted integer (so that >=MAXDIMS is the None value), and requirements gives the needed properties of obj. The output is a converted version of the input so that requirements are met and if needed a flattening has occurred. On output negative values of *axis are converted and the new value is checked to ensure consistency with the shape of obj.

General check of Python Type#

int PyArray_Check(PyObject *op)#

Evaluates true if op is a Python object whose type is a sub-type of PyArray_Type.

int PyArray_CheckExact(PyObject *op)#

Evaluates true if op is a Python object with type PyArray_Type.

int PyArray_HasArrayInterface(PyObject *op, PyObject *out)#

If op implements any part of the array interface, then out will contain a new reference to the newly created ndarray using the interface or out will contain NULL if an error during conversion occurs. Otherwise, out will contain a borrowed reference to Py_NotImplemented and no error condition is set.

int PyArray_HasArrayInterfaceType(PyObject *op, PyArray_Descr *dtype, PyObject *context, PyObject *out)#

If op implements any part of the array interface, then out will contain a new reference to the newly created ndarray using the interface or out will contain NULL if an error during conversion occurs. Otherwise, out will contain a borrowed reference to Py_NotImplemented and no error condition is set. This version allows setting of the dtype in the part of the array interface that looks for the __array__ attribute. context is unused.

int PyArray_IsZeroDim(PyObject *op)#

Evaluates true if op is an instance of (a subclass of) PyArray_Type and has 0 dimensions.

PyArray_IsScalar(op, cls)#

Evaluates true if op is an instance of Py{cls}ArrType_Type.

int PyArray_CheckScalar(PyObject *op)#

Evaluates true if op is either an array scalar (an instance of a sub-type of PyGenericArrType_Type ), or an instance of (a sub-class of) PyArray_Type whose dimensionality is 0.

int PyArray_IsPythonNumber(PyObject *op)#

Evaluates true if op is an instance of a builtin numeric type (int, float, complex, long, bool)

int PyArray_IsPythonScalar(PyObject *op)#

Evaluates true if op is a builtin Python scalar object (int, float, complex, bytes, str, long, bool).

int PyArray_IsAnyScalar(PyObject *op)#

Evaluates true if op is either a Python scalar object (see PyArray_IsPythonScalar) or an array scalar (an instance of a sub- type of PyGenericArrType_Type ).

int PyArray_CheckAnyScalar(PyObject *op)#

Evaluates true if op is a Python scalar object (see PyArray_IsPythonScalar), an array scalar (an instance of a sub-type of PyGenericArrType_Type) or an instance of a sub-type of PyArray_Type whose dimensionality is 0.

Data-type accessors#

Some of the descriptor attributes may not always be defined and should or cannot not be accessed directly.

npy_intp PyDataType_ELSIZE(PyArray_Descr *descr)#

The element size of the datatype (itemsize in Python).

Note

If the descr is attached to an array PyArray_ITEMSIZE(arr) can be used and is available on all NumPy versions.

void PyDataType_SET_ELSIZE(PyArray_Descr *descr, npy_intp size)#

Allows setting of the itemsize, this is only relevant for string/bytes datatypes as it is the current pattern to define one with a new size.

npy_intp PyDataType_ALIGNENT(PyArray_Descr *descr)#

The alignment of the datatype.

PyObject *PyDataType_METADATA(PyArray_Descr *descr)#

The Metadata attached to a dtype, either NULL or a dictionary.

PyObject *PyDataType_NAMES(PyArray_Descr *descr)#

NULL or a tuple of structured field names attached to a dtype.

PyObject *PyDataType_FIELDS(PyArray_Descr *descr)#

NULL, None, or a dict of structured dtype fields, this dict must not be mutated, NumPy may change the way fields are stored in the future.

This is the same dict as returned by np.dtype.fields.

NpyAuxData *PyDataType_C_METADATA(PyArray_Descr *descr)#

C-metadata object attached to a descriptor. This accessor should not be needed usually. The C-Metadata field does provide access to the datetime/timedelta time unit information.

PyArray_ArrayDescr *PyDataType_SUBARRAY(PyArray_Descr *descr)#

Information about a subarray dtype eqivalent to the Python np.dtype.base and np.dtype.shape.

If this is non- NULL, then this data-type descriptor is a C-style contiguous array of another data-type descriptor. In other-words, each element that this descriptor describes is actually an array of some other base descriptor. This is most useful as the data-type descriptor for a field in another data-type descriptor. The fields member should be NULL if this is non- NULL (the fields member of the base descriptor can be non- NULL however).

type PyArray_ArrayDescr#

typedef struct {
    PyArray_Descr *base;
    PyObject *shape;
} PyArray_ArrayDescr;

PyArray_Descr *base#

The data-type-descriptor object of the base-type.

PyObject *shape#

The shape (always C-style contiguous) of the sub-array as a Python tuple.

Data-type checking#

For the typenum macros, the argument is an integer representing an enumerated array data type. For the array type checking macros the argument must be a PyObject* that can be directly interpreted as a PyArrayObject*.

int PyTypeNum_ISUNSIGNED(int num)#

int PyDataType_ISUNSIGNED(PyArray_Descr *descr)#

int PyArray_ISUNSIGNED(PyArrayObject *obj)#

Type represents an unsigned integer.

int PyTypeNum_ISSIGNED(int num)#

int PyDataType_ISSIGNED(PyArray_Descr *descr)#

int PyArray_ISSIGNED(PyArrayObject *obj)#

Type represents a signed integer.

int PyTypeNum_ISINTEGER(int num)#

int PyDataType_ISINTEGER(PyArray_Descr *descr)#

int PyArray_ISINTEGER(PyArrayObject *obj)#

Type represents any integer.

int PyTypeNum_ISFLOAT(int num)#

int PyDataType_ISFLOAT(PyArray_Descr *descr)#

int PyArray_ISFLOAT(PyArrayObject *obj)#

Type represents any floating point number.

int PyTypeNum_ISCOMPLEX(int num)#

int PyDataType_ISCOMPLEX(PyArray_Descr *descr)#

int PyArray_ISCOMPLEX(PyArrayObject *obj)#

Type represents any complex floating point number.

int PyTypeNum_ISNUMBER(int num)#

int PyDataType_ISNUMBER(PyArray_Descr *descr)#

int PyArray_ISNUMBER(PyArrayObject *obj)#

Type represents any integer, floating point, or complex floating point number.

int PyTypeNum_ISSTRING(int num)#

int PyDataType_ISSTRING(PyArray_Descr *descr)#

int PyArray_ISSTRING(PyArrayObject *obj)#

Type represents a string data type.

int PyTypeNum_ISFLEXIBLE(int num)#

int PyDataType_ISFLEXIBLE(PyArray_Descr *descr)#

int PyArray_ISFLEXIBLE(PyArrayObject *obj)#

Type represents one of the flexible array types ( NPY_STRING, NPY_UNICODE, or NPY_VOID ).

int PyDataType_ISUNSIZED(PyArray_Descr *descr)#

Type has no size information attached, and can be resized. Should only be called on flexible dtypes. Types that are attached to an array will always be sized, hence the array form of this macro not existing.

Changed in version 1.18.

For structured datatypes with no fields this function now returns False.

int PyTypeNum_ISUSERDEF(int num)#

int PyDataType_ISUSERDEF(PyArray_Descr *descr)#

int PyArray_ISUSERDEF(PyArrayObject *obj)#

Type represents a user-defined type.

int PyTypeNum_ISEXTENDED(int num)#

int PyDataType_ISEXTENDED(PyArray_Descr *descr)#

int PyArray_ISEXTENDED(PyArrayObject *obj)#

Type is either flexible or user-defined.

int PyTypeNum_ISOBJECT(int num)#

int PyDataType_ISOBJECT(PyArray_Descr *descr)#

int PyArray_ISOBJECT(PyArrayObject *obj)#

Type represents object data type.

int PyTypeNum_ISBOOL(int num)#

int PyDataType_ISBOOL(PyArray_Descr *descr)#

int PyArray_ISBOOL(PyArrayObject *obj)#

Type represents Boolean data type.

int PyDataType_HASFIELDS(PyArray_Descr *descr)#

int PyArray_HASFIELDS(PyArrayObject *obj)#

Type has fields associated with it.

int PyArray_ISNOTSWAPPED(PyArrayObject *m)#

Evaluates true if the data area of the ndarray m is in machine byte-order according to the array’s data-type descriptor.

int PyArray_ISBYTESWAPPED(PyArrayObject *m)#

Evaluates true if the data area of the ndarray m is not in machine byte-order according to the array’s data-type descriptor.

npy_bool PyArray_EquivTypes(PyArray_Descr *type1, PyArray_Descr *type2)#

Return NPY_TRUE if type1 and type2 actually represent equivalent types for this platform (the fortran member of each type is ignored). For example, on 32-bit platforms, NPY_LONG and NPY_INT are equivalent. Otherwise return NPY_FALSE.

npy_bool PyArray_EquivArrTypes(PyArrayObject *a1, PyArrayObject *a2)#

Return NPY_TRUE if a1 and a2 are arrays with equivalent types for this platform.

npy_bool PyArray_EquivTypenums(int typenum1, int typenum2)#

Special case of PyArray_EquivTypes (…) that does not accept flexible data types but may be easier to call.

int PyArray_EquivByteorders(int b1, int b2)#

True if byteorder characters b1 and b2 ( NPY_LITTLE, NPY_BIG, NPY_NATIVE, NPY_IGNORE ) are either equal or equivalent as to their specification of a native byte order. Thus, on a little-endian machine NPY_LITTLE and NPY_NATIVE are equivalent where they are not equivalent on a big-endian machine.

Converting data types#

PyObject *PyArray_Cast(PyArrayObject *arr, int typenum)#

Mainly for backwards compatibility to the Numeric C-API and for simple casts to non-flexible types. Return a new array object with the elements of arr cast to the data-type typenum which must be one of the enumerated types and not a flexible type.

PyObject *PyArray_CastToType(PyArrayObject *arr, PyArray_Descr *type, int fortran)#

Return a new array of the type specified, casting the elements of arr as appropriate. The fortran argument specifies the ordering of the output array.

int PyArray_CastTo(PyArrayObject *out, PyArrayObject *in)#

As of 1.6, this function simply calls PyArray_CopyInto, which handles the casting.

Cast the elements of the array in into the array out. The output array should be writeable, have an integer-multiple of the number of elements in the input array (more than one copy can be placed in out), and have a data type that is one of the builtin types. Returns 0 on success and -1 if an error occurs.

int PyArray_CanCastSafely(int fromtype, int totype)#

Returns non-zero if an array of data type fromtype can be cast to an array of data type totype without losing information. An exception is that 64-bit integers are allowed to be cast to 64-bit floating point values even though this can lose precision on large integers so as not to proliferate the use of long doubles without explicit requests. Flexible array types are not checked according to their lengths with this function.

int PyArray_CanCastTo(PyArray_Descr *fromtype, PyArray_Descr *totype)#

PyArray_CanCastTypeTo supersedes this function in NumPy 1.6 and later.

Equivalent to PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING).

int PyArray_CanCastTypeTo(PyArray_Descr *fromtype, PyArray_Descr *totype, NPY_CASTING casting)#

New in version 1.6.

Returns non-zero if an array of data type fromtype (which can include flexible types) can be cast safely to an array of data type totype (which can include flexible types) according to the casting rule casting. For simple types with NPY_SAFE_CASTING, this is basically a wrapper around PyArray_CanCastSafely, but for flexible types such as strings or unicode, it produces results taking into account their sizes. Integer and float types can only be cast to a string or unicode type using NPY_SAFE_CASTING if the string or unicode type is big enough to hold the max value of the integer/float type being cast from.

int PyArray_CanCastArrayTo(PyArrayObject *arr, PyArray_Descr *totype, NPY_CASTING casting)#

New in version 1.6.

Returns non-zero if arr can be cast to totype according to the casting rule given in casting. If arr is an array scalar, its value is taken into account, and non-zero is also returned when the value will not overflow or be truncated to an integer when converting to a smaller type.

This is almost the same as the result of PyArray_CanCastTypeTo(PyArray_MinScalarType(arr), totype, casting), but it also handles a special case arising because the set of uint values is not a subset of the int values for types with the same number of bits.

PyArray_Descr *PyArray_MinScalarType(PyArrayObject *arr)#

New in version 1.6.

If arr is an array, returns its data type descriptor, but if arr is an array scalar (has 0 dimensions), it finds the data type of smallest size to which the value may be converted without overflow or truncation to an integer.

This function will not demote complex to float or anything to boolean, but will demote a signed integer to an unsigned integer when the scalar value is positive.

PyArray_Descr *PyArray_PromoteTypes(PyArray_Descr *type1, PyArray_Descr *type2)#

New in version 1.6.

Finds the data type of smallest size and kind to which type1 and type2 may be safely converted. This function is symmetric and associative. A string or unicode result will be the proper size for storing the max value of the input types converted to a string or unicode.

PyArray_Descr *PyArray_ResultType(npy_intp narrs, PyArrayObject **arrs, npy_intp ndtypes, PyArray_Descr **dtypes)#

New in version 1.6.

This applies type promotion to all the input arrays and dtype objects, using the NumPy rules for combining scalars and arrays, to determine the output type for an operation with the given set of operands. This is the same result type that ufuncs produce.

See the documentation of numpy.result_type for more detail about the type promotion algorithm.

int PyArray_ObjectType(PyObject *op, int mintype)#

This function is superseded by PyArray_MinScalarType and/or PyArray_ResultType.

This function is useful for determining a common type that two or more arrays can be converted to. It only works for non-flexible array types as no itemsize information is passed. The mintype argument represents the minimum type acceptable, and op represents the object that will be converted to an array. The return value is the enumerated typenumber that represents the data-type that op should have.

PyArrayObject **PyArray_ConvertToCommonType(PyObject *op, int *n)#

The functionality this provides is largely superseded by iterator NpyIter introduced in 1.6, with flag NPY_ITER_COMMON_DTYPE or with the same dtype parameter for all operands.

Convert a sequence of Python objects contained in op to an array of ndarrays each having the same data type. The type is selected in the same way as PyArray_ResultType. The length of the sequence is returned in n, and an n -length array of PyArrayObject pointers is the return value (or NULL if an error occurs). The returned array must be freed by the caller of this routine (using PyDataMem_FREE ) and all the array objects in it DECREF ‘d or a memory-leak will occur. The example template-code below shows a typical usage:

Changed in version 1.18.0: A mix of scalars and zero-dimensional arrays now produces a type capable of holding the scalar value. Previously priority was given to the dtype of the arrays.

mps = PyArray_ConvertToCommonType(obj, &n);
if (mps==NULL) return NULL;
{code}
<before return>
for (i=0; i<n; i++) Py_DECREF(mps[i]);
PyDataMem_FREE(mps);
{return}

char *PyArray_Zero(PyArrayObject *arr)#

A pointer to newly created memory of size arr ->itemsize that holds the representation of 0 for that type. The returned pointer, ret, must be freed using PyDataMem_FREE (ret) when it is not needed anymore.

char *PyArray_One(PyArrayObject *arr)#

A pointer to newly created memory of size arr ->itemsize that holds the representation of 1 for that type. The returned pointer, ret, must be freed using PyDataMem_FREE (ret) when it is not needed anymore.

int PyArray_ValidType(int typenum)#

Returns NPY_TRUE if typenum represents a valid type-number (builtin or user-defined or character code). Otherwise, this function returns NPY_FALSE.

User-defined data types#

void PyArray_InitArrFuncs(PyArray_ArrFuncs *f)#

Initialize all function pointers and members to NULL.

int PyArray_RegisterDataType(PyArray_DescrProto *dtype)#

Note

As of NumPy 2.0 this API is considered legacy, the new DType API is more powerful and provides additional flexibility. The API may eventually be deprecated but support is continued for the time being.

Compiling for NumPy 1.x and 2.x

NumPy 2.x requires passing in a PyArray_DescrProto typed struct rather than a PyArray_Descr. This is necessary to allow changes. To allow code to run and compile on both 1.x and 2.x you need to change the type of your struct to PyArray_DescrProto and add:

/* Allow compiling on NumPy 1.x */
#if NPY_ABI_VERSION < 0x02000000
#define PyArray_DescrProto PyArray_Descr
#endif

for 1.x compatibility. Further, the struct will not be the actual descriptor anymore, only it’s type number will be updated. After successful registration, you must thus fetch the actual dtype with:

int type_num = PyArray_RegisterDataType(&my_descr_proto);
if (type_num < 0) {
    /* error */
}
PyArray_Descr *my_descr = PyArray_DescrFromType(type_num);

With these two changes, the code should compile and work on both 1.x and 2.x or later.

Register a data-type as a new user-defined data type for arrays. The type must have most of its entries filled in. This is not always checked and errors can produce segfaults. In particular, the typeobj member of the dtype structure must be filled with a Python type that has a fixed-size element-size that corresponds to the elsize member of dtype. Also the f member must have the required functions: nonzero, copyswap, copyswapn, getitem, setitem, and cast (some of the cast functions may be NULL if no support is desired). To avoid confusion, you should choose a unique character typecode but this is not enforced and not relied on internally.

A user-defined type number is returned that uniquely identifies the type. A pointer to the new structure can then be obtained from PyArray_DescrFromType using the returned type number. A -1 is returned if an error occurs. If this dtype has already been registered (checked only by the address of the pointer), then return the previously-assigned type-number.

int PyArray_RegisterCastFunc(PyArray_Descr *descr, int totype, PyArray_VectorUnaryFunc *castfunc)#

Register a low-level casting function, castfunc, to convert from the data-type, descr, to the given data-type number, totype. Any old casting function is over-written. A 0 is returned on success or a -1 on failure.

type PyArray_VectorUnaryFunc#

The function pointer type for low-level casting functions.

int PyArray_RegisterCanCast(PyArray_Descr *descr, int totype, NPY_SCALARKIND scalar)#

Register the data-type number, totype, as castable from data-type object, descr, of the given scalar kind. Use scalar = NPY_NOSCALAR to register that an array of data-type descr can be cast safely to a data-type whose type_number is totype. The return value is 0 on success or -1 on failure.

Special functions for NPY_OBJECT#

int PyArray_INCREF(PyArrayObject *op)#

Used for an array, op, that contains any Python objects. It increments the reference count of every object in the array according to the data-type of op. A -1 is returned if an error occurs, otherwise 0 is returned.

void PyArray_Item_INCREF(char *ptr, PyArray_Descr *dtype)#

A function to INCREF all the objects at the location ptr according to the data-type dtype. If ptr is the start of a structured type with an object at any offset, then this will (recursively) increment the reference count of all object-like items in the structured type.

int PyArray_XDECREF(PyArrayObject *op)#

Used for an array, op, that contains any Python objects. It decrements the reference count of every object in the array according to the data-type of op. Normal return value is 0. A -1 is returned if an error occurs.

void PyArray_Item_XDECREF(char *ptr, PyArray_Descr *dtype)#

A function to XDECREF all the object-like items at the location ptr as recorded in the data-type, dtype. This works recursively so that if dtype itself has fields with data-types that contain object-like items, all the object-like fields will be XDECREF 'd.

int PyArray_SetWritebackIfCopyBase(PyArrayObject *arr, PyArrayObject *base)#

Precondition: arr is a copy of base (though possibly with different strides, ordering, etc.) Sets the NPY_ARRAY_WRITEBACKIFCOPY flag and arr->base, and set base to READONLY. Call PyArray_ResolveWritebackIfCopy before calling Py_DECREF in order to copy any changes back to base and reset the READONLY flag.

Returns 0 for success, -1 for failure.

Basic Array Flags#

An ndarray can have a data segment that is not a simple contiguous chunk of well-behaved memory you can manipulate. It may not be aligned with word boundaries (very important on some platforms). It might have its data in a different byte-order than the machine recognizes. It might not be writeable. It might be in Fortran-contiguous order. The array flags are used to indicate what can be said about data associated with an array.

NPY_ARRAY_C_CONTIGUOUS#

The data area is in C-style contiguous order (last index varies the fastest).

NPY_ARRAY_F_CONTIGUOUS#

The data area is in Fortran-style contiguous order (first index varies the fastest).

NPY_ARRAY_OWNDATA#

The data area is owned by this array. Should never be set manually, instead create a PyObject wrapping the data and set the array’s base to that object. For an example, see the test in test_mem_policy.

NPY_ARRAY_ALIGNED#

The data area and all array elements are aligned appropriately.

NPY_ARRAY_WRITEABLE#

The data area can be written to.

Notice that the above 3 flags are defined so that a new, well- behaved array has these flags defined as true.

NPY_ARRAY_WRITEBACKIFCOPY#

The data area represents a (well-behaved) copy whose information should be transferred back to the original when PyArray_ResolveWritebackIfCopy is called.

This is a special flag that is set if this array represents a copy made because a user required certain flags in PyArray_FromAny and a copy had to be made of some other array (and the user asked for this flag to be set in such a situation). The base attribute then points to the “misbehaved” array (which is set read_only). PyArray_ResolveWritebackIfCopy will copy its contents back to the “misbehaved” array (casting if necessary) and will reset the “misbehaved” array to NPY_ARRAY_WRITEABLE. If the “misbehaved” array was not NPY_ARRAY_WRITEABLE to begin with then PyArray_FromAny would have returned an error because NPY_ARRAY_WRITEBACKIFCOPY would not have been possible.

PyArray_UpdateFlags (obj, flags) will update the obj->flags for flags which can be any of NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, or NPY_ARRAY_WRITEABLE.

Combinations of array flags#

NPY_ARRAY_BEHAVED#

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY#

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO#

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY#

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO#

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT#

NPY_ARRAY_CARRAY

NPY_ARRAY_IN_ARRAY#

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_IN_FARRAY#

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_ARRAY#

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_FARRAY#

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY#

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY

NPY_ARRAY_INOUT_FARRAY#

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY

NPY_ARRAY_UPDATE_ALL#

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

Flag-like constants#

These constants are used in PyArray_FromAny (and its macro forms) to specify desired properties of the new array.

NPY_ARRAY_FORCECAST#

Cast to the desired type, even if it can’t be done without losing information.

NPY_ARRAY_ENSURECOPY#

Make sure the resulting array is a copy of the original.

NPY_ARRAY_ENSUREARRAY#

Make sure the resulting object is an actual ndarray, and not a sub-class.

These constants are used in PyArray_CheckFromAny (and its macro forms) to specify desired properties of the new array.

NPY_ARRAY_NOTSWAPPED#

Make sure the returned array has a data-type descriptor that is in machine byte-order, over-riding any specification in the dtype argument. Normally, the byte-order requirement is determined by the dtype argument. If this flag is set and the dtype argument does not indicate a machine byte-order descriptor (or is NULL and the object is already an array with a data-type descriptor that is not in machine byte- order), then a new data-type descriptor is created and used with its byte-order field set to native.

NPY_ARRAY_BEHAVED_NS#

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

NPY_ARRAY_ELEMENTSTRIDES#

Make sure the returned array has strides that are multiples of the element size.

Flag checking#

For all of these macros arr must be an instance of a (subclass of) PyArray_Type.

int PyArray_CHKFLAGS(PyObject *arr, int flags)#

The first parameter, arr, must be an ndarray or subclass. The parameter, flags, should be an integer consisting of bitwise combinations of the possible flags an array can have: NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_OWNDATA, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_WRITEBACKIFCOPY.

int PyArray_IS_C_CONTIGUOUS(PyObject *arr)#

Evaluates true if arr is C-style contiguous.

int PyArray_IS_F_CONTIGUOUS(PyObject *arr)#

Evaluates true if arr is Fortran-style contiguous.

int PyArray_ISFORTRAN(PyObject *arr)#

Evaluates true if arr is Fortran-style contiguous and not C-style contiguous. PyArray_IS_F_CONTIGUOUS is the correct way to test for Fortran-style contiguity.

int PyArray_ISWRITEABLE(PyObject *arr)#

Evaluates true if the data area of arr can be written to

int PyArray_ISALIGNED(PyObject *arr)#

Evaluates true if the data area of arr is properly aligned on the machine.

int PyArray_ISBEHAVED(PyObject *arr)#

Evaluates true if the data area of arr is aligned and writeable and in machine byte-order according to its descriptor.

int PyArray_ISBEHAVED_RO(PyObject *arr)#

Evaluates true if the data area of arr is aligned and in machine byte-order.

int PyArray_ISCARRAY(PyObject *arr)#

Evaluates true if the data area of arr is C-style contiguous, and PyArray_ISBEHAVED (arr) is true.

int PyArray_ISFARRAY(PyObject *arr)#

Evaluates true if the data area of arr is Fortran-style contiguous and PyArray_ISBEHAVED (arr) is true.

int PyArray_ISCARRAY_RO(PyObject *arr)#

Evaluates true if the data area of arr is C-style contiguous, aligned, and in machine byte-order.

int PyArray_ISFARRAY_RO(PyObject *arr)#

Evaluates true if the data area of arr is Fortran-style contiguous, aligned, and in machine byte-order .

int PyArray_ISONESEGMENT(PyObject *arr)#

Evaluates true if the data area of arr consists of a single (C-style or Fortran-style) contiguous segment.

void PyArray_UpdateFlags(PyArrayObject *arr, int flagmask)#

The NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_ALIGNED, and NPY_ARRAY_F_CONTIGUOUS array flags can be “calculated” from the array object itself. This routine updates one or more of these flags of arr as specified in flagmask by performing the required calculation.

int PyArray_FailUnlessWriteable(PyArrayObject *obj, const char *name)#

This function does nothing and returns 0 if obj is writeable. It raises an exception and returns -1 if obj is not writeable. It may also do other house-keeping, such as issuing warnings on arrays which are transitioning to become views. Always call this function at some point before writing to an array.

name is a name for the array, used to give better error messages. It can be something like “assignment destination”, “output array”, or even just “array”.

Slots and Typedefs#

These are used to identify which kind of function an ArrayMethod slot implements. See Slots and Typedefs below for documentation on the functions that must be implemented for each slot.

NPY_METH_resolve_descriptors#

typedef NPY_CASTING (PyArrayMethod_ResolveDescriptors)(struct PyArrayMethodObject_tag *method, PyArray_DTypeMeta *const *dtypes, PyArray_Descr *const *given_descrs, PyArray_Descr **loop_descrs, npy_intp *view_offset)#

The function used to set the descriptors for an operation based on the descriptors of the operands. For example, a ufunc operation with two input operands and one output operand that is called without out being set in the python API, resolve_descriptors will be passed the descriptors for the two operands and determine the correct descriptor to use for the output based on the output DType set for the ArrayMethod. If out is set, then the output descriptor would be passed in as well and should not be overridden.

The method is a pointer to the underlying cast or ufunc loop. In the future we may expose this struct publicly but for now this is an opaque pointer and the method cannot be inspected. The dtypes is an nargs length array of PyArray_DTypeMeta pointers, given_descrs is an nargs length array of input descriptor instances (output descriptors may be NULL if no output was provided by the user), and loop_descrs is an nargs length array of descriptors that must be filled in by the resolve descriptors implementation. view_offset is currently only interesting for casts and can normally be ignored. When a cast does not require any operation, this can be signalled by setting view_offset to 0. On error, you must return (NPY_CASTING)-1 with an error set.

NPY_METH_strided_loop#

NPY_METH_contiguous_loop#

NPY_METH_unaligned_strided_loop#

NPY_METH_unaligned_contiguous_loop#

One dimensional strided loops implementing the behavior (either a ufunc or cast). In most cases, NPY_METH_strided_loop is the generic and only version that needs to be implemented. NPY_METH_contiguous_loop can be implemented additionally as a more light-weight/faster version and it is used when all inputs and outputs are contiguous.

To deal with possibly unaligned data, NumPy needs to be able to copy unaligned to aligned data. When implementing a new DType, the “cast” or copy for it needs to implement NPY_METH_unaligned_strided_loop. Unlike the normal versions, this loop must not assume that the data can be accessed in an aligned fashion. These loops must copy each value before accessing or storing:

type_in in_value;
type_out out_value
memcpy(&value, in_data, sizeof(type_in));
out_value = in_value;
memcpy(out_data, &out_value, sizeof(type_out)

while a normal loop can just use:

*(type_out *)out_data = *(type_in)in_data;

The unaligned loops are currently only used in casts and will never be picked in ufuncs (ufuncs create a temporary copy to ensure aligned inputs). These slot IDs are ignored when NPY_METH_get_loop is defined, where instead whichever loop returned by the get_loop function is used.

NPY_METH_contiguous_indexed_loop#

A specialized inner-loop option to speed up common ufunc.at computations.

typedef int (PyArrayMethod_StridedLoop)(PyArrayMethod_Context *context, char *const *data, const npy_intp *dimensions, const npy_intp *strides, NpyAuxData *auxdata)#

An implementation of an ArrayMethod loop. All of the loop slot IDs listed above must provide a PyArrayMethod_StridedLoop implementation. The context is a struct containing context for the loop operation - in particular the input descriptors. The data are an array of pointers to the beginning of the input and output array buffers. The dimensions are the loop dimensions for the operation. The strides are an nargs length array of strides for each input. The auxdata is an optional set of auxiliary data that can be passed in to the loop - helpful to turn on and off optional behavior or reduce boilerplate by allowing similar ufuncs to share loop implementations or to allocate space that is persistent over multiple strided loop calls.

NPY_METH_get_loop#

Allows more fine-grained control over loop selection. Accepts an implementation of PyArrayMethod_GetLoop, which in turn returns a strided loop implementation. If NPY_METH_get_loop is defined, the other loop slot IDs are ignored, if specified.

typedef int (PyArrayMethod_GetLoop)(PyArrayMethod_Context *context, int aligned, int move_references, const npy_intp *strides, PyArrayMethod_StridedLoop **out_loop, NpyAuxData **out_transferdata, NPY_ARRAYMETHOD_FLAGS *flags);#

Sets the loop to use for an operation at runtime. The context is the runtime context for the operation. aligned indicates whether the data access for the loop is aligned (1) or unaligned (0). move_references indicates whether embedded references in the data should be copied. strides are the strides for the input array, out_loop is a pointer that must be filled in with a pointer to the loop implementation. out_transferdata can be optionally filled in to allow passing in extra user-defined context to an operation. flags must be filled in with ArrayMethod flags relevant for the operation. This is for example necessary to indicate if the inner loop requires the Python GIL to be held.

NPY_METH_get_reduction_initial#

typedef int (PyArrayMethod_GetReductionInitial)(PyArrayMethod_Context *context, npy_bool reduction_is_empty, char *initial)#

Query an ArrayMethod for the initial value for use in reduction. The context is the ArrayMethod context, mainly to access the input descriptors. reduction_is_empty indicates whether the reduction is empty. When it is, the value returned may differ. In this case it is a “default” value that may differ from the “identity” value normally used. For example:

• 0.0 is the default for sum([]). But -0.0 is the correct identity otherwise as it preserves the sign for sum([-0.0]).

• We use no identity for object, but return the default of 0 and 1 for the empty sum([], dtype=object) and prod([], dtype=object). This allows np.sum(np.array(["a", "b"], dtype=object)) to work.

• -inf or INT_MIN for max is an identity, but at least INT_MIN not a good default when there are no items.

initial is a pointer to the data for the initial value, which should be filled in. Returns -1, 0, or 1 indicating error, no initial value, and the initial value being successfully filled. Errors must not be given when no initial value is correct, since NumPy may call this even when it is not strictly necessary to do so.

Flags#

enum NPY_ARRAYMETHOD_FLAGS#

These flags allow switching on and off custom runtime behavior for ArrayMethod loops. For example, if a ufunc cannot possibly trigger floating point errors, then the NPY_METH_NO_FLOATINGPOINT_ERRORS flag should be set on the ufunc when it is registered.

enumerator NPY_METH_REQUIRES_PYAPI#

Indicates the method must hold the GIL. If this flag is not set, the GIL is released before the loop is called.

enumerator NPY_METH_NO_FLOATINGPOINT_ERRORS#

Indicates the method cannot generate floating errors, so checking for floating errors after the loop completes can be skipped.

enumerator NPY_METH_SUPPORTS_UNALIGNED#

Indicates the method supports unaligned access.

enumerator NPY_METH_IS_REORDERABLE#

Indicates that the result of applying the loop repeatedly (for example, in a reduction operation) does not depend on the order of application.

enumerator NPY_METH_RUNTIME_FLAGS#

The flags that can be changed at runtime.

Typedefs#

Typedefs for functions that users of the ArrayMethod API can implement are described below.

typedef int (PyArrayMethod_TraverseLoop)(void *traverse_context, const PyArray_Descr *descr, char *data, npy_intp size, npy_intp stride, NpyAuxData *auxdata)#

A traverse loop working on a single array. This is similar to the general strided-loop function. This is designed for loops that need to visit every element of a single array.

Currently this is used for array clearing, via the NPY_DT_get_clear_loop DType API hook, and zero-filling, via the NPY_DT_get_fill_zero_loop DType API hook. These are most useful for handling arrays storing embedded references to python objects or heap-allocated data.

The descr is the descriptor for the array, data is a pointer to the array buffer, size is the 1D size of the array buffer, stride is the stride, and auxdata is optional extra data for the loop.

The traverse_context is passed in because we may need to pass in Interpreter state or similar in the future, but we don’t want to pass in a full context (with pointers to dtypes, method, caller which all make no sense for a traverse function). We assume for now that this context can be just passed through in the future (for structured dtypes).

typedef int (PyArrayMethod_GetTraverseLoop)(void *traverse_context, const PyArray_Descr *descr, int aligned, npy_intp fixed_stride, PyArrayMethod_TraverseLoop **out_loop, NpyAuxData **out_auxdata, NPY_ARRAYMETHOD_FLAGS *flags)#

Simplified get_loop function specific to dtype traversal

It should set the flags needed for the traversal loop and set out_loop to the loop function, which must be a valid PyArrayMethod_TraverseLoop pointer. Currently this is used for zero-filling and clearing arrays storing embedded references.

API Functions and Typedefs#

These functions are part of the main numpy array API and were added along with the rest of the ArrayMethod API.

int PyUFunc_AddLoopFromSpec(PyObject *ufunc, PyArrayMethod_Spec *spec)#

Add loop directly to a ufunc from a given ArrayMethod spec. the main ufunc registration function. This adds a new implementation/loop to a ufunc. It replaces PyUFunc_RegisterLoopForType.

int PyUFunc_AddPromoter(PyObject *ufunc, PyObject *DType_tuple, PyObject *promoter)#

Note that currently the output dtypes are always NULL unless they are also part of the signature. This is an implementation detail and could change in the future. However, in general promoters should not have a need for output dtypes. Register a new promoter for a ufunc. The first argument is the ufunc to register the promoter with. The second argument is a Python tuple containing DTypes or None matching the number of inputs and outputs for the ufuncs. The last argument is a promoter is a function stored in a PyCapsule. It is passed the operation and requested DType signatures and can mutate it to attempt a new search for a matching loop/promoter.

typedef int (PyArrayMethod_PromoterFunction)(PyObject *ufunc, PyArray_DTypeMeta *const op_dtypes[], PyArray_DTypeMeta *const signature[], PyArray_DTypeMeta *new_op_dtypes[])#

Type of the promoter function, which must be wrapped into a PyCapsule with name "numpy._ufunc_promoter". It is passed the operation and requested DType signatures and can mutate the signatures to attempt a search for a new loop or promoter that can accomplish the operation by casting the inputs to the “promoted” DTypes.

int PyUFunc_GiveFloatingpointErrors(const char *name, int fpe_errors)#

Checks for a floating point error after performing a floating point operation in a manner that takes into account the error signaling configured via numpy.errstate. Takes the name of the operation to use in the error message and an integer flag that is one of NPY_FPE_DIVIDEBYZERO, NPY_FPE_OVERFLOW, NPY_FPE_UNDERFLOW, NPY_FPE_INVALID to indicate which error to check for.

Returns -1 on failure (an error was raised) and 0 on success.

int PyUFunc_AddWrappingLoop(PyObject *ufunc_obj, PyArray_DTypeMeta *new_dtypes[], PyArray_DTypeMeta *wrapped_dtypes[], PyArrayMethod_TranslateGivenDescriptors *translate_given_descrs, PyArrayMethod_TranslateLoopDescriptors *translate_loop_descrs)#

Allows creating of a fairly lightweight wrapper around an existing ufunc loop. The idea is mainly for units, as this is currently slightly limited in that it enforces that you cannot use a loop from another ufunc.

typedef int (PyArrayMethod_TranslateGivenDescriptors)(int nin, int nout, PyArray_DTypeMeta *wrapped_dtypes[], PyArray_Descr *given_descrs[], PyArray_Descr *new_descrs[]);#

The function to convert the given descriptors (passed in to resolve_descriptors) and translates them for the wrapped loop. The new descriptors MUST be viewable with the old ones, NULL must be supported (for output arguments) and should normally be forwarded.

The output of of this function will be used to construct views of the arguments as if they were the translated dtypes and does not use a cast. This means this mechanism is mostly useful for DTypes that “wrap” another DType implementation. For example, a unit DType could use this to wrap an existing floating point DType without needing to re-implement low-level ufunc logic. In the unit example, resolve_descriptors would handle computing the output unit from the input unit.

typedef int (PyArrayMethod_TranslateLoopDescriptors)(int nin, int nout, PyArray_DTypeMeta *new_dtypes[], PyArray_Descr *given_descrs[], PyArray_Descr *original_descrs[], PyArray_Descr *loop_descrs[]);#

The function to convert the actual loop descriptors (as returned by the original resolve_descriptors function) to the ones the output array should use. This function must return “viewable” types, it must not mutate them in any form that would break the inner-loop logic. Does not need to support NULL.

PyArray_DTypeMeta *orig_dtypes[3] = {
    &WrappedDoubleDType, &WrappedDoubleDType, &WrappedDoubleDType};
PyArray_DTypeMeta *wrapped_dtypes[3] = {
     &PyArray_Float64DType, &PyArray_Float64DType, &PyArray_Float64DType}

PyObject *mod = PyImport_ImportModule("numpy");
if (mod == NULL) {
    return -1;
}
PyObject *multiply = PyObject_GetAttrString(mod, "multiply");
Py_DECREF(mod);

if (multiply == NULL) {
    return -1;
}

int res = PyUFunc_AddWrappingLoop(
    multiply, orig_dtypes, wrapped_dtypes, &translate_given_descrs
    &translate_loop_descrs);

Py_DECREF(multiply);

static int
translate_given_descrs(int nin, int nout,
                       PyArray_DTypeMeta *NPY_UNUSED(wrapped_dtypes[]),
                       PyArray_Descr *given_descrs[],
                       PyArray_Descr *new_descrs[])
{
    for (int i = 0; i < nin + nout; i++) {
        if (given_descrs[i] == NULL) {
            new_descrs[i] = NULL;
        }
        else {
            new_descrs[i] = PyArray_DescrFromType(NPY_DOUBLE);
        }
    }
    return 0;
}

static int
translate_loop_descrs(int nin, int NPY_UNUSED(nout),
                      PyArray_DTypeMeta *NPY_UNUSED(new_dtypes[]),
                      PyArray_Descr *given_descrs[],
                      PyArray_Descr *original_descrs[],
                      PyArray_Descr *loop_descrs[])
{
    // more complicated parametric DTypes may need to
    // to do additional checking, but we know the wrapped
    // DTypes *have* to be float64 for this example.
    loop_descrs[0] = PyArray_DescrFromType(NPY_FLOAT64);
    Py_INCREF(loop_descrs[0]);
    loop_descrs[1] = PyArray_DescrFromType(NPY_FLOAT64);
    Py_INCREF(loop_descrs[1]);
    loop_descrs[2] = PyArray_DescrFromType(NPY_FLOAT64);
    Py_INCREF(loop_descrs[2]);
}