numpy.dtype

class numpy.dtype(dtype, align=False, copy=False[, metadata])

Create a data type object.

A numpy array is homogeneous, and contains elements described by a dtype object. A dtype object can be constructed from different combinations of fundamental numeric types.

Parameters:

dtype – Object to be converted to a data type object.
align (bool, optional) – Add padding to the fields to match what a C compiler would output for a similar C-struct. Can be True only if obj is a dictionary or a comma-separated string. If a struct dtype is being created, this also sets a sticky alignment flag isalignedstruct.
copy (bool, optional) – Make a new copy of the data-type object. If False, the result may just be a reference to a built-in data-type object.
metadata (dict, optional) – An optional dictionary with dtype metadata.

See also

result_type

Examples

Using array-scalar type:

>>> np.dtype(np.int16)
dtype('int16')

Structured type, one field name ‘f1’, containing int16:

>>> np.dtype([('f1', np.int16)])
dtype([('f1', '<i2')])

Structured type, one field named ‘f1’, in itself containing a structured type with one field:

>>> np.dtype([('f1', [('f1', np.int16)])])
dtype([('f1', [('f1', '<i2')])])

Structured type, two fields: the first field contains an unsigned int, the second an int32:

>>> np.dtype([('f1', np.uint64), ('f2', np.int32)])
dtype([('f1', '<u8'), ('f2', '<i4')])

Using array-protocol type strings:

>>> np.dtype([('a','f8'),('b','S10')])
dtype([('a', '<f8'), ('b', 'S10')])

Using comma-separated field formats. The shape is (2,3):

>>> np.dtype("i4, (2,3)f8")
dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])

Using tuples. int is a fixed type, 3 the field’s shape. void is a flexible type, here of size 10:

>>> np.dtype([('hello',(np.int64,3)),('world',np.void,10)])
dtype([('hello', '<i8', (3,)), ('world', 'V10')])

Subdivide int16 into 2 int8’s, called x and y. 0 and 1 are the offsets in bytes:

>>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)}))
dtype((numpy.int16, [('x', 'i1'), ('y', 'i1')]))

Using dictionaries. Two fields named ‘gender’ and ‘age’:

>>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]})
dtype([('gender', 'S1'), ('age', 'u1')])

Offsets in bytes, here 0 and 25:

>>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)})
dtype([('surname', 'S25'), ('age', 'u1')])

Attributes:

`alignment`	The required alignment (bytes) of this data-type according to the compiler.
`base`	Returns dtype for the base element of the subarrays, regardless of their dimension or shape.
`byteorder`	A character indicating the byte-order of this data-type object.
`char`	A unique character code for each of the 21 different built-in types.
`descr`	__array_interface__ description of the data-type.
`fields`	Dictionary of named fields defined for this data type, or `None`.
`flags`	Bit-flags describing how this data type is to be interpreted.
`hasobject`	Boolean indicating whether this dtype contains any reference-counted objects in any fields or sub-dtypes.
`isalignedstruct`	Boolean indicating whether the dtype is a struct which maintains field alignment.
`isbuiltin`	Integer indicating how this dtype relates to the built-in dtypes.
`isnative`	Boolean indicating whether the byte order of this dtype is native to the platform.
`itemsize`	The element size of this data-type object.
`kind`	A character code (one of 'biufcmMOSUV') identifying the general kind of data.
`metadata`	Either `None` or a readonly dictionary of metadata (mappingproxy).
`name`	A bit-width name for this data-type.
`names`	Ordered list of field names, or `None` if there are no fields.
`ndim`	Number of dimensions of the sub-array if this data type describes a sub-array, and `0` otherwise.
`num`	A unique number for each of the 21 different built-in types.
`shape`	Shape tuple of the sub-array if this data type describes a sub-array, and `()` otherwise.
`str`	The array-protocol typestring of this data-type object.
`subdtype`	Tuple `(item_dtype, shape)` if this dtype describes a sub-array, and None otherwise.
`type`

Attributes

dtype.base

Returns dtype for the base element of the subarrays, regardless of their dimension or shape.

See also

dtype.subdtype

Examples

>>> x = numpy.dtype('8f')
>>> x.base
dtype('float32')

>>> x =  numpy.dtype('i2')
>>> x.base
dtype('int16')

dtype.descr

__array_interface__ description of the data-type.

The format is that required by the ‘descr’ key in the __array_interface__ attribute.

Warning: This attribute exists specifically for __array_interface__, and passing it directly to np.dtype will not accurately reconstruct some dtypes (e.g., scalar and subarray dtypes).

Examples

>>> x = np.dtype(float)
>>> x.descr
[('', '<f8')]

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> dt.descr
[('name', '<U16'), ('grades', '<f8', (2,))]

dtype.fields

Dictionary of named fields defined for this data type, or None.

The dictionary is indexed by keys that are the names of the fields. Each entry in the dictionary is a tuple fully describing the field:

(dtype, offset[, title])

Offset is limited to C int, which is signed and usually 32 bits. If present, the optional title can be any object (if it is a string or unicode then it will also be a key in the fields dictionary, otherwise it’s meta-data). Notice also that the first two elements of the tuple can be passed directly as arguments to the ndarray.getfield and ndarray.setfield methods.

See also

ndarray.getfield, ndarray.setfield

Examples

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> print(dt.fields)
{'grades': (dtype(('float64',(2,))), 16), 'name': (dtype('|S16'), 0)}

dtype.hasobject

Boolean indicating whether this dtype contains any reference-counted objects in any fields or sub-dtypes.

Recall that what is actually in the ndarray memory representing the Python object is the memory address of that object (a pointer). Special handling may be required, and this attribute is useful for distinguishing data types that may contain arbitrary Python objects and data-types that won’t.

dtype.isalignedstruct: Boolean indicating whether the dtype is a struct which maintains field alignment. This flag is sticky, so when combining multiple structs together, it is preserved and produces new dtypes which are also aligned.

dtype.isbuiltin

Integer indicating how this dtype relates to the built-in dtypes.

Read-only.

0	if this is a structured array type, with fields
1	if this is a dtype compiled into numpy (such as ints, floats etc)
2	if the dtype is for a user-defined numpy type A user-defined type uses the numpy C-API machinery to extend numpy to handle a new array type. See user.user-defined-data-types in the NumPy manual.

Examples

>>> dt = np.dtype('i2')
>>> dt.isbuiltin
1
>>> dt = np.dtype('f8')
>>> dt.isbuiltin
1
>>> dt = np.dtype([('field1', 'f8')])
>>> dt.isbuiltin
0

dtype.isnative: Boolean indicating whether the byte order of this dtype is native to the platform.

dtype.metadata

Either None or a readonly dictionary of metadata (mappingproxy).

The metadata field can be set using any dictionary at data-type creation. NumPy currently has no uniform approach to propagating metadata; although some array operations preserve it, there is no guarantee that others will.

Warning

Although used in certain projects, this feature was long undocumented and is not well supported. Some aspects of metadata propagation are expected to change in the future.

Examples

>>> dt = np.dtype(float, metadata={"key": "value"})
>>> dt.metadata["key"]
'value'
>>> arr = np.array([1, 2, 3], dtype=dt)
>>> arr.dtype.metadata
mappingproxy({'key': 'value'})

Adding arrays with identical datatypes currently preserves the metadata:

>>> (arr + arr).dtype.metadata
mappingproxy({'key': 'value'})

But if the arrays have different dtype metadata, the metadata may be dropped:

>>> dt2 = np.dtype(float, metadata={"key2": "value2"})
>>> arr2 = np.array([3, 2, 1], dtype=dt2)
>>> (arr + arr2).dtype.metadata is None
True  # The metadata field is cleared so None is returned

dtype.name

A bit-width name for this data-type.

Un-sized flexible data-type objects do not have this attribute.

Examples

>>> x = np.dtype(float)
>>> x.name
'float64'
>>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])
>>> x.name
'void640'

dtype.names

Ordered list of field names, or None if there are no fields.

The names are ordered according to increasing byte offset. This can be used, for example, to walk through all of the named fields in offset order.

Examples

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> dt.names
('name', 'grades')

dtype.ndim

Number of dimensions of the sub-array if this data type describes a sub-array, and 0 otherwise.

New in version 1.13.0.

Examples

>>> x = np.dtype(float)
>>> x.ndim
0

>>> x = np.dtype((float, 8))
>>> x.ndim
1

>>> x = np.dtype(('i4', (3, 4)))
>>> x.ndim
2

dtype.shape

Shape tuple of the sub-array if this data type describes a sub-array, and () otherwise.

Examples

>>> dt = np.dtype(('i4', 4))
>>> dt.shape
(4,)

>>> dt = np.dtype(('i4', (2, 3)))
>>> dt.shape
(2, 3)

dtype.str: The array-protocol typestring of this data-type object.

dtype.subdtype

Tuple (item_dtype, shape) if this dtype describes a sub-array, and None otherwise.

The shape is the fixed shape of the sub-array described by this data type, and item_dtype the data type of the array.

If a field whose dtype object has this attribute is retrieved, then the extra dimensions implied by shape are tacked on to the end of the retrieved array.

See also

dtype.base

Examples

>>> x = numpy.dtype('8f')
>>> x.subdtype
(dtype('float32'), (8,))

>>> x =  numpy.dtype('i2')
>>> x.subdtype
>>>