PyArray DescrType

The PyArrayDescr_Type is the built-in type of the data-type-descriptor objects used to describe how the bytes comprising the array are to be interpreted. There are 21 statically-defined PyArray_Descr objects for the built-in data-types. While these participate in reference counting, their reference count should never reach zero. There is also a dynamic table of user-defined PyArray_Descr objects that is also maintained. Once a data-type-descriptor object is "registered" it should never be deallocated either. The function PyArray_DescrFromType(...) can be used to retrieve a PyArray_Descr object from an enumerated type-number (either built-in or user-defined). The format of the structure that lies at the heart of the PyArrayDescr_Type is.

typedef struct { PyObject_HEAD PyTypeObject *typeobj; char kind; char type; char byteorder; char hasobject; int type_num; int elsize; int alignment;

PyArray-ArrayDescr *subarray; PyObject * fields; PyArray-ArrFuncs *f; } PyArrayJDe scr;

typeobj Pointer to a typeobject that is the corresponding Python type for the elements of this array. For the builtin types, this points to the corresponding array scalar. For user-defined types, this should point to a user-defined typeobject. This typeobject can either inherit from array scalars or not. If it does not inherit from array scalars, then the NPY_USE_GETITEM and NPY_USE_SETITEM flags should be set in the hasobject flag.

kind A character code indicating the kind of array (using the array interface typestring notation). A 'b' represents Boolean, a 'i' represents signed integer, a 'u' represents unsigned integer, 'f' represents floating point, 'c' represents complex floating point, 'S' represents 8-bit character string, 'U' represents 32-bit/character unicode string, and 'V' repesents arbitrary.

type A traditional character code indicating the data type.

byteorder A character indicating the byte-order: '>' (big-endian), '<' (little-endian), '=' (native), '|' (irrelevant, ignore). All builtin data-types have byteorder '='.

hasobject A data-type bit-flag that determines if the data-type exhibits object-

array like behavior. Each bit in this member is a flag which are named as:

NPY_ITEM_REFCOUNT (NPYJTEM_HASOBJECT) Indicates that items of this data-type must be reference counted (using Py_INCREF and Py_DECREF).

NPYJTEM_LISTPICKLE Indicates arrays of this data-type must be converted to a list before pickling.

NPYJTEMJS.POINTER Indicates the item is a pointer to some other data-type

NPY_NEEDS JNIT Indicates memory for this data-type must be initialized (set to 0) on creation.

NPY_NEEDS_PYAPI Indicates this data-type requires the Python G-API during access (so don't give up the GIL if array access is going to be needed).

NPY_USE_GETITEM On array access use the f->getitem function pointer instead of the standard conversion to an array scalar. Must use if you don't define an array scalar to go along with the data-type.

NPY_USE_SETITEM When creating a 0-d array from an array scalar use f->setitem instead of the standard copy from an array scalar. Must use if you don't define an array scalar to go along with the data-type.

NPY_FROM_FIELDS The bits that are inherited for the parent datatype if these bits are set in any field of the data-type. Currently (NPY_NEEDS_INIT | NPY_LIST_PICKLE | NPY_ITEM_REFCOUNT | NPYJSTEEDS-PYAPI).


PyDataType_FLAGCHK (PyArray_Descr* dtype, int flags) Return true if all the given flags are set for the data-type object.

PyDataType_REFCHK (PyArray_Descr* dtype) Equivalent to PyDataType_FLAGCHK(f%pe, NPY_ITEM_REFCOUNT).

type_num A number that uniquely identifies the data type. For new data-types, this number is assigned when the data-type is registered.

elsize For data types that are always the same size (such as long), this holds the size of the data type. For flexible data types where different arrays can have a different elementsize, this should be 0.

alignment A number providing alignment information for this data type. Specifically, it shows how far from the start of a 2-element structure (whose first element is a char), the compiler places an item of this type: offsetof(struct {char c; type v;}, v)

subarray 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 datatype descriptor. The fields member should be NULL if this is non-NULL (the fields member of the base descriptor can be non-NULL however). The PyArray_ArrayDescr structure is defined using typedef struct {

PyArrayJDescr * b a s e; PyObject *shape; } PyArray-ArrayDescr;

The elements of this structure are:

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

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

fields If this is non-NULL, then this data-type-descriptor has fields described by a Python dictionary whose keys are names (and also titles if given) and whose values are tuples that describe the fields. Recall that a data-type-descriptor always describes a fixed-length set of bytes. A field is a named sub-region of that total, fixed-length collection. A field is described by a tuple composed of another data-type-descriptor and a byte offset. Optionally, the tuple may contain a title which is normally a Python string. These tuples are placed in this dictionary keyed by name (and also title if given).

f A pointer to a structure containing functions that the type needs to implement internal features. These functions are not the same thing as the universal functions (ufuncs) described later. Their signatures can vary arbitrarily. Not all of these function pointers must be defined for a given type. The required members are nonzero, copyswap, copyswapn, setitem, getitem, and cast. These are assumed to be non-NULL and NULL entries will cause a program crash. The other functions may be NULL which will just mean reduced functionality for that data-type. (Also, the nonzero function will be filled in with a default function if it is NULL when you register a user-defined data-type).

typedef struct {

PyArray-VectorUnaryFunc *cast [PyArrayJSTTYPES] ;

PyAr ray-Get I temFunc *getitem;

PyAr ray-Set I temFunc *setitem;

PyArray-CopySwapNFunc *copyswapn ;

PyArray-CopySwapFunc *copyswap;

PyArray-CompareFunc ^compare;

PyArray-ArgFun c *a rgmax ;

PyArrayJDotFunc *dotfunc;

PyArrayScanFunc *scanfunc;

PyArray-FromStrFunc *fromstr;

PyArrayJsfonzeroFunc *nonzero;

PyArray-FillWi thScalarFunc * fill wit hscalar ;

PyArraySortFunc * sort [PyArrayJSTSORTS] ;

PyArray-ArgSortFunc *argsort [PyArrayJSTSORTS] ;

PyObject *castdict;

PyAr r ayScal arKindFunc * scalarkind;

int **cancastscalarkindto;

int *cancastto;

int listpickle } PyArray-ArrFuncs ;

The concept of a behaved segment is used in the description of the function pointers. A behaved segment is one that is aligned and in native machine byteorder for the data-type. The nonzero, copyswap, copyswapn, getitem, and setitem functions can (and must) deal with mis-behaved arrays. The other functions require behaved memory segments.

cast (void) (void* from, void* to, npy_intp n, void* fromarr, void* toarr)

An array of function pointers to cast from the current type to all of the other builtin types. Each function casts a contiguous, aligned, and notswapped buffer pointed at by from to a contiguous, aligned, and notswapped buffer pointed at by to The number of items to cast is given by n, and the arguments fromarr and toarr are interpreted as PyArrayObjects for flexible arrays to get itemsize information.

A pointer to a function that returns a standard Python object from a single element of the array object arr pointed to by data. This function must be able to deal with "misbehaved" (misaligned and/or swapped) arrays correctly.

setitem (int) (PyObject* item, void* data, void* arr)

A pointer to a function that sets the Python object item into the array, arr, at the position pointed to by data. This function deals with "misbehaved" arrays. If successful, a zero is returned, otherwise, a negative one is returned (and a Python error set).

copyswapn (void) (void* dest, npy_intp dstride, void* src, npy_intp sstride, npy_intp n, int swap, void *arr)

copyswap (void) (void* dest, void* src, int swap, void *arr)

These members are both pointers to functions to copy data from src to dest and swap if indicated. The value of arr is only used for flexible (NPYJ3TRING, NPY_UNICODE, and NPY.VOID) arrays (and is obtained from arr->descr->elsize). The second function copies a single value, while the first loops over n values with the provided strides. These functions can deal with misbehaved src data. If src is NULL then no copy is performed. If swap is 0, then no byteswapping occurs. It is assumed that dest and src do not overlap. If they overlap, then use memmove(...) first followed by copyswap (n) with NULL valued src.

compare (int) (const void* d1, const void* d2, void* arr)

A pointer to a function that compares two elements of the array, arr, pointed to by d1 and d2. This function requires behaved arrays. The return value is 1 if *d1 > *d2, 0 if *d1 == *d2, and -1 if *d1 < *d2. The array object arr is used to retrieve itemsize and field information for flexible arrays.

argmax (int) (void* data, npy_intp n, npy_intp* max_ind, void* arr)

A pointer to a function that retrieves the index of the largest of n elements in arr beginning at the element pointed to by data. This function requires that the memory segment be contiguous and behaved. The return value is always 0. The index of the largest element is returned in max_ind.

dotfunc (void) (void* ipl, npy_intp isl, void* ip2, npy_intp is2, void* op, npy_intp n, void* arr)

A pointer to a function that multiplies two n-length sequences together, adds them, and places the result in element pointed to by op of arr. The start of the two sequences are pointed to by ip1 and ip2. To get to the next element in each sequence requires a jump of is1 and is2 bytes, respectively. This function requires behaved (though not necessarily contiguous) memory.

scanfunc (int) (FILE* fd, void* ip ,void* sep ,void* arr)

A pointer to a function that scans (scanf style) one element of the corresponding type from the file descriptor fd into the array memory pointed to by ip. The array is assumed to be behaved. If sep is not NULL, then a separator string is also scanned from the file before returning. The last argument arr is the array to be scanned into. A 0 is returned if the scan is successful. A negative number indicates something went wrong: -1 means the end of file was reached before the separator string could be scanned, -4 means that the end of file was reached before the element could be scanned, and -3 means that the element could not be interpreted from the format string. Requires a behaved array.

fromstr (int) (char* str, void* ip, char** endptr, void* arr)

A pointer to a function that converts the string pointed to by str to one element of the corresponding type and places it in the memory location pointed to by ip. After the conversion is completed, *endptr points to the rest of the string. The last argument arr is the array into which ip points (needed for variable-size data-types). Returns 0 on success or -1 on failure. Requires a behaved array.

A pointer to a function that returns TRUE if the item of arr pointed to by data is nonzero. This function can deal with misbehaved arrays.

fill (void) (void* data, npy_intp length, void* arr)

A pointer to a function that fills a contiguous array of given length with data. The first two elements of the array must already be filled-in. From these two values, a delta will be computed and the values from item 3 to the end will be computed by repeatedly adding this computed delta. The data buffer must be well-behaved.

fillwithscalar (void)(void* buffer, npy_intp length, void* value, void* arr)

A pointer to a function that fills a contiguous buffer of the given length with a single scalar value whose address is given. The final argument is the array which is needed to get the itemsize for variable-length arrays.

sort (int) (void* start, npy_intp length, void* arr)

An array of function pointers to a particular sorting algorithms. A particular sorting algorithm is obtained using a key (so far PyArray_QUICKSORT, PyArray_HEAPSORT, and PyArray_MERGESORT are defined). These sorts are done in-place assuming contiguous and aligned data.

argsort (int) (void* start, npy_intp* result, npy_intp length, void *arr)

An array of function pointers to sorting algorithms for this data type. The same sorting algorithms as for sort are available. The indices producing the sort are returned in result (which must be initialized with indices 0 to length-1 inclusive).


Either NULL or a dictionary containing low-level casting functions for user-defined data-types. Each function is wrapped in a PyCObject* and keyed by the data-type number.

scalarkind (PyArray_SCALARKIND) (PyArrayObj ect* arr)

A function to determine how scalars of this type should be interpreted. The argument is NULL or a 0-dimensional array containing the data (if that is needed to determine the kind of scalar). The return value must be of type PyArray_SCALARKIND.


Either NULL or an array of PyArray_NSCALARKINDS pointers. These pointers should each be either NULL or a pointer to an array of integers (terminated by PyArray_NOTYPE) indicating data-types that a scalar of this data-type of the specified kind can be cast to safely (this usually means without losing precision).


Either NULL or an array of integers (terminated by PyArray_NOTYPE) indicated data-types that this data-type can be cast to safely (this usually means without losing precision).



The PyArray-Type typeobject implements many of the features of Python objects including the tp_as_number, tp_asj3equence, tp_as_mapping, and tp_as_buffer interfaces. The rich comparison (tp_richcompare) is also used along with new-style attribute lookup for methods (tp_methods) and properties (tp_getset). The PyArray-Type can also be sub-typed.

The tp_as_number methods use a generic approach to call whatever function has been registered for handling the operation. The function PyNumeric_SetOps(..) can be used to register functions to handle particular mathematical operations (for all arrays). When the umath module is imported, it sets the numeric operations for all arrays to the corresponding ufuncs.

The tp_str and tp_repr methods can also be altered using PyS-tring_SetStringFunction(...).

0 0

Post a comment