Data access#

These functions and macros provide easy access to elements of thendarray from C. These work for all arrays. You may need to take carewhen accessing the data in the array, however, if it is not in machinebyte-order, misaligned, or not writeable. In other words, be sure torespect the state of the flags unless you know what you are doing, orhave previously guaranteed an array that is writeable, aligned, and inmachine byte-order usingPyArray_FromAny. If you wish to handle alltypes of arrays, the copyswap function for each type is useful forhandling misbehaved arrays. Some platforms (e.g. Solaris) do not likemisaligned data and will crash if you de-reference a misalignedpointer. Other platforms (e.g. x86 Linux) will just work more slowlywith misaligned data.

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

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

void*PyArray_GETPTR1(PyArrayObject*obj,npy_intpi)#

void*PyArray_GETPTR2(PyArrayObject*obj,npy_intpi,npy_intpj)#

void*PyArray_GETPTR3(PyArrayObject*obj,npy_intpi,npy_intpj,npy_intpk)#

void*PyArray_GETPTR4(PyArrayObject*obj,npy_intpi,npy_intpj,npy_intpk,npy_intpl)#

Quick, inline access to the element at the given coordinates inthe ndarray,obj, which must have respectively 1, 2, 3, or 4dimensions (this is not checked). The correspondingi,j,k, andl coordinates can be any integer but will beinterpreted asnpy_intp. You may want to typecast thereturned pointer to the data type of the ndarray.

From scratch#

PyObject*PyArray_NewFromDescr(PyTypeObject*subtype,PyArray_Descr*descr,intnd,npy_intpconst*dims,npy_intpconst*strides,void*data,intflags,PyObject*obj)#

This function steals a reference todescr. The easiest way to get oneis usingPyArray_DescrFromType.

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

The returned object is an object of Python-typesubtype, whichmust be a subtype ofPyArray_Type. The array hasnddimensions, described bydims. The data-type descriptor of thenew array isdescr.

Ifsubtype is of an array subclass instead of the base&PyArray_Type, thenobj is the object to pass tothe__array_finalize__ method of the subclass.

Ifdata isNULL, then new unitinialized memory will be allocated andflags can be non-zero to indicate a Fortran-style contiguous array. UsePyArray_FILLWBYTE to initialize the memory.

Ifdata is notNULL, then it is assumed to point to the memoryto be used for the array and theflags argument is used as thenew flags for the array (except the state ofNPY_ARRAY_OWNDATA,NPY_ARRAY_WRITEBACKIFCOPY flag of the new array will be reset).

In addition, ifdata is non-NULL, thenstrides canalso be provided. Ifstrides isNULL, then the array stridesare computed as C-style contiguous (default) or Fortran-stylecontiguous (flags is nonzero fordata =NULL orflags &NPY_ARRAY_F_CONTIGUOUS is nonzero non-NULLdata). Anyprovideddims andstrides are copied into newly allocateddimension and strides arrays for the new array object.

PyArray_CheckStrides can help verify non-NULL strideinformation.

Ifdata is provided, it must stay alive for the life of the array. Oneway to manage this is throughPyArray_SetBaseObject

PyObject*PyArray_NewLikeArray(PyArrayObject*prototype,NPY_ORDERorder,PyArray_Descr*descr,intsubok)#

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

Whenorder isNPY_ANYORDER, the result order isNPY_FORTRANORDER ifprototype is a fortran array,NPY_CORDER otherwise. Whenorder isNPY_KEEPORDER, the result order matches that ofprototype, evenwhen the axes ofprototype aren’t in C or Fortran order.

Ifdescr is NULL, the data type ofprototype is used.

Ifsubok is 1, the newly created array will use the sub-type ofprototype to create the new array, otherwise it will create abase-class array.

PyObject*PyArray_New(PyTypeObject*subtype,intnd,npy_intpconst*dims,inttype_num,npy_intpconst*strides,void*data,intitemsize,intflags,PyObject*obj)#

This is similar toPyArray_NewFromDescr (…) except youspecify the data-type descriptor withtype_num anditemsize,wheretype_num corresponds to a builtin (or user-defined)type. If the type always has the same number of bytes, thenitemsize is ignored. Otherwise, itemsize specifies the particularsize of this array.

PyObject*PyArray_SimpleNew(intnd,npy_intpconst*dims,inttypenum)#

Create a new uninitialized array of type,typenum, whose size ineach ofnd dimensions is given by the integer array,dims.The memoryfor the array is uninitialized (unless typenum isNPY_OBJECTin which case each element in the array is set to NULL). Thetypenum argument allows specification of any of the builtindata-types such asNPY_FLOAT orNPY_LONG. Thememory for the array can be set to zero if desired usingPyArray_FILLWBYTE (return_object, 0).This function cannot beused to create a flexible-type array (no itemsize given).

PyObject*PyArray_SimpleNewFromData(intnd,npy_intpconst*dims,inttypenum,void*data)#

Create an array wrapper arounddata pointed to by the givenpointer. The array flags will have a default that the data area iswell-behaved and C-style contiguous. The shape of the array isgiven by thedims c-array of lengthnd. The data-type of thearray is indicated bytypenum. If data comes from anotherreference-counted Python object, the reference count on this objectshould be increased after the pointer is passed in, and the base memberof the returned ndarray should point to the Python object that ownsthe data. This will ensure that the provided memory is notfreed while the returned array is in existence.

PyObject*PyArray_SimpleNewFromDescr(intnd,npy_intconst*dims,PyArray_Descr*descr)#

This function steals a reference todescr.

Create a new array with the provided data-type descriptor,descr,of the shape determined bynd anddims.

voidPyArray_FILLWBYTE(PyObject*obj,intval)#

Fill the array pointed to byobj —which must be a (subclassof) ndarray—with the contents ofval (evaluated as a byte).This macro calls memset, so obj must be contiguous.

PyObject*PyArray_Zeros(intnd,npy_intpconst*dims,PyArray_Descr*dtype,intfortran)#

Construct a newnd -dimensional array with shape given bydimsand data type given bydtype. Iffortran is non-zero, then aFortran-order array is created, otherwise a C-order array iscreated. Fill the memory with zeros (or the 0 object ifdtypecorresponds toNPY_OBJECT ).

PyObject*PyArray_ZEROS(intnd,npy_intpconst*dims,inttype_num,intfortran)#

Macro form ofPyArray_Zeros which takes a type-number insteadof a data-type object.

PyObject*PyArray_Empty(intnd,npy_intpconst*dims,PyArray_Descr*dtype,intfortran)#

Construct a newnd -dimensional array with shape given bydimsand data type given bydtype. Iffortran is non-zero, then aFortran-order array is created, otherwise a C-order array iscreated. The array is uninitialized unless the data typecorresponds toNPY_OBJECT in which case the array isfilled withPy_None.

PyObject*PyArray_EMPTY(intnd,npy_intpconst*dims,inttypenum,intfortran)#

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

PyObject*PyArray_Arange(doublestart,doublestop,doublestep,inttypenum)#

Construct a new 1-dimensional array of data-type,typenum, thatranges fromstart tostop (exclusive) in increments ofstep. Equivalent toarange (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 bydescr, that ranges fromstart tostop (exclusive) inincrements ofstep. Equivalent to arange(start,stop,step,typenum ).

intPyArray_SetBaseObject(PyArrayObject*arr,PyObject*obj)#

This functionsteals a reference toobj and sets it as thebase property ofarr.

If you construct an array by passing in your own memory buffer asa parameter, you need to set the array’sbase property to ensurethe 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 thechain ofbase pointers so that each array points to the ownerof the memory directly. Once the base is set, it may not be changedto another value.

From other objects#

PyObject*PyArray_FromAny(PyObject*op,PyArray_Descr*dtype,intmin_depth,intmax_depth,intrequirements,PyObject*context)#

This is the main function used to obtain an array from any nestedsequence, or object that exposes the array interface,op. Theparameters allow specification of the requireddtype, theminimum (min_depth) and maximum (max_depth) number ofdimensions acceptable, and otherrequirements for the array. Thisfunctionsteals a reference to the dtype argument, which needsto be aPyArray_Descr structureindicating the desired data-type (including requiredbyteorder). Thedtype argument may beNULL, indicating that anydata-type (and byteorder) is acceptable. UnlessNPY_ARRAY_FORCECAST is present inflags,this call will generate an error if the datatype cannot be safely obtained from the object. If you want to useNULL for thedtype and ensure the array is not swapped thenusePyArray_CheckFromAny. A value of 0 for either of thedepth parameters causes the parameter to be ignored. Any of thefollowing array flags can be added (e.g. using |) to get therequirements argument. If your code can handle general (e.g.strided, byte-swapped, or unaligned arrays) thenrequirementsmay be 0. Also, ifop is not already an array (or does notexpose the array interface), then a new array will be created (andfilled fromop using the sequence protocol). The new array willhaveNPY_ARRAY_DEFAULT as its flags member. Thecontextargument 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 itsdata type. An aligned array has the data pointer and every stridesfactor 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 ofop. If this flag is notpresent, data is not copied if it can be avoided.

NPY_ARRAY_ENSUREARRAY

Make sure the result is a base-class ndarray. Bydefault, ifop is an instance of a subclass ofndarray, an instance of that same subclass is returned. Ifthis 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 donesafely. Without this flag, a data cast will occur only if itcan be done safely, otherwise an error is raised.

NPY_ARRAY_WRITEBACKIFCOPY

Ifop is already an array, but does not satisfy therequirements, then a copy is made (which will satisfy therequirements). If this flag is present and a copy (of an objectthat is already an array) must be made, then the correspondingNPY_ARRAY_WRITEBACKIFCOPY flag is set in the returnedcopy andop is made to be read-only. You must be sure to callPyArray_ResolveWritebackIfCopy to copy the contentsback intoop and theop arraywill be made writeable again. Ifop is not writeable to beginwith, 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,intmin_depth,intmax_depth,intrequirements,PyObject*context)#

Nearly identical toPyArray_FromAny (…) exceptrequirements can containNPY_ARRAY_NOTSWAPPED (over-riding thespecification indtype) andNPY_ARRAY_ELEMENTSTRIDES whichindicates that the array should be aligned in the sense that thestrides are multiples of the element size.

PyObject*PyArray_FromArray(PyArrayObject*op,PyArray_Descr*newtype,intrequirements)#

Special case ofPyArray_FromAny for whenop is already anarray but it needs to be of a specificnewtype (includingbyte-order) or has certainrequirements.

PyObject*PyArray_FromStructInterface(PyObject*op)#

Returns an ndarray object from a Python object that exposes the__array_struct__ attribute and follows the array interfaceprotocol. If the object does not contain this attribute then aborrowed reference toPy_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 interfaceprotocol. If the object does not contain this attribute then aborrowed reference toPy_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 takedtype andcopy keywordarguments.context is unused.

PyObject*PyArray_ContiguousFromAny(PyObject*op,inttypenum,intmin_depth,intmax_depth)#

This function returns a (C-style) contiguous and behaved functionarray from any nested sequence or array interface exportingobject,op, of (non-flexible) type given by the enumeratedtypenum, of minimum depthmin_depth, and of maximum depthmax_depth. Equivalent to a call toPyArray_FromAny withrequirements set toNPY_ARRAY_DEFAULT and the type_num member of thetype argument set totypenum.

PyObject*PyArray_ContiguousFromObject(PyObject*op,inttypenum,intmin_depth,intmax_depth)#

This function returns a well-behaved C-style contiguous array from any nestedsequence or array-interface exporting object. The minimum number of dimensionsthe array can have is given bymin_depth while the maximum ismax_depth.This is equivalent to callPyArray_FromAny with requirementsNPY_ARRAY_DEFAULT andNPY_ARRAY_ENSUREARRAY.

PyObject*PyArray_FromObject(PyObject*op,inttypenum,intmin_depth,intmax_depth)#

Return an aligned and in native-byteorder array from any nestedsequence or array-interface exporting object, op, of a type given bythe enumerated typenum. The minimum number of dimensions the array canhave is given by min_depth while the maximum is max_depth. This isequivalent to a call toPyArray_FromAny with requirements set toBEHAVED.

PyObject*PyArray_EnsureArray(PyObject*op)#

This functionsteals a reference toop and makes sure thatop is a base-class ndarray. It special cases array scalars,but otherwise callsPyArray_FromAny (op, NULL, 0, 0,NPY_ARRAY_ENSUREARRAY, NULL).

PyObject*PyArray_FromString(char*string,npy_intpslen,PyArray_Descr*dtype,npy_intpnum,char*sep)#

Construct a one-dimensional ndarray of a single type from a binaryor (ASCII) textstring of lengthslen. The data-type ofthe array to-be-created is given bydtype. If num is -1, thencopy the entire string and return an appropriately sizedarray, otherwise,num is the number of items tocopy fromthe string. Ifsep is NULL (or “”), then interpret the stringas bytes of binary data, otherwise convert the sub-stringsseparated bysep to items of data-typedtype. Somedata-types may not be readable in text mode and an error will beraised if that occurs. All errors return NULL.

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

Construct a one-dimensional ndarray of a single type from a binaryor text file. The open file pointer isfp, the data-type ofthe array to be created is given bydtype. This must matchthe data in the file. Ifnum is -1, then read until the end ofthe file and return an appropriately sized array, otherwise,num is the number of items to read. Ifsep is NULL (or“”), then read from the file in binary mode, otherwise read fromthe file in text mode withsep providing the itemseparator. Some array types cannot be read in text mode in whichcase an error is raised.

PyObject*PyArray_FromBuffer(PyObject*buf,PyArray_Descr*dtype,npy_intpcount,npy_intpoffset)#

Construct a one-dimensional ndarray of a single type from anobject,buf, that exports the (single-segment) buffer protocol(or has an attribute __buffer__ that returns an object thatexports the buffer protocol). A writeable buffer will be triedfirst followed by a read- only buffer. TheNPY_ARRAY_WRITEABLEflag of the returned array will reflect which one wassuccessful. The data is assumed to start atoffset bytes fromthe start of the memory location for the object. The type of thedata in the buffer will be interpreted depending on the data- typedescriptor,dtype. Ifcount is negative then it will bedetermined from the size of the buffer and the requested itemsize,otherwise,count represents how many elements should beconverted from the buffer.

intPyArray_CopyInto(PyArrayObject*dest,PyArrayObject*src)#

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

intPyArray_CopyObject(PyArrayObject*dest,PyObject*src)#

Assign an objectsrc to a NumPy arraydest according toarray-coercion rules. This is basically identical toPyArray_FromAny, but assigns directly to the output array.Returns 0 on success and -1 on failures.

PyArrayObject*PyArray_GETCONTIGUOUS(PyObject*op)#

Ifop is already (C-style) contiguous and well-behaved thenjust return a reference, otherwise return a (contiguous andwell-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)#

Convertobj to an ndarray. The argument can be any nestedsequence or object that exports the array interface. This is amacro form ofPyArray_FromAny usingNULL, 0, 0, 0 for theother arguments. Your code must be able to handle any data-typedescriptor and any combination of data-flags to use this macro.

PyObject*PyArray_FROM_OF(PyObject*obj,intrequirements)#

Similar toPyArray_FROM_O except it can take an argumentofrequirements indicating properties the resulting array musthave. Available requirements that can be enforced areNPY_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, andNPY_ARRAY_ENSUREARRAY. Standard combinations of flags can alsobe used:

PyObject*PyArray_FROM_OT(PyObject*obj,inttypenum)#

Similar toPyArray_FROM_O except it can take an argument oftypenum specifying the type-number the returned array.

PyObject*PyArray_FROM_OTF(PyObject*obj,inttypenum,intrequirements)#

Combination ofPyArray_FROM_OF andPyArray_FROM_OTallowing both atypenum and aflags argument to be provided.

PyObject*PyArray_FROMANY(PyObject*obj,inttypenum,intmin,intmax,intrequirements)#

Similar toPyArray_FromAny except the data-type isspecified using a typenumber.PyArray_DescrFromType(typenum) is passed directly toPyArray_FromAny. Thismacro also addsNPY_ARRAY_DEFAULT to requirements ifNPY_ARRAY_ENSURECOPY is passed in as requirements.

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

Encapsulate the functionality of functions and methods that takethe axis= keyword and work properly with None as the axisargument. The input array isobj, while*axis is aconverted integer (so that*axis==NPY_RAVEL_AXIS is the None value), andrequirements gives the needed properties ofobj. Theoutput is a converted version of the input so that requirementsare met and if needed a flattening has occurred. On outputnegative values of*axis are converted and the new value ischecked to ensure consistency with the shape ofobj.

General check of Python Type#

intPyArray_Check(PyObject*op)#

Evaluates true ifop is a Python object whose type is a sub-typeofPyArray_Type.

intPyArray_CheckExact(PyObject*op)#

Evaluates true ifop is a Python object with typePyArray_Type.

intPyArray_HasArrayInterface(PyObject*op,PyObject*out)#

Ifop implements any part of the array interface, thenoutwill contain a new reference to the newly created ndarray usingthe interface orout will containNULL if an error duringconversion occurs. Otherwise, out will contain a borrowedreference toPy_NotImplemented and no error condition is set.

intPyArray_HasArrayInterfaceType(PyObject*op,PyArray_Descr*dtype,PyObject*context,PyObject*out)#

Ifop implements any part of the array interface, thenoutwill contain a new reference to the newly created ndarray usingthe interface orout will containNULL if an error duringconversion occurs. Otherwise, out will contain a borrowedreference to Py_NotImplemented and no error condition is set.This version allows setting of the dtype in the part of the array interfacethat looks for the__array__ attribute.context isunused.

intPyArray_IsZeroDim(PyObject*op)#

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

PyArray_IsScalar(op,cls)#

Evaluates true ifop is an instance ofPy{cls}ArrType_Type.

intPyArray_CheckScalar(PyObject*op)#

Evaluates true ifop is either an array scalar (an instance of asub-type ofPyGenericArrType_Type ), or an instance of (asub-class of)PyArray_Type whose dimensionality is 0.

intPyArray_IsPythonNumber(PyObject*op)#

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

intPyArray_IsPythonScalar(PyObject*op)#

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

intPyArray_IsAnyScalar(PyObject*op)#

Evaluates true ifop is either a Python scalar object (seePyArray_IsPythonScalar) or an array scalar (an instance of a sub-type ofPyGenericArrType_Type ).

intPyArray_CheckAnyScalar(PyObject*op)#

Evaluates true ifop is a Python scalar object (seePyArray_IsPythonScalar), an array scalar (an instance of asub-type ofPyGenericArrType_Type) or an instance of a sub-type ofPyArray_Type whose dimensionality is 0.

Data-type accessors#

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

npy_intpPyDataType_ELSIZE(PyArray_Descr*descr)#

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

Note

If thedescr is attached to an arrayPyArray_ITEMSIZE(arr)can be used and is available on all NumPy versions.

voidPyDataType_SET_ELSIZE(PyArray_Descr*descr,npy_intpsize)#

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

npy_intpPyDataType_ALIGNENT(PyArray_Descr*descr)#

The alignment of the datatype.

PyObject*PyDataType_METADATA(PyArray_Descr*descr)#

The Metadata attached to a dtype, eitherNULL 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 mustnot be mutated, NumPy may change the way fields are stored in the future.

This is the same dict as returned bynp.dtype.fields.

NpyAuxData*PyDataType_C_METADATA(PyArray_Descr*descr)#

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

PyArray_ArrayDescr*PyDataType_SUBARRAY(PyArray_Descr*descr)#

Information about a subarray dtype equivalent to the Pythonnp.dtype.baseandnp.dtype.shape.

If this is non-NULL, then this data-type descriptor is aC-style contiguous array of another data-type descriptor. Inother-words, each element that this descriptor describes isactually an array of some other base descriptor. This is mostuseful as the data-type descriptor for a field in anotherdata-type descriptor. The fields member should beNULL if thisis non-NULL (the fields member of the base descriptor can benon-NULL however).

typePyArray_ArrayDescr#

typedefstruct{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 Pythontuple.

Data-type checking#

For the typenum macros, the argument is an integer representing anenumerated array data type. For the array type checking macros theargument must be aPyObject* that can be directly interpreted as aPyArrayObject*.

intPyTypeNum_ISUNSIGNED(intnum)#

intPyDataType_ISUNSIGNED(PyArray_Descr*descr)#

intPyArray_ISUNSIGNED(PyArrayObject*obj)#

Type represents an unsigned integer.

intPyTypeNum_ISSIGNED(intnum)#

intPyDataType_ISSIGNED(PyArray_Descr*descr)#

intPyArray_ISSIGNED(PyArrayObject*obj)#

Type represents a signed integer.

intPyTypeNum_ISINTEGER(intnum)#

intPyDataType_ISINTEGER(PyArray_Descr*descr)#

intPyArray_ISINTEGER(PyArrayObject*obj)#

Type represents any integer.

intPyTypeNum_ISFLOAT(intnum)#

intPyDataType_ISFLOAT(PyArray_Descr*descr)#

intPyArray_ISFLOAT(PyArrayObject*obj)#

Type represents any floating point number.

intPyTypeNum_ISCOMPLEX(intnum)#

intPyDataType_ISCOMPLEX(PyArray_Descr*descr)#

intPyArray_ISCOMPLEX(PyArrayObject*obj)#

Type represents any complex floating point number.

intPyTypeNum_ISNUMBER(intnum)#

intPyDataType_ISNUMBER(PyArray_Descr*descr)#

intPyArray_ISNUMBER(PyArrayObject*obj)#

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

intPyTypeNum_ISSTRING(intnum)#

intPyDataType_ISSTRING(PyArray_Descr*descr)#

intPyArray_ISSTRING(PyArrayObject*obj)#

Type represents a string data type.

intPyTypeNum_ISFLEXIBLE(intnum)#

intPyDataType_ISFLEXIBLE(PyArray_Descr*descr)#

intPyArray_ISFLEXIBLE(PyArrayObject*obj)#

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

intPyDataType_ISUNSIZED(PyArray_Descr*descr)#

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

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

intPyTypeNum_ISUSERDEF(intnum)#

intPyDataType_ISUSERDEF(PyArray_Descr*descr)#

intPyArray_ISUSERDEF(PyArrayObject*obj)#

Type represents a user-defined type.

intPyTypeNum_ISEXTENDED(intnum)#

intPyDataType_ISEXTENDED(PyArray_Descr*descr)#

intPyArray_ISEXTENDED(PyArrayObject*obj)#

Type is either flexible or user-defined.

intPyTypeNum_ISOBJECT(intnum)#

intPyDataType_ISOBJECT(PyArray_Descr*descr)#

intPyArray_ISOBJECT(PyArrayObject*obj)#

Type represents object data type.

intPyTypeNum_ISBOOL(intnum)#

intPyDataType_ISBOOL(PyArray_Descr*descr)#

intPyArray_ISBOOL(PyArrayObject*obj)#

Type represents Boolean data type.

intPyDataType_HASFIELDS(PyArray_Descr*descr)#

intPyArray_HASFIELDS(PyArrayObject*obj)#

Type has fields associated with it.

intPyArray_ISNOTSWAPPED(PyArrayObject*m)#

Evaluates true if the data area of the ndarraym is in machinebyte-order according to the array’s data-type descriptor.

intPyArray_ISBYTESWAPPED(PyArrayObject*m)#

Evaluates true if the data area of the ndarraym isnot inmachine byte-order according to the array’s data-type descriptor.

npy_boolPyArray_EquivTypes(PyArray_Descr*type1,PyArray_Descr*type2)#

ReturnNPY_TRUE iftype1 andtype2 actually representequivalent types for this platform (the fortran member of eachtype is ignored). For example, on 32-bit platforms,NPY_LONG andNPY_INT are equivalent. OtherwisereturnNPY_FALSE.

npy_boolPyArray_EquivArrTypes(PyArrayObject*a1,PyArrayObject*a2)#

ReturnNPY_TRUE ifa1 anda2 are arrays with equivalenttypes for this platform.

npy_boolPyArray_EquivTypenums(inttypenum1,inttypenum2)#

Special case ofPyArray_EquivTypes (…) that does not acceptflexible data types but may be easier to call.

intPyArray_EquivByteorders(intb1,intb2)#

True if byteorder charactersb1 andb2 (NPY_LITTLE,NPY_BIG,NPY_NATIVE,NPY_IGNORE ) areeither equal or equivalent as to their specification of a nativebyte order. Thus, on a little-endian machineNPY_LITTLEandNPY_NATIVE are equivalent where they are notequivalent on a big-endian machine.

Converting data types#

PyObject*PyArray_Cast(PyArrayObject*arr,inttypenum)#

Mainly for backwards compatibility to the Numeric C-API and forsimple casts to non-flexible types. Return a new array object withthe elements ofarr cast to the data-typetypenum which mustbe one of the enumerated types and not a flexible type.

PyObject*PyArray_CastToType(PyArrayObject*arr,PyArray_Descr*type,intfortran)#

Return a new array of thetype specified, casting the elementsofarr as appropriate. The fortran argument specifies theordering of the output array.

intPyArray_CastTo(PyArrayObject*out,PyArrayObject*in)#

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

Cast the elements of the arrayin into the arrayout. Theoutput array should be writeable, have an integer-multiple of thenumber of elements in the input array (more than one copy can beplaced in out), and have a data type that is one of the builtintypes. Returns 0 on success and -1 if an error occurs.

intPyArray_CanCastSafely(intfromtype,inttotype)#

Returns non-zero if an array of data typefromtype can be castto an array of data typetotype without losing information. Anexception is that 64-bit integers are allowed to be cast to 64-bitfloating point values even though this can lose precision on largeintegers so as not to proliferate the use of long doubles withoutexplicit requests. Flexible array types are not checked accordingto their lengths with this function.

intPyArray_CanCastTo(PyArray_Descr*fromtype,PyArray_Descr*totype)#

PyArray_CanCastTypeTo supersedes this function inNumPy 1.6 and later.

Equivalent to PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING).

intPyArray_CanCastTypeTo(PyArray_Descr*fromtype,PyArray_Descr*totype,NPY_CASTINGcasting)#

Returns non-zero if an array of data typefromtype (which caninclude flexible types) can be cast safely to an array of datatypetotype (which can include flexible types) according tothe casting rulecasting. For simple types withNPY_SAFE_CASTING,this is basically a wrapper aroundPyArray_CanCastSafely, butfor flexible types such as strings or unicode, it produces resultstaking into account their sizes. Integer and float types can only be castto a string or unicode type usingNPY_SAFE_CASTING if the stringor unicode type is big enough to hold the max value of the integer/floattype being cast from.

intPyArray_CanCastArrayTo(PyArrayObject*arr,PyArray_Descr*totype,NPY_CASTINGcasting)#

Returns non-zero ifarr can be cast tototype accordingto the casting rule given incasting. Ifarr is an arrayscalar, its value is taken into account, and non-zero is alsoreturned when the value will not overflow or be truncated toan integer when converting to a smaller type.

PyArray_Descr*PyArray_MinScalarType(PyArrayObject*arr)#

Note

With the adoption of NEP 50 in NumPy 2, this function is not usedinternally. It is currently provided for backwards compatibility,but expected to be eventually deprecated.

Ifarr is an array, returns its data type descriptor, but ifarr is an array scalar (has 0 dimensions), it finds the data typeof smallest size to which the value may be convertedwithout overflow or truncation to an integer.

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

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

Finds the data type of smallest size and kind to whichtype1 andtype2 may be safely converted. This function is symmetric andassociative. A string or unicode result will be the proper size forstoring the max value of the input types converted to a string or unicode.

PyArray_Descr*PyArray_ResultType(npy_intpnarrs,PyArrayObject**arrs,npy_intpndtypes,PyArray_Descr**dtypes)#

This applies type promotion to all the input arrays and dtypeobjects, using the NumPy rules for combining scalars and arrays, todetermine the output type for an operation with the given set ofoperands. This is the same result type that ufuncs produce.

See the documentation ofnumpy.result_type for moredetail about the type promotion algorithm.

intPyArray_ObjectType(PyObject*op,intmintype)#

This function is superseded byPyArray_ResultType.

This function is useful for determining a common type that two ormore arrays can be converted to. It only works for non-flexiblearray types as no itemsize information is passed. Themintypeargument represents the minimum type acceptable, andoprepresents the object that will be converted to an array. Thereturn value is the enumerated typenumber that represents thedata-type thatop should have.

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

The functionality this provides is largely superseded by iteratorNpyIter introduced in 1.6, with flagNPY_ITER_COMMON_DTYPE or with the same dtype parameter forall operands.

Convert a sequence of Python objects contained inop to an arrayof ndarrays each having the same data type. The type is selectedin the same way asPyArray_ResultType. The length of the sequence isreturned inn, and ann -length array ofPyArrayObjectpointers is the return value (orNULL if an error occurs).The returned array must be freed by the caller of this routine(usingPyDataMem_FREE ) and all the array objects in itDECREF ‘d or a memory-leak will occur. The example template-codebelow shows a typical usage:

mps=PyArray_ConvertToCommonType(obj,&n);if(mps==NULL)returnNULL;{code}<beforereturn>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 sizearr ->itemsize thatholds the representation of 0 for that type. The returned pointer,ret,must be freed usingPyDataMem_FREE (ret) when it isnot needed anymore.

char*PyArray_One(PyArrayObject*arr)#

A pointer to newly created memory of sizearr ->itemsize thatholds the representation of 1 for that type. The returned pointer,ret,must be freed usingPyDataMem_FREE (ret) when itis not needed anymore.

intPyArray_ValidType(inttypenum)#

ReturnsNPY_TRUE iftypenum represents a valid type-number(builtin or user-defined or character code). Otherwise, thisfunction returnsNPY_FALSE.

User-defined data types#

voidPyArray_InitArrFuncs(PyArray_ArrFuncs*f)#

Initialize all function pointers and members toNULL.

intPyArray_RegisterDataType(PyArray_DescrProto*dtype)#

Note

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

Compiling for NumPy 1.x and 2.x

NumPy 2.x requires passing in aPyArray_DescrProto typed structrather than aPyArray_Descr. This is necessary to allow changes.To allow code to run and compile on both 1.x and 2.x you need tochange the type of your struct toPyArray_DescrProto and add:

/*AllowcompilingonNumPy1.x*/#if NPY_ABI_VERSION < 0x02000000#define PyArray_DescrProto PyArray_Descr#endif

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

inttype_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.xand 2.x or later.

In the unlikely case that you are heap allocating the dtype struct youshould free it again on NumPy 2, since a copy is made.The struct is not a valid Python object, so do not usePy_DECREFon it.

Register a data-type as a new user-defined data type forarrays. The type must have most of its entries filled in. This isnot always checked and errors can produce segfaults. Inparticular, the typeobj member of thedtype structure must befilled with a Python type that has a fixed-size element-size thatcorresponds to the elsize member ofdtype. Also thefmember must have the required functions: nonzero, copyswap,copyswapn, getitem, setitem, and cast (some of the cast functionsmay beNULL if no support is desired). To avoid confusion, youshould choose a unique character typecode but this is not enforcedand not relied on internally.

A user-defined type number is returned that uniquely identifiesthe type. A pointer to the new structure can then be obtained fromPyArray_DescrFromType using the returned type number. A -1 isreturned if an error occurs. If thisdtype has already beenregistered (checked only by the address of the pointer), thenreturn the previously-assigned type-number.

The number of user DTypes known to numpy is stored inNPY_NUMUSERTYPES, a static global variable that is public in theC API. Accessing this symbol is inherentlynot thread-safe. Iffor some reason you need to use this API in a multithreaded context,you will need to add your own locking, NumPy does not ensure newdata types can be added in a thread-safe manner.

intPyArray_RegisterCastFunc(PyArray_Descr*descr,inttotype,PyArray_VectorUnaryFunc*castfunc)#

Register a low-level casting function,castfunc, to convertfrom the data-type,descr, to the given data-type number,totype. Any old casting function is over-written. A0 isreturned on success or a-1 on failure.

typePyArray_VectorUnaryFunc#

The function pointer type for low-level casting functions.

intPyArray_RegisterCanCast(PyArray_Descr*descr,inttotype,NPY_SCALARKINDscalar)#

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

Special functions for NPY_OBJECT#

intPyArray_INCREF(PyArrayObject*op)#

Used for an array,op, that contains any Python objects. Itincrements the reference count of every object in the arrayaccording to the data-type ofop. A -1 is returned if an erroroccurs, otherwise 0 is returned.

voidPyArray_Item_INCREF(char*ptr,PyArray_Descr*dtype)#

A function to INCREF all the objects at the locationptraccording to the data-typedtype. Ifptr is the start of astructured type with an object at any offset, then this will (recursively)increment the reference count of all object-like items in thestructured type.

intPyArray_XDECREF(PyArrayObject*op)#

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

voidPyArray_Item_XDECREF(char*ptr,PyArray_Descr*dtype)#

A function to XDECREF all the object-like items at the locationptr as recorded in the data-type,dtype. This worksrecursively so that ifdtype itself has fields with data-typesthat contain object-like items, all the object-like fields will beXDECREF'd.

intPyArray_SetWritebackIfCopyBase(PyArrayObject*arr,PyArrayObject*base)#

Precondition:arr is a copy ofbase (though possibly with differentstrides, ordering, etc.) Sets theNPY_ARRAY_WRITEBACKIFCOPY flagandarr->base, and setbase to READONLY. CallPyArray_ResolveWritebackIfCopy before callingPy_DECREF in order to copy any changes back tobase andreset 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 contiguouschunk of well-behaved memory you can manipulate. It may not be alignedwith word boundaries (very important on some platforms). It might haveits data in a different byte-order than the machine recognizes. Itmight not be writeable. It might be in Fortran-contiguous order. Thearray flags are used to indicate what can be said about dataassociated with an array.

NPY_ARRAY_C_CONTIGUOUS#

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

NPY_ARRAY_F_CONTIGUOUS#

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

NPY_ARRAY_OWNDATA#

The data area is owned by this array. Should never be set manually, insteadcreate aPyObject wrapping the data and set the array’s base to thatobject. For an example, see the test intest_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 informationshould be transferred back to the original whenPyArray_ResolveWritebackIfCopy is called.

This is a special flag that is set if this array represents a copymade because a user required certain flags inPyArray_FromAny and a copy had to be made of some otherarray (and the user asked for this flag to be set in such asituation). The base attribute then points to the “misbehaved”array (which is set read_only).PyArray_ResolveWritebackIfCopywill copy its contents back to the “misbehaved”array (casting if necessary) and will reset the “misbehaved” arraytoNPY_ARRAY_WRITEABLE. If the “misbehaved” array was notNPY_ARRAY_WRITEABLE to begin with thenPyArray_FromAnywould have returned an error becauseNPY_ARRAY_WRITEBACKIFCOPYwould not have been possible.

PyArray_UpdateFlags (obj, flags) will update theobj->flagsforflags which can be any ofNPY_ARRAY_C_CONTIGUOUS,NPY_ARRAY_F_CONTIGUOUS,NPY_ARRAY_ALIGNED, orNPY_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 inPyArray_FromAny (and its macro forms) tospecify desired properties of the new array.

NPY_ARRAY_FORCECAST#

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

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 inPyArray_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 inmachine byte-order, over-riding any specification in thedtypeargument. Normally, the byte-order requirement is determined bythedtype argument. If this flag is set and the dtype argumentdoes not indicate a machine byte-order descriptor (or is NULL andthe object is already an array with a data-type descriptor that isnot in machine byte- order), then a new data-type descriptor iscreated 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 theelement size.

Flag checking#

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

intPyArray_CHKFLAGS(constPyArrayObject*arr,intflags)#

The first parameter, arr, must be an ndarray or subclass. Theparameter,flags, should be an integer consisting of bitwisecombinations 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.

intPyArray_IS_C_CONTIGUOUS(constPyArrayObject*arr)#

Evaluates true ifarr is C-style contiguous.

intPyArray_IS_F_CONTIGUOUS(constPyArrayObject*arr)#

Evaluates true ifarr is Fortran-style contiguous.

intPyArray_ISFORTRAN(constPyArrayObject*arr)#

Evaluates true ifarr is Fortran-style contiguous andnotC-style contiguous.PyArray_IS_F_CONTIGUOUSis the correct way to test for Fortran-style contiguity.

intPyArray_ISWRITEABLE(constPyArrayObject*arr)#

Evaluates true if the data area ofarr can be written to

intPyArray_ISALIGNED(constPyArrayObject*arr)#

Evaluates true if the data area ofarr is properly aligned onthe machine.

intPyArray_ISBEHAVED(constPyArrayObject*arr)#

Evaluates true if the data area ofarr is aligned and writeableand in machine byte-order according to its descriptor.

intPyArray_ISBEHAVED_RO(constPyArrayObject*arr)#

Evaluates true if the data area ofarr is aligned and in machinebyte-order.

intPyArray_ISCARRAY(constPyArrayObject*arr)#

Evaluates true if the data area ofarr is C-style contiguous,andPyArray_ISBEHAVED (arr) is true.

intPyArray_ISFARRAY(constPyArrayObject*arr)#

Evaluates true if the data area ofarr is Fortran-stylecontiguous andPyArray_ISBEHAVED (arr) is true.

intPyArray_ISCARRAY_RO(constPyArrayObject*arr)#

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

intPyArray_ISFARRAY_RO(constPyArrayObject*arr)#

Evaluates true if the data area ofarr is Fortran-stylecontiguous, aligned, and in machine byte-order.

intPyArray_ISONESEGMENT(constPyArrayObject*arr)#

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

voidPyArray_UpdateFlags(PyArrayObject*arr,intflagmask)#

TheNPY_ARRAY_C_CONTIGUOUS,NPY_ARRAY_ALIGNED, andNPY_ARRAY_F_CONTIGUOUS array flags can be “calculated” from thearray object itself. This routine updates one or more of theseflags ofarr as specified inflagmask by performing therequired calculation.

intPyArray_FailUnlessWriteable(PyArrayObject*obj,constchar*name)#

This function does nothing and returns 0 ifobj is writeable.It raises an exception and returns -1 ifobj is not writeable.It may also do other house-keeping, such as issuing warnings onarrays which are transitioning to become views. Always call thisfunction 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 slotimplements. SeeSlots and Typedefs below for documentation onthe functions that must be implemented for each slot.

NPY_METH_resolve_descriptors#

typedefNPY_CASTING(PyArrayMethod_ResolveDescriptors)(structPyArrayMethodObject_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 onthe descriptors of the operands. For example, a ufunc operation withtwo input operands and one output operand that is called withoutout being set in the python API,resolve_descriptors will bepassed the descriptors for the two operands and determine the correctdescriptor to use for the output based on the output DType set forthe ArrayMethod. Ifout is set, then the output descriptor wouldbe passed in as well and should not be overridden.

Themethod is a pointer to the underlying cast or ufunc loop. Inthe future we may expose this struct publicly but for now this is anopaque pointer and the method cannot be inspected. Thedtypes is annargs length array ofPyArray_DTypeMeta pointers,given_descrs is annargs length array of input descriptorinstances (output descriptors may be NULL if no output was providedby the user), andloop_descrs is annargs length array ofdescriptors that must be filled in by the resolve descriptorsimplementation.view_offset is currently only interesting forcasts and can normally be ignored. When a cast does not require anyoperation, this can be signalled by settingview_offset to 0. Onerror, 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 aufunc or cast). In most cases,NPY_METH_strided_loop is thegeneric and only version that needs to be implemented.NPY_METH_contiguous_loop can be implemented additionally as amore light-weight/faster version and it is used when all inputs andoutputs are contiguous.

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

type_inin_value;type_outout_valuememcpy(&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 neverbe picked in ufuncs (ufuncs create a temporary copy to ensure alignedinputs). These slot IDs are ignored whenNPY_METH_get_loop isdefined, where instead whichever loop returned by theget_loopfunction is used.

NPY_METH_contiguous_indexed_loop#

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

typedefint(PyArrayMethod_StridedLoop)(PyArrayMethod_Context*context,char*const*data,constnpy_intp*dimensions,constnpy_intp*strides,NpyAuxData*auxdata)#

An implementation of an ArrayMethod loop. All of the loop slot IDslisted above must provide aPyArrayMethod_StridedLoopimplementation. Thecontext is a struct containing context for theloop operation - in particular the input descriptors. Thedata arean array of pointers to the beginning of the input and output arraybuffers. Thedimensions are the loop dimensions for theoperation. Thestrides are annargs length array of strides foreach input. Theauxdata is an optional set of auxiliary data thatcan be passed in to the loop - helpful to turn on and off optionalbehavior or reduce boilerplate by allowing similar ufuncs to shareloop implementations or to allocate space that is persistent overmultiple strided loop calls.

NPY_METH_get_loop#

Allows more fine-grained control over loop selection. Accepts animplementation of PyArrayMethod_GetLoop, which in turn returns astrided loop implementation. IfNPY_METH_get_loop is defined,the other loop slot IDs are ignored, if specified.

typedefint(PyArrayMethod_GetLoop)(PyArrayMethod_Context*context,intaligned,intmove_references,constnpy_intp*strides,PyArrayMethod_StridedLoop**out_loop,NpyAuxData**out_transferdata,NPY_ARRAYMETHOD_FLAGS*flags);#

Sets the loop to use for an operation at runtime. Thecontext is theruntime context for the operation.aligned indicates whether the dataaccess for the loop is aligned (1) or unaligned (0).move_referencesindicates whether embedded references in the data should be copied.stridesare the strides for the input array,out_loop is a pointer that must befilled in with a pointer to the loop implementation.out_transferdata canbe optionally filled in to allow passing in extra user-defined context to anoperation.flags must be filled in with ArrayMethod flags relevant for theoperation. This is for example necessary to indicate if the inner looprequires the Python GIL to be held.

NPY_METH_get_reduction_initial#

typedefint(PyArrayMethod_GetReductionInitial)(PyArrayMethod_Context*context,npy_boolreduction_is_empty,char*initial)#

Query an ArrayMethod for the initial value for use in reduction. Thecontext is the ArrayMethod context, mainly to access the inputdescriptors.reduction_is_empty indicates whether the reduction isempty. 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 forsum([]). But-0.0 is the correctidentity otherwise as it preserves the sign forsum([-0.0]).

• We use no identity for object, but return the default of0 and1 for the emptysum([],dtype=object) andprod([],dtype=object).This allowsnp.sum(np.array(["a","b"],dtype=object)) to work.

• -inf orINT_MIN formax is an identity, but at leastINT_MIN not a gooddefault when there are no items.

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

Flags#

enumNPY_ARRAYMETHOD_FLAGS#

These flags allow switching on and off custom runtime behavior forArrayMethod loops. For example, if a ufunc cannot possibly trigger floatingpoint errors, then theNPY_METH_NO_FLOATINGPOINT_ERRORS flag should beset on the ufunc when it is registered.

enumeratorNPY_METH_REQUIRES_PYAPI#

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

enumeratorNPY_METH_NO_FLOATINGPOINT_ERRORS#

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

enumeratorNPY_METH_SUPPORTS_UNALIGNED#

Indicates the method supports unaligned access.

enumeratorNPY_METH_IS_REORDERABLE#

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

enumeratorNPY_METH_RUNTIME_FLAGS#

The flags that can be changed at runtime.

Typedefs#

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

typedefint(PyArrayMethod_TraverseLoop)(void*traverse_context,constPyArray_Descr*descr,char*data,npy_intpsize,npy_intpstride,NpyAuxData*auxdata)#

A traverse loop working on a single array. This is similar to the generalstrided-loop function. This is designed for loops that need to visit everyelement of a single array.

Currently this is used for array clearing, via theNPY_DT_get_clear_loopDType API hook, and zero-filling, via theNPY_DT_get_fill_zero_loopDType API hook. These are most useful for handling arrays storing embeddedreferences to python objects or heap-allocated data.

Thedescr is the descriptor for the array,data is a pointer to the arraybuffer,size is the 1D size of the array buffer,stride is the stride,andauxdata is optional extra data for the loop.

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

typedefint(PyArrayMethod_GetTraverseLoop)(void*traverse_context,constPyArray_Descr*descr,intaligned,npy_intpfixed_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 setout_loop to theloop function, which must be a validPyArrayMethod_TraverseLooppointer. Currently this is used for zero-filling and clearing arrays storingembedded references.

API Functions and Typedefs#

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

intPyUFunc_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/loopto a ufunc. It replacesPyUFunc_RegisterLoopForType.

intPyUFunc_AddPromoter(PyObject*ufunc,PyObject*DType_tuple,PyObject*promoter)#

Note that currently the output dtypes are alwaysNULL unless they arealso part of the signature. This is an implementation detail and couldchange in the future. However, in general promoters should not have aneed for output dtypes.Register a new promoter for a ufunc. The first argument is the ufunc toregister the promoter with. The second argument is a Python tuple containingDTypes or None matching the number of inputs and outputs for the ufuncs. Thelast argument is a promoter is a function stored in a PyCapsule. It ispassed the operation and requested DType signatures and can mutate it toattempt a new search for a matching loop/promoter.

typedefint(PyArrayMethod_PromoterFunction)(PyObject*ufunc,PyArray_DTypeMeta*constop_dtypes[],PyArray_DTypeMeta*constsignature[],PyArray_DTypeMeta*new_op_dtypes[])#

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

intPyUFunc_GiveFloatingpointErrors(constchar*name,intfpe_errors)#

Checks for a floating point error after performing a floating pointoperation in a manner that takes into account the error signaling configuredvianumpy.errstate. Takes the name of the operation to use in the errormessage and an integer flag that is one ofNPY_FPE_DIVIDEBYZERO,NPY_FPE_OVERFLOW,NPY_FPE_UNDERFLOW,NPY_FPE_INVALID to indicatewhich error to check for.

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

intPyUFunc_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 existingufunc loop. The idea is mainly for units, as this is currentlyslightly limited in that it enforces that you cannot use a loop fromanother ufunc.

typedefint(PyArrayMethod_TranslateGivenDescriptors)(intnin,intnout,PyArray_DTypeMeta*wrapped_dtypes[],PyArray_Descr*given_descrs[],PyArray_Descr*new_descrs[]);#

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

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

typedefint(PyArrayMethod_TranslateLoopDescriptors)(intnin,intnout,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 bythe originalresolve_descriptors function) to the ones the outputarray should use. This function must return “viewable” types, it mustnot 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;}intres=PyUFunc_AddWrappingLoop(multiply,orig_dtypes,wrapped_dtypes,&translate_given_descrs&translate_loop_descrs);Py_DECREF(multiply);

staticinttranslate_given_descrs(intnin,intnout,PyArray_DTypeMeta*NPY_UNUSED(wrapped_dtypes[]),PyArray_Descr*given_descrs[],PyArray_Descr*new_descrs[]){for(inti=0;i<nin+nout;i++){if(given_descrs[i]==NULL){new_descrs[i]=NULL;}else{new_descrs[i]=PyArray_DescrFromType(NPY_DOUBLE);}}return0;}staticinttranslate_loop_descrs(intnin,intNPY_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]);}