Data type API #

The standard array can have 25 different data types (and has somesupport for adding your own types). These data types all have anenumerated type, an enumerated type-character, and a correspondingarray scalar Python type object (placed in a hierarchy). There arealso standard C typedefs to make it easier to manipulate elements ofthe given data type. For the numeric types, there are also bit-widthequivalent C typedefs and named typenumbers that make it easier toselect the precision desired.

Warning

The names for the types in c code follows c naming conventionsmore closely. The Python names for these types follow Pythonconventions. Thus,NPY_FLOAT picks up a 32-bit float inC, butnumpy.float64 in Python corresponds to a 64-bitdouble. The bit-width names can be used in both Python and C forclarity.

Enumerated types#

enumNPY_TYPES#

There is a list of enumerated types defined providing the basic 25data types plus some useful generic names. Whenever the code requiresa type number, one of these enumerated types is requested. The typesare all calledNPY_{NAME}:

enumeratorNPY_BOOL#: The enumeration value for the boolean type, stored as one byte.It may only be set to the values 0 and 1.

enumeratorNPY_BYTE#

enumeratorNPY_INT8#: The enumeration value for an 8-bit/1-byte signed integer.

enumeratorNPY_SHORT#

enumeratorNPY_INT16#: The enumeration value for a 16-bit/2-byte signed integer.

enumeratorNPY_INT#

enumeratorNPY_INT32#: The enumeration value for a 32-bit/4-byte signed integer.

enumeratorNPY_LONG#: Equivalent to either NPY_INT or NPY_LONGLONG, depending on theplatform.

enumeratorNPY_LONGLONG#

enumeratorNPY_INT64#: The enumeration value for a 64-bit/8-byte signed integer.

enumeratorNPY_UBYTE#

enumeratorNPY_UINT8#: The enumeration value for an 8-bit/1-byte unsigned integer.

enumeratorNPY_USHORT#

enumeratorNPY_UINT16#: The enumeration value for a 16-bit/2-byte unsigned integer.

enumeratorNPY_UINT#

enumeratorNPY_UINT32#: The enumeration value for a 32-bit/4-byte unsigned integer.

enumeratorNPY_ULONG#: Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on theplatform.

enumeratorNPY_ULONGLONG#

enumeratorNPY_UINT64#: The enumeration value for a 64-bit/8-byte unsigned integer.

enumeratorNPY_HALF#

enumeratorNPY_FLOAT16#: The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floatingpoint type.

enumeratorNPY_FLOAT#

enumeratorNPY_FLOAT32#: The enumeration value for a 32-bit/4-byte IEEE 754 compatible floatingpoint type.

enumeratorNPY_DOUBLE#

enumeratorNPY_FLOAT64#: The enumeration value for a 64-bit/8-byte IEEE 754 compatible floatingpoint type.

enumeratorNPY_LONGDOUBLE#: The enumeration value for a platform-specific floating point type which isat least as large as NPY_DOUBLE, but larger on many platforms.

enumeratorNPY_CFLOAT#

enumeratorNPY_COMPLEX64#: The enumeration value for a 64-bit/8-byte complex type made up oftwo NPY_FLOAT values.

enumeratorNPY_CDOUBLE#

enumeratorNPY_COMPLEX128#: The enumeration value for a 128-bit/16-byte complex type made up oftwo NPY_DOUBLE values.

enumeratorNPY_CLONGDOUBLE#: The enumeration value for a platform-specific complex floating pointtype which is made up of two NPY_LONGDOUBLE values.

enumeratorNPY_DATETIME#: The enumeration value for a data type which holds dates or datetimes witha precision based on selectable date or time units.

enumeratorNPY_TIMEDELTA#: The enumeration value for a data type which holds lengths of times inintegers of selectable date or time units.

enumeratorNPY_STRING#: The enumeration value for null-padded byte strings of a selectablesize. The strings have a fixed maximum size within a given array.

enumeratorNPY_UNICODE#: The enumeration value for UCS4 strings of a selectable size. Thestrings have a fixed maximum size within a given array.

enumeratorNPY_VSTRING#: The enumeration value for UTF-8 variable-width strings. Note that thisdtype holds an array of references, with string data stored outside ofthe array buffer. Use the C API for working with numpy variable-widthstatic strings to access the string data in each array entry.
Note
This DType is new-style and is not included inNPY_NTYPES_LEGACY.

enumeratorNPY_OBJECT#: The enumeration value for references to arbitrary Python objects.

enumeratorNPY_VOID#: Primarily used to hold struct dtypes, but can contain arbitrarybinary data.

Some useful aliases of the above types are

enumeratorNPY_INTP#: The enumeration value for a signed integer of typePy_ssize_t(same asssize_t if defined). This is the type used by allarrays of indices.
Changed in version 2.0:Previously, this was the same asintptr_t (same size as apointer). In practice, this is identical except on very nicheplatforms.You can use the'p' character code for the pointer meaning.

enumeratorNPY_UINTP#: The enumeration value for an unsigned integer type that is identicalto asize_t.
Changed in version 2.0:Previously, this was the same asuintptr_t (same size as apointer). In practice, this is identical except on very nicheplatforms.You can use the'P' character code for the pointer meaning.

enumeratorNPY_MASK#: The enumeration value of the type used for masks, such as withtheNPY_ITER_ARRAYMASK iterator flag. This is equivalenttoNPY_UINT8.

enumeratorNPY_DEFAULT_TYPE#: The default type to use when no dtype is explicitly specified, forexample when calling np.zero(shape). This is equivalent toNPY_DOUBLE.

Other useful related constants are

NPY_NTYPES_LEGACY#: The number of built-in NumPy types written using the legacy DTypesystem. New NumPy dtypes will be written using the new DType API and may notfunction in the same manner as legacy DTypes. Use this macro if you want tohandle legacy DTypes using different code paths or if you do not want toupdate code that usesNPY_NTYPES_LEGACY and does not work correctly with newDTypes.
Note
Newly added DTypes such asNPY_VSTRING will not be countedinNPY_NTYPES_LEGACY.

NPY_NOTYPE#: A signal value guaranteed not to be a valid type enumeration number.

NPY_USERDEF#: The start of type numbers used for legacy Custom Data types.New-style user DTypes currently are currentlynot assigned a type-number.
Note
The total number of user dtypes is limited to belowNPY_VSTRING.Higher numbers are reserved to future new-style DType use.

The various character codes indicating certain types are also part ofan enumerated list. References to type characters (should they beneeded at all) should always use these enumerations. The form of themisNPY_{NAME}LTR where{NAME} can be

BOOL,BYTE,UBYTE,SHORT,USHORT,INT,UINT,LONG,ULONG,LONGLONG,ULONGLONG,HALF,FLOAT,DOUBLE,LONGDOUBLE,CFLOAT,CDOUBLE,CLONGDOUBLE,DATETIME,TIMEDELTA,OBJECT,STRING,UNICODE,VSTRING,VOID
INTP,UINTP
GENBOOL,SIGNED,UNSIGNED,FLOATING,COMPLEX

The latter group of{NAME}s corresponds to letters used in the arrayinterface typestring specification.

Defines#

Max and min values for integers#

NPY_MAX_INT{bits},NPY_MAX_UINT{bits},NPY_MIN_INT{bits}: These are defined for{bits} = 8, 16, 32, 64, 128, and 256 and providethe maximum (minimum) value of the corresponding (unsigned) integertype. Note: the actual integer type may not be available on allplatforms (i.e. 128-bit and 256-bit integers are rare).
NPY_MIN_{type}: This is defined for{type} =BYTE,SHORT,INT,LONG,LONGLONG,INTP
NPY_MAX_{type}: This is defined for all defined for{type} =BYTE,UBYTE,SHORT,USHORT,INT,UINT,LONG,ULONG,LONGLONG,ULONGLONG,INTP,UINTP

Number of bits in data types#

AllNPY_SIZEOF_{CTYPE} constants have correspondingNPY_BITSOF_{CTYPE} constants defined. TheNPY_BITSOF_{CTYPE}constants provide the number of bits in the data type. Specifically,the available{CTYPE}s are

BOOL,CHAR,SHORT,INT,LONG,LONGLONG,FLOAT,DOUBLE,LONGDOUBLE

Bit-width references to enumerated typenums#

All of the numeric data types (integer, floating point, and complex)have constants that are defined to be a specific enumerated typenumber. Exactly which enumerated type a bit-width type refers to isplatform dependent. In particular, the constants available arePyArray_{NAME}{BITS} where{NAME} isINT,UINT,FLOAT,COMPLEX and{BITS} can be 8, 16, 32, 64, 80, 96, 128,160, 192, 256, and 512. Obviously not all bit-widths are available onall platforms for all the kinds of numeric types. Commonly 8-, 16-,32-, 64-bit integers; 32-, 64-bit floats; and 64-, 128-bit complextypes are available.

Further integer aliases#

The constantsNPY_INTP andNPY_UINTP refer to anPy_ssize_tandsize_t.Although in practice normally true, these types are strictly speaking notpointer sized and the character codes'p' and'P' can be used forpointer sized integers.(Before NumPy 2,intp was pointer size, but this almost never matchedthe actual use, which is the reason for the name.)

Since NumPy 2,NPY_DEFAULT_INT is additionally defined.The value of the macro is runtime dependent: Since NumPy 2, it maps toNPY_INTP while on earlier versions it maps toNPY_LONG.

C-type names#

There are standard variable types for each of the numeric data typesand the bool data type. Some of these are already available in theC-specification. You can create variables in extension code with thesetypes.

Boolean#

typenpy_bool#: unsigned char; The constantsNPY_FALSE andNPY_TRUE are also defined.

(Un)Signed Integer#

Unsigned versions of the integers can be defined by prepending a ‘u’to the front of the integer name.

typenpy_byte#: char

typenpy_ubyte#: unsigned char

typenpy_short#: short

typenpy_ushort#: unsigned short

typenpy_int#: int

typenpy_uint#: unsigned int

typenpy_int16#: 16-bit integer

typenpy_uint16#: 16-bit unsigned integer

typenpy_int32#: 32-bit integer

typenpy_uint32#: 32-bit unsigned integer

typenpy_int64#: 64-bit integer

typenpy_uint64#: 64-bit unsigned integer

typenpy_long#: long int

typenpy_ulong#: unsigned long int

typenpy_longlong#: long long int

typenpy_ulonglong#: unsigned long long int

typenpy_intp#: Py_ssize_t (a signed integer with the same size as the Csize_t).This is the correct integer for lengths or indexing. In practice this isnormally the size of a pointer, but this is not guaranteed.
Note
Before NumPy 2.0, this was the same asPy_intptr_t.While a better match, this did not match actual usage in practice.On the Python side, we still supportnp.dtype('p') to fetch a dtypecompatible with storing pointers, whilen is the correct characterfor thessize_t.

typenpy_uintp#: The Csize_t/Py_size_t.

(Complex) Floating point#

typenpy_half#: 16-bit float

typenpy_float#: 32-bit float

typenpy_cfloat#: 32-bit complex float

typenpy_double#: 64-bit double

typenpy_cdouble#: 64-bit complex double

typenpy_longdouble#: long double

typenpy_clongdouble#: long complex double

complex types are structures with.real and.imag members (inthat order).

Bit-width names#

There are also typedefs for signed integers, unsigned integers,floating point, and complex floating point types of specific bit-widths. The available type names are

npy_int{bits},npy_uint{bits},npy_float{bits},andnpy_complex{bits}

where{bits} is the number of bits in the type and can be8,16,32,64, 128, and 256 for integer types; 16,32,64, 80, 96, 128, and 256 for floating-point types; and 32,64,128, 160, 192, and 512 for complex-valued types. Whichbit-widths are available is platform dependent. The bolded bit-widthsare usually available on all platforms.

Time and timedelta#

typenpy_datetime#: date or datetime (alias ofnpy_int64)

typenpy_timedelta#: length of time (alias ofnpy_int64)

Printf formatting#

For help in printing, the following strings are defined as the correctformat specifier in printf and related commands.

NPY_LONGLONG_FMT#

NPY_ULONGLONG_FMT#

NPY_INTP_FMT#

NPY_UINTP_FMT#

NPY_LONGDOUBLE_FMT#

On this page

Movatterモバイル変換

Data type API#