数据类型 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#
主要用于保存结构体 dtype，但可以包含任意二进制数据。
上述类型的一些有用别名是
-
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。
-
enumerator NPY_BOOL#
其他有用的相关常量包括：
-
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、INTPNPY_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
位宽引用到枚举 typenums#
所有数值数据类型（整数、浮点数和复数）都具有定义为特定枚举类型编号的常量。位宽类型究竟指的是哪个枚举类型取决于平台。特别是，可用的常量为 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 位复数类型是可用的。
其他整数别名#
常量 NPY_INTP 和 NPY_UINTP 分别指代 Py_ssize_t 和 size_t。虽然在实践中通常为真，但严格来说，这些类型并非指针大小，字符代码 'p' 和 'P' 可用于指针大小的整数。（在 NumPy 2 之前，intp 是指针大小，但这几乎从未与实际使用相匹配，这就是名称的原因。）
从 NumPy 2 开始，还定义了 NPY_DEFAULT_INT。宏的值取决于运行时：从 NumPy 2 开始，它映射到 NPY_INTP，而在早期版本中，它映射到 NPY_LONG。
C 类型名称#
每种数值数据类型和布尔数据类型都有标准的变量类型。其中一些已经在 C 规范中可用。您可以在扩展代码中使用这些类型创建变量。
布尔值#
（无）符号整数#
可以通过在整数名称前面添加“u”来定义整数的无符号版本。
-
type npy_byte#
char
-
type npy_ubyte#
unsigned char
-
type npy_short#
short
-
type npy_ushort#
unsigned short
-
type npy_int#
int
-
type npy_uint#
unsigned int
-
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#
long int
-
type npy_ulong#
unsigned long int
-
type npy_longlong#
long long int
-
type npy_ulonglong#
unsigned long long int
-
type npy_intp#
Py_ssize_t（一个与 Csize_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#
long double
-
type npy_clongdouble#
long complex double
复数类型是具有 .real 和 .imag 成员（按此顺序）的结构。
位宽名称#
还存在用于特定位宽的带符号整数、无符号整数、浮点数和复数浮点数类型的 typedef。可用的类型名称为：
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。哪些位宽可用取决于平台。粗体位宽通常在所有平台上都可用。
时间和时间增量#
Printf 格式化#
为了帮助打印，以下字符串被定义为 printf 和相关命令中正确的格式说明符。
-
NPY_LONGLONG_FMT#
-
NPY_ULONGLONG_FMT#
-
NPY_INTP_FMT#
-
NPY_UINTP_FMT#
-
NPY_LONGDOUBLE_FMT#