数据类型 API#

标准数组可以有 25 种不同的数据类型（并支持添加自定义类型）。所有这些数据类型都有一个枚举类型、一个枚举类型字符和一个对应的数组标量 Python 类型对象（按层次结构放置）。此外，还有标准 C 类型定义，以便更轻松地操作给定数据类型的元素。对于数值类型，还有位宽等效的 C 类型定义和命名类型编号，以便更容易选择所需的精度。

警告

C 代码中类型的名称更接近 C 命名约定。这些类型的 Python 名称遵循 Python 约定。因此，NPY_FLOAT 在 C 中表示 32 位浮点数，但 Python 中的 numpy.float64 对应 64 位双精度浮点数。位宽名称可在 Python 和 C 中使用，以提高清晰度。

枚举类型#

enum NPY_TYPES#

定义了一系列枚举类型，提供了 25 种基本数据类型以及一些有用的通用名称。当代码需要类型编号时，会请求这些枚举类型之一。所有类型都命名为 NPY_{NAME}

enumerator NPY_BOOL#: 布尔类型的枚举值，存储为一个字节。它只能设置为值 0 和 1。

enumerator NPY_BYTE#

enumerator NPY_INT8#: 8 位/1 字节有符号整数的枚举值。

enumerator NPY_SHORT#

enumerator NPY_INT16#: 16 位/2 字节有符号整数的枚举值。

enumerator NPY_INT#

enumerator NPY_INT32#: 32 位/4 字节有符号整数的枚举值。

enumerator NPY_LONG#: 等效于 NPY_INT 或 NPY_LONGLONG，具体取决于平台。

enumerator NPY_LONGLONG#

enumerator NPY_INT64#: 64 位/8 字节有符号整数的枚举值。

enumerator NPY_UBYTE#

enumerator NPY_UINT8#: 8 位/1 字节无符号整数的枚举值。

enumerator NPY_USHORT#

enumerator NPY_UINT16#: 16 位/2 字节无符号整数的枚举值。

enumerator NPY_UINT#

enumerator NPY_UINT32#: 32 位/4 字节无符号整数的枚举值。

enumerator NPY_ULONG#: 等效于 NPY_UINT 或 NPY_ULONGLONG，具体取决于平台。

enumerator NPY_ULONGLONG#

enumerator NPY_UINT64#: 64 位/8 字节无符号整数的枚举值。

enumerator NPY_HALF#

enumerator NPY_FLOAT16#: 16 位/2 字节 IEEE 754-2008 兼容浮点类型的枚举值。

enumerator NPY_FLOAT#

enumerator NPY_FLOAT32#: 32 位/4 字节 IEEE 754 兼容浮点类型的枚举值。

enumerator NPY_DOUBLE#

enumerator NPY_FLOAT64#: 64 位/8 字节 IEEE 754 兼容浮点类型的枚举值。

enumerator NPY_LONGDOUBLE#: 平台特定浮点类型的枚举值，其大小至少与 NPY_DOUBLE 相同，但在许多平台上会更大。

enumerator NPY_CFLOAT#

enumerator NPY_COMPLEX64#: 由两个 NPY_FLOAT 值组成的 64 位/8 字节复数类型的枚举值。

enumerator NPY_CDOUBLE#

enumerator NPY_COMPLEX128#: 由两个 NPY_DOUBLE 值组成的 128 位/16 字节复数类型的枚举值。

enumerator NPY_CLONGDOUBLE#: 平台特定复数浮点类型的枚举值，由两个 NPY_LONGDOUBLE 值组成。

enumerator NPY_DATETIME#: 存储日期或日期时间的数据类型的枚举值，精度基于可选的日期或时间单位。

enumerator NPY_TIMEDELTA#: 存储时间长度（以可选的日期或时间单位的整数表示）的数据类型的枚举值。

enumerator NPY_STRING#: 可选择大小的、以空字符填充的字节字符串的枚举值。在给定数组中，字符串具有固定的最大大小。

enumerator NPY_UNICODE#: 可选择大小的 UCS4 字符串的枚举值。在给定数组中，字符串具有固定的最大大小。

enumerator NPY_VSTRING#: UTF-8 可变宽度字符串的枚举值。请注意，此 dtype 存储一个引用数组，字符串数据存储在数组缓冲区之外。请使用 C API 处理 numpy 可变宽度静态字符串以访问每个数组条目中的字符串数据。

注意

此 DType 是新式的，不包含在 NPY_NTYPES_LEGACY 中。

enumerator NPY_OBJECT#: 任意 Python 对象的引用的枚举值。

enumerator NPY_VOID#: 主要用于存储结构体数据类型，但可以包含任意二进制数据。

上述类型的一些有用别名是

enumerator NPY_INTP#: Py_ssize_t 类型（如果已定义，则与 ssize_t 相同）的有符号整数的枚举值。这是所有索引数组使用的类型。

2.0 版本中的变更: 之前，这与 intptr_t 相同（与指针大小相同）。实际上，除了在非常特殊的平台上，这都是相同的。您可以使用 'p' 字符代码表示指针的含义。

enumerator NPY_UINTP#: 与 size_t 相同的无符号整数类型的枚举值。

2.0 版本中的变更: 之前，这与 uintptr_t 相同（与指针大小相同）。实际上，除了在非常特殊的平台上，这都是相同的。您可以使用 'P' 字符代码表示指针的含义。

enumerator NPY_MASK#: 用于掩码的类型枚举值，例如与 NPY_ITER_ARRAYMASK 迭代器标志一起使用。这等效于 NPY_UINT8。

enumerator NPY_DEFAULT_TYPE#: 未明确指定 dtype 时使用的默认类型，例如调用 np.zero(shape) 时。这等效于 NPY_DOUBLE。

其他有用的相关常量是

NPY_NTYPES_LEGACY#: 使用传统 DType 系统编写的内置 NumPy 类型的数量。新的 NumPy dtype 将使用新的 DType API 编写，并且可能无法与传统 DType 以相同方式运行。如果您想使用不同的代码路径处理传统 DType，或者如果您不想更新使用 NPY_NTYPES_LEGACY 且无法正确处理新 DType 的代码，请使用此宏。

注意

新添加的 DType，如 NPY_VSTRING，将不计入 NPY_NTYPES_LEGACY。

NPY_NOTYPE#: 一个保证不是有效类型枚举编号的信号值。

NPY_USERDEF#: 用于传统自定义数据类型的类型编号的起始值。新式用户 DType 目前未分配类型编号。

注意

用户 dtype 的总数限制在 NPY_VSTRING 以下。更高的编号保留用于未来的新式 DType 用途。

表示某些类型的各种字符代码也是枚举列表的一部分。对类型字符的引用（如果需要的话）应始终使用这些枚举。其形式为 NPY_{NAME}LTR，其中 {NAME} 可以是

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

后一组 {NAME}s 对应于数组接口类型字符串规范中使用的字母。

宏定义#

整数的最大值和最小值#

NPY_MAX_INT{bits}, NPY_MAX_UINT{bits}, NPY_MIN_INT{bits}: 这些定义适用于 {bits} = 8, 16, 32, 64, 128, 和 256，并提供对应（无符号）整数类型的最大（最小）值。注意：实际的整数类型可能并非在所有平台上都可用（例如 128 位和 256 位整数很少见）。
NPY_MIN_{type}: 这定义适用于 {type} = BYTE, SHORT, INT, LONG, LONGLONG, INTP
NPY_MAX_{type}: 这定义适用于所有已定义的 {type} = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, INTP, UINTP

数据类型中的位数#

所有 NPY_SIZEOF_{CTYPE} 常量都有对应的 NPY_BITSOF_{CTYPE} 常量定义。NPY_BITSOF_{CTYPE} 常量提供数据类型中的位数。具体来说，可用的 {CTYPE}s 是

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

枚举类型编号的位宽引用#

所有数值数据类型（整数、浮点和复数）都有被定义为特定枚举类型编号的常量。位宽类型具体引用哪个枚举类型取决于平台。特别是，可用的常量是 PyArray_{NAME}{BITS}，其中 {NAME} 是 INT, UINT, FLOAT, COMPLEX，而 {BITS} 可以是 8, 16, 32, 64, 80, 96, 128, 160, 192, 256, 和 512。显然，并非所有平台上所有类型的数值类型都支持所有位宽。通常，8 位、16 位、32 位、64 位整数；32 位、64 位浮点数；以及 64 位、128 位复数类型是可用的。

C 类型名称#

每种数值数据类型和布尔数据类型都有标准变量类型。其中一些在 C 规范中已经可用。您可以使用这些类型在扩展代码中创建变量。

布尔型#

type npy_bool#: 无符号字符；常量 NPY_FALSE 和 NPY_TRUE 也已定义。

(无)符号整数#

整数的无符号版本可以通过在整数名称前加上“u”来定义。

type npy_byte#: 字符

type npy_ubyte#: 无符号字符

type npy_short#: 短整型

type npy_ushort#: 无符号短整型

type npy_int#: 整型

type npy_uint#: 无符号整型

type npy_int16#: 16 位整数

type npy_uint16#: 16 位无符号整数

type npy_int32#: 32 位整数

type npy_uint32#: 32 位无符号整数

type npy_int64#: 64 位整数

type npy_uint64#: 64 位无符号整数

type npy_long#: 长整型

type npy_ulong#: 无符号长整型

type npy_longlong#: 长长整型

type npy_ulonglong#: 无符号长长整型

type npy_intp#: Py_ssize_t（一个与 C size_t 大小相同的有符号整数）。这是用于长度或索引的正确整数。实际上，这通常是指针的大小，但不能保证。

注意

在 NumPy 2.0 之前，这与 Py_intptr_t 相同。虽然更匹配，但这与实际使用不符。在 Python 端，我们仍然支持 np.dtype('p') 来获取与存储指针兼容的 dtype，而 n 是 ssize_t 的正确字符。

type npy_uintp#: C size_t/Py_size_t。

(复数)浮点数#

type npy_half#: 16 位浮点数

type npy_float#: 32 位浮点数

type npy_cfloat#: 32 位复数浮点数

type npy_double#: 64 位双精度浮点数

type npy_cdouble#: 64 位复数双精度浮点数

type npy_longdouble#: 长双精度浮点数

type npy_clongdouble#: 长复数双精度浮点数

复数类型是包含 .real 和 .imag 成员（按此顺序）的结构体。

位宽名称#

还有针对特定位宽的有符号整数、无符号整数、浮点数和复数浮点数的类型定义。可用的类型名称是

npy_int{bits}, npy_uint{bits}, npy_float{bits}, 和 npy_complex{bits}

其中 {bits} 是类型中的位数，对于整数类型可以是 8, 16, 32, 64, 128, 和 256；对于浮点类型可以是 16, 32, 64, 80, 96, 128, 和 256；对于复数值类型可以是 32, 64, 128, 160, 192, 和 512。哪些位宽可用取决于平台。加粗的位宽通常在所有平台上都可用。

时间和时间差#

type npy_datetime#: 日期或日期时间（npy_int64 的别名）

type npy_timedelta#: 时间长度（npy_int64 的别名）

Printf 格式化#

为了便于打印，以下字符串被定义为 printf 和相关命令中的正确格式说明符。

NPY_LONGLONG_FMT#

NPY_ULONGLONG_FMT#

NPY_INTP_FMT#

NPY_UINTP_FMT#

NPY_LONGDOUBLE_FMT#