Navigation

Several new types are defined in the C-code. Most of these are
accessible from Python, but a few are not exposed due to their limited
use. Every new Python type has an associated PyObject* with an
internal structure that includes a pointer to a “method table” that
defines how the new object behaves in Python. When you receive a
Python object into C code, you always get a pointer to a
PyObject structure. Because a PyObject structure is
very generic and defines only PyObject_HEAD, by itself it
is not very interesting. However, different objects contain more
details after the PyObject_HEAD (but you have to cast to the
correct type to access them — or use accessor functions or macros).

Python types are the functional equivalent in C of classes in Python.
By constructing a new Python type you make available a new object for
Python. The ndarray object is an example of a new type defined in C.
New types are defined in C by two basic steps:

creating a C-structure (usually named Py{Name}Object) that is
binary- compatible with the PyObject structure itself but holds
the additional information needed for that particular object;

populating the PyTypeObject table (pointed to by the ob_type
member of the PyObject structure) with pointers to functions
that implement the desired behavior for the type.

Instead of special method names which define behavior for Python
classes, there are “function tables” which point to functions that
implement the desired results. Since Python 2.2, the PyTypeObject
itself has become dynamic which allows C types that can be “sub-typed
“from other C-types in C, and sub-classed in Python. The children
types inherit the attributes and methods from their parent(s).

There are two major new types: the ndarray ( PyArray_Type )
and the ufunc ( PyUFunc_Type ). Additional types play a
supportive role: the PyArrayIter_Type, the
PyArrayMultiIter_Type, and the PyArrayDescr_Type
. The PyArrayIter_Type is the type for a flat iterator for an
ndarray (the object that is returned when getting the flat
attribute). The PyArrayMultiIter_Type is the type of the
object returned when calling broadcast (). It handles iteration
and broadcasting over a collection of nested sequences. Also, the
PyArrayDescr_Type is the data-type-descriptor type whose
instances describe the data. Finally, there are 21 new scalar-array
types which are new Python scalars corresponding to each of the
fundamental data types available for arrays. An additional 10 other
types are place holders that allow the array scalars to fit into a
hierarchy of actual Python types.

The PyArrayObject C-structure contains all of the required
information for an array. All instances of an ndarray (and its
subclasses) will have this structure. For future compatibility,
these structure members should normally be accessed using the
provided macros. If you need a shorter name, then you can make use
of NPY_AO which is defined to be equivalent to
PyArrayObject.

This is needed by all Python objects. It consists of (at least)
a reference count member ( ob_refcnt ) and a pointer to the
typeobject ( ob_type ). (Other elements may also be present
if Python was compiled with special options see
Include/object.h in the Python source tree for more
information). The ob_type member points to a Python type
object.

An integer providing the number of dimensions for this
array. When nd is 0, the array is sometimes called a rank-0
array. Such arrays have undefined dimensions and strides and
cannot be accessed. NPY_MAXDIMS is the largest number of
dimensions for any array.

This member is used to hold a pointer to another Python object that
is related to this array. There are two use cases: 1) If this array
does not own its own memory, then base points to the Python object
that owns it (perhaps another array object), 2) If this array has
the NPY_ARRAY_UPDATEIFCOPY flag set, then this array is
a working copy of a “misbehaved” array. As soon as this array is
deleted, the array pointed to by base will be updated with the
contents of this array.

A pointer to a data-type descriptor object (see below). The
data-type descriptor object is an instance of a new built-in
type which allows a generic description of memory. There is a
descriptor structure for each data type supported. This
descriptor structure contains useful information about the type
as well as a pointer to a table of function pointers to
implement specific functionality.

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).

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 flags member.

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{charc;typev;},v)

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). The PyArray_ArrayDescr structure is
defined using

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).

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.

Functions implementing internal features. 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).

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 byte-order 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.

void cast(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.

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).

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 ( NPY_STRING, 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.

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.

int argmax(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.

void dotfunc(void* ip1, npy_intp is1, 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 is2bytes, respectively. This function requires
behaved (though not necessarily contiguous) memory.

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.

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 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.

void fillwithscalar(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.

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

int argsort(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).

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
NPY_SCALARKIND.

Either NULL or an array of NPY_NSCALARKINDS
pointers. These pointers should each be either NULL or a
pointer to an array of integers (terminated by
NPY_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).

The PyArray_Type typeobject implements many of the features of
Python objects including the tp_as_number, tp_as_sequence,
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.

Tip

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 PyString_SetStringFunction(...).

The ufunc object is implemented by creation of the
PyUFunc_Type. It is a very simple type that implements only
basic getattribute behavior, printing behavior, and has call
behavior which allows these objects to act like functions. The
basic idea behind the ufunc is to hold a reference to fast
1-dimensional (vector) loops for each data type that supports the
operation. These one-dimensional loops all have the same signature
and are the key to creating a new ufunc. They are called by the
generic looping code as appropriate to implement the N-dimensional
function. There are also some generic 1-d loops defined for
floating and complexfloating arrays that allow you to define a
ufunc using a single scalar function (e.g. atanh).

Either PyUFunc_One, PyUFunc_Zero, or
PyUFunc_None to indicate the identity for this operation.
It is only used for a reduce-like call on an empty array.

void PyUFuncObject.functions(char** args, npy_intp* dims,

npy_intp* steps, void* extradata)

An array of function pointers — one for each data type
supported by the ufunc. This is the vector loop that is called
to implement the underlying function dims [0] times. The
first argument, args, is an array of nargs pointers to
behaved memory. Pointers to the data for the input arguments
are first, followed by the pointers to the data for the output
arguments. How many bytes must be skipped to get to the next
element in the sequence is specified by the corresponding entry
in the steps array. The last argument allows the loop to
receive extra information. This is commonly used so that a
single, generic vector loop can be used for multiple
functions. In this case, the actual scalar function to call is
passed in as extradata. The size of this function pointer
array is ntypes.

Extra data to be passed to the 1-d vector loops or NULL if
no extra-data is needed. This C-array must be the same size (
i.e. ntypes) as the functions array. NULL is used if
extra_data is not needed. Several C-API calls for UFuncs are
just 1-d vector loops that make use of this extra data to
receive a pointer to the actual function to call.

An array of nargsntypes 8-bit type_numbers
which contains the type signature for the function for each of
the supported (builtin) data types. For each of the ntypes
functions, the corresponding set of type numbers in this array
shows how the args argument should be interpreted in the 1-d
vector loop. These type numbers do not have to be the same type
and mixed-type ufuncs are supported.

A dictionary of user-defined 1-d vector loops (stored as CObject ptrs)
for user-defined types. A loop may be registered by the user for any
user-defined type. It is retrieved by type number. User defined type
numbers are always larger than NPY_USERDEF.

This is an iterator object that makes it easy to loop over an N-dimensional
array. It is the object returned from the flat attribute of an
ndarray. It is also used extensively throughout the implementation
internals to loop over an N-dimensional array. The tp_as_mapping
interface is implemented so that the iterator object can be indexed
(using 1-d indexing), and a few methods are implemented through the
tp_methods table. This object implements the next method and can be
used anywhere an iterator can be used in Python.

The C-structure corresponding to an object of PyArrayIter_Type is
the PyArrayIterObject. The PyArrayIterObject is used to
keep track of a pointer into an N-dimensional array. It contains associated
information used to quickly march through the array. The pointer can
be adjusted in three basic ways: 1) advance to the “next” position in
the array in a C-style contiguous fashion, 2) advance to an arbitrary
N-dimensional coordinate in the array, and 3) advance to an arbitrary
one-dimensional index into the array. The members of the
PyArrayIterObject structure are used in these
calculations. Iterator objects keep their own dimension and strides
information about an array. This can be adjusted as needed for
“broadcasting,” or to loop over only specific dimensions.

This flag is true if the underlying array is
NPY_ARRAY_C_CONTIGUOUS. It is used to simplify
calculations when possible.

How to use an array iterator on a C-level is explained more fully in
later sections. Typically, you do not need to concern yourself with
the internal structure of the iterator object, and merely interact
with it through the use of the macros PyArray_ITER_NEXT (it),
PyArray_ITER_GOTO (it, dest), or PyArray_ITER_GOTO1D (it,
index). All of these macros require the argument it to be a
PyArrayIterObject*.

This type provides an iterator that encapsulates the concept of
broadcasting. It allows arrays to be broadcast together
so that the loop progresses in C-style contiguous fashion over the
broadcasted array. The corresponding C-structure is the
PyArrayMultiIterObject whose memory layout must begin any
object, obj, passed in to the PyArray_Broadcast (obj)
function. Broadcasting is performed by adjusting array iterators so
that each iterator represents the broadcasted shape and size, but
has its strides adjusted so that the correct element from the array
is used at each iteration.

When the flags attribute is retrieved from Python, a special
builtin object of this type is constructed. This special type makes
it easier to work with the different flags by accessing them as
attributes or by accessing them as if the object were a dictionary
with the flag names as entries.

There is a Python type for each of the different built-in data types
that can be present in the array Most of these are simple wrappers
around the corresponding data type in C. The C-names for these types
are Py{TYPE}ArrType_Type where {TYPE} can be

These type names are part of the C-API and can therefore be created in
extension C-code. There is also a PyIntpArrType_Type and a
PyUIntpArrType_Type that are simple substitutes for one of the
integer types that can hold a pointer on the platform. The structure
of these scalar objects is not exposed to C-code. The function
PyArray_ScalarAsCtype (..) can be used to extract the C-type value
from the array scalar and the function PyArray_Scalar (...) can be
used to construct an array scalar from a C-value.

A few new C-structures were found to be useful in the development of
NumPy. These C-structures are used in at least one C-API call and are
therefore documented here. The main reason these structures were
defined is to make it easy to use the Python ParseTuple C-API to
convert from Python objects to a useful C-Object.

This is equivalent to the buffer object structure in Python up to
the ptr member. On 32-bit platforms (i.e. if NPY_SIZEOF_INT
== NPY_SIZEOF_INTP ) or in Python 2.5, the len member also
matches an equivalent member of the buffer object. It is useful to
represent a generic single- segment chunk of memory.

The PyArrayInterface structure is defined so that NumPy and
other extension modules can use the rapid array interface
protocol. The __array_struct__ method of an object that
supports the rapid array interface protocol should return a
PyCObject that contains a pointer to a PyArrayInterface
structure with the relevant details of the array. After the new
array is created, the attribute should be DECREF‘d which will
free the PyArrayInterface structure. Remember to INCREF the
object (whose __array_struct__ attribute was retrieved) and
point the base member of the new PyArrayObject to this same
object. In this way the memory for the array will be managed
correctly.

A Python object describing the data-type in more detail (same
as the descr key in __array_interface__). This can be
NULL if typekind and itemsize provide enough
information. This field is also ignored unless
ARR_HAS_DESCR flag is on in flags.

Internally, the code uses some additional Python objects primarily for
memory management. These types are not accessible directly from
Python, and are not exposed to the C-API. They are included here only
for completeness and assistance in understanding the code.

A loose wrapper for a C-structure that contains the information
needed for looping. This is useful if you are trying to understand
the ufunc looping code. The PyUFuncLoopObject is the associated
C-structure. It is defined in the ufuncobject.h header.

A loose wrapper for the C-structure that contains the information
needed for reduce-like methods of ufuncs. This is useful if you are
trying to understand the reduce, accumulate, and reduce-at
code. The PyUFuncReduceObject is the associated C-structure. It
is defined in the ufuncobject.h header.

Advanced indexing is handled with this Python type. It is simply a
loose wrapper around the C-structure containing the variables
needed for advanced array indexing. The associated C-structure,
PyArrayMapIterObject, is useful if you are trying to
understand the advanced-index mapping code. It is defined in the
arrayobject.h header. This type is not exposed to Python and
could be replaced with a C-structure. As a Python type it takes
advantage of reference- counted memory management.