标量

Python 只定义了一种特定数据类型（只有一种整数类型,一种浮点类型等）.这在不需要关心数据在计算机中所有表示方式的应用中很方便.然而,对于科学计算,通常需要更多的控制.

在NumPy中,有24种新的基本Python类型用于描述不同类型的标量.这些类型描述符主要基于CPython所用C语言中可用的类型,并包含几种与Python类型兼容的附加类型.

数组标量具有与 ndarrays 相同的属性和方法.[#]_ 这允许人们将数组的项部分地视为数组来处理,从而平滑了在混合标量和数组操作时产生的粗糙边缘.

数组标量存在于数据类型的层次结构中（见下图）.它们可以使用层次结构来检测:例如,``isinstance(val, np.generic)`` 将返回 True 如果 val 是一个数组标量对象.或者,可以使用数据类型层次结构中的其他成员来确定存在哪种类型的数组标量.因此,例如 isinstance(val, np.complexfloating) 将返回 True 如果 val 是一个复数值类型,而 isinstance(val, np.flexible) 将返回 true 如果 val 是其中一个可变项大小数组类型（str_、bytes_、void）.

图: 表示数组数据类型的类型对象的层次结构.未显示的是用于索引的两个整数类型 intp 和 :class:`uintp`（自 NumPy 2 以来与默认整数相同）.

[1]

然而,数组标量是不可变的,因此没有任何数组标量属性是可设置的.

内置标量类型

内置的标量类型如下所示.C语言风格的名称与字符代码相关联,这些字符代码在其描述中显示.然而,不鼓励使用字符代码.

一些标量类型本质上等同于基本的Python类型,因此它们不仅继承自通用的数组标量类型,还继承自这些基本类型:

数组标量类型	相关的 Python 类型	继承?
int_	int	仅限 Python 2
double	float	是的
cdouble	complex	是的
bytes_	bytes	是的
str_	str	是的
bool_	bool	不
datetime64	datetime.datetime	不
timedelta64	datetime.timedelta	不

The bool_ 数据类型与 Python 的 bool 非常相似,但不继承自它,因为 Python 的 bool 不允许被继承,并且在 C 级别上,实际的 bool 数据大小与 Python 布尔标量不同.

警告

int_ 类型在 Python 3 下**不**继承自 int 内置类型,因为 int 类型不再是固定宽度的整数类型.

小技巧

NumPy 中的默认数据类型是 double.

class numpy.generic

numpy 标量类型的基类.

这是大多数（所有?）numpy 标量类型派生的类.为了保持一致性,它暴露了与 ndarray 相同的 API,尽管许多相关属性要么是”只读”,要么完全不相关.这是强烈建议用户从中派生自定义标量类型的类.

class numpy.number

所有数值标量类型的抽象基类.

整数类型

class numpy.integer

所有整数标量类型的抽象基类.

备注

numpy 整数类型反映了 C 整数的行为,因此可能会受到 溢出错误 的影响.

有符号整数类型

class numpy.signedinteger

所有有符号整数标量类型的抽象基类.

class numpy.byte

有符号整数类型,与C char 兼容.

字符代码:

'b'

规范名称:

numpy.byte

此平台上的别名（Darwin arm64）:

numpy.int8: 8位有符号整数（-128 到 127）.

class numpy.short

有符号整数类型,与C语言的 short 兼容.

字符代码:

'h'

规范名称:

numpy.short

此平台上的别名（Darwin arm64）:

numpy.int16: 16位有符号整数（-32_768 到 32_767）.

class numpy.intc

有符号整数类型,与 C int 兼容.

字符代码:

'i'

规范名称:

numpy.intc

此平台上的别名（Darwin arm64）:

numpy.int32: 32位有符号整数（-2_147_483_648 到 2_147_483_647）.

class numpy.int_

默认的有符号整数类型,在64位系统上是64位,在32位系统上是32位.

字符代码:

'l'

规范名称:

numpy.int_

此平台上的别名（Darwin arm64）:

numpy.int64: 64位有符号整数（-9_223_372_036_854_775_808 到 9_223_372_036_854_775_807）.

此平台上的别名（Darwin arm64）:

numpy.intp: 足够大的带符号整数以适应指针,与C intptr_t 兼容.

numpy.long

int_ 的别名

class numpy.longlong

有符号整数类型,与C long long 兼容.

字符代码:

'q'

无符号整数类型

class numpy.unsignedinteger

所有无符号整数标量类型的抽象基类.

class numpy.ubyte

无符号整数类型,与C语言的 unsigned char 兼容.

字符代码:

'B'

规范名称:

numpy.ubyte

此平台上的别名（Darwin arm64）:

numpy.uint8:8位无符号整数（0 到 255）.

class numpy.ushort

无符号整数类型,与C语言的 unsigned short 兼容.

字符代码:

'H'

规范名称:

numpy.ushort

此平台上的别名（Darwin arm64）:

numpy.uint16:16位无符号整数（0 到 65_535）.

class numpy.uintc

无符号整数类型,与C语言的 unsigned int 兼容.

字符代码:

'I'

规范名称:

numpy.uintc

此平台上的别名（Darwin arm64）:

numpy.uint32: 32位无符号整数（0 到 4_294_967_295）.

class numpy.uint

无符号有符号整数类型,在64位系统上是64位,在32位系统上是32位.

字符代码:

'L'

规范名称:

numpy.uint

此平台上的别名（Darwin arm64）:

numpy.uint64: 64位无符号整数（0 到 18_446_744_073_709_551_615）.

此平台上的别名（Darwin arm64）:

numpy.uintp:足够容纳指针的无符号整数,与 C 语言的 uintptr_t 兼容.

numpy.ulong

uint 的别名

class numpy.ulonglong

有符号整数类型,与C语言的 unsigned long long 兼容.

字符代码:

'Q'

不精确类型

class numpy.inexact

所有数值标量类型的抽象基类,其范围内的值可能具有（潜在的）不精确表示,例如浮点数.

备注

不精确的标量使用最少的十进制数字打印,这些数字需要通过明智的舍入来区分其值与其他相同数据类型的值.请参阅 format_float_positional 和 format_float_scientific 的 unique 参数.

这意味着具有相同二进制值但数据类型精度不同的变量可能显示不同:

>>> import numpy as np

>>> f16 = np.float16("0.1")
>>> f32 = np.float32(f16)
>>> f64 = np.float64(f32)
>>> f16 == f32 == f64
True
>>> f16, f32, f64
(0.1, 0.099975586, 0.0999755859375)

注意,这些浮点数没有一个持有确切的值 \(\frac{1}{10}\);``f16`` 打印为 0.1 因为它尽可能接近这个值,而其他类型则不然,因为它们有更多的精度,因此有更接近的值.

相反地,精度不同的浮点标量尽管打印出来相同,但可能比较结果是不相等的:

>>> f16 = np.float16("0.1")
>>> f32 = np.float32("0.1")
>>> f64 = np.float64("0.1")
>>> f16 == f32 == f64
False
>>> f16, f32, f64
(0.1, 0.1, 0.1)

浮点类型

class numpy.floating

所有浮点标量类型的抽象基类.

class numpy.half

半精度浮点数类型.

字符代码:

'e'

规范名称:

numpy.half

此平台上的别名（Darwin arm64）:

numpy.float16:16位精度浮点数类型:符号位,5位指数,10位尾数.

class numpy.single

单精度浮点数类型,与C float 兼容.

字符代码:

'f'

规范名称:

numpy.single

此平台上的别名（Darwin arm64）:

numpy.float32:32位精度浮点数类型:符号位,8位指数,23位尾数.

class numpy.double(x=0, /)

双精度浮点数类型,与 Python float 和 C double 兼容.

字符代码:

'd'

规范名称:

numpy.double

此平台上的别名（Darwin arm64）:

numpy.float64:64位精度浮点数类型:符号位,11位指数,52位尾数.

class numpy.longdouble

扩展精度浮点数类型,与 C long double 兼容,但不一定是 IEEE 754 四倍精度.

字符代码:

'g'

复杂浮点类型

class numpy.complexfloating

所有由浮点数组成的复数标量类型的抽象基类.

class numpy.csingle

由两个单精度浮点数组成的复数类型.

字符代码:

'F'

规范名称:

numpy.csingle

此平台上的别名（Darwin arm64）:

numpy.complex64:由两个32位精度浮点数组成的复数类型.

class numpy.cdouble(real=0, imag=0)

由两个双精度浮点数组成的复数类型,与 Python complex 兼容.

字符代码:

'D'

规范名称:

numpy.cdouble

此平台上的别名（Darwin arm64）:

numpy.complex128:由两个64位精度浮点数组成的复数类型.

class numpy.clongdouble

由两个扩展精度浮点数组成的复数类型.

字符代码:

'G'

其他类型

numpy.bool_

bool 的别名

class numpy.bool

布尔类型（True 或 False）,存储为一个字节.

警告

bool 类型不是 int_ 类型的子类（bool 甚至不是数字类型）.这与 Python 默认将 bool 实现为 int 的子类不同.

字符代码:

'?'

class numpy.datetime64

如果从64位整数创建,它表示从 1970-01-01T00:00:00 开始的偏移量.如果从字符串创建,字符串可以是ISO 8601日期或日期时间格式.

当解析一个字符串以创建一个 datetime 对象时,如果字符串包含尾随的时区（’Z’ 或时区偏移）,时区将被丢弃并给出用户警告.

Datetime64 对象应被视为 UTC 时间,因此具有 +0000 的偏移量.

>>> np.datetime64(10, 'Y')
np.datetime64('1980')
>>> np.datetime64('1980', 'Y')
np.datetime64('1980')
>>> np.datetime64(10, 'D')
np.datetime64('1970-01-11')

更多信息请参见 日期时间和时间差.

字符代码:

'M'

class numpy.timedelta64

一个存储为64位整数的timedelta.

更多信息请参见 日期时间和时间差.

字符代码:

'm'

class numpy.object_

任何 Python 对象.

字符代码:

'O'

备注

对象数组中实际存储的数据（即,具有 dtype object_ 的数组）是对 Python 对象的引用,而不是对象本身.因此,对象数组的行为更像是一般的 Python 列表,这意味着它们的内容不需要是相同的 Python 类型.

对象类型也是特殊的,因为包含 object_ 项的数组在访问项时不会返回 object_ 对象,而是返回数组项引用的实际对象.

以下数据类型是 灵活的:它们没有预定义的大小,它们描述的数据在不同的数组中可以有不同的长度.（在字符代码中,``#`` 是一个表示数据类型由多少个元素组成的整数.）

class numpy.flexible

所有没有预定义长度的标量类型的抽象基类.这些类型的实际大小取决于特定的 numpy.dtype 实例化.

class numpy.character

所有字符串标量类型的抽象基类.

class numpy.bytes_

一个字节字符串.

当在数组中使用时,这种类型会去除尾随的空字节.

字符代码:

'S'

class numpy.str_

一个 unicode 字符串.

这种类型会去除尾随的空代码点.

>>> s = np.str_("abc\x00")
>>> s
'abc'

与内置的 str 不同,这支持 Buffer Protocol ,将其内容作为 UCS4 公开:

>>> m = memoryview(np.str_("abc"))
>>> m.format
'3w'
>>> m.tobytes()
b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00'

字符代码:

'U'

class numpy.void(length_or_data, /, dtype=None)

创建一个新的结构化或非结构化空标量.

参数:

length_or_dataint, 类数组, 类字节, 对象

多个含义之一（见注释）.一个非结构化void的长度或字节数据.或者,当提供`dtype`时,要存储在新标量中的数据.这可以是一个类数组对象,在这种情况下可能会返回一个数组.

dtypedtype,可选

如果提供了新标量的 dtype.这个 dtype 必须是 “void” dtype（即结构化或非结构化的 void,另请参见 结构化数据类型）.

在 1.24 版本加入.

备注

由于历史原因以及空标量可以表示任意字节数据和结构化数据类型,void 构造函数有三种调用约定:

1. np.void(5) 创建一个填充了五个 \0 字节的 dtype="V5" 标量.5 可以是 Python 或 NumPy 整数.

2. np.void(b"bytes-like") 从字节字符串创建一个空标量.dtype 项大小将与字节字符串长度匹配,这里为 "V10".

3. 当传递 dtype= 时,调用大致与数组创建相同.然而,返回的是一个空标量而不是数组.

请参阅示例,这些示例展示了所有三种不同的约定.

示例

>>> np.void(5)
np.void(b'\x00\x00\x00\x00\x00')
>>> np.void(b'abcd')
np.void(b'\x61\x62\x63\x64')
>>> np.void((3.2, b'eggs'), dtype="d,S5")
np.void((3.2, b'eggs'), dtype=[('f0', '<f8'), ('f1', 'S5')])
>>> np.void(3, dtype=[('x', np.int8), ('y', np.int8)])
np.void((3, 3), dtype=[('x', 'i1'), ('y', 'i1')])

字符代码:

'V'

警告

请参见 关于字符串类型的注释.

数值兼容性:如果你在 Numeric 代码中使用了旧的类型代码字符（这从未被推荐）,你需要将其中一些字符更改为新的字符.特别是,需要的更改是 c -> S1, b -> B, 1 -> b, s -> h, w -> H, 和 u -> I.这些更改使得类型字符约定与其他 Python 模块（如 struct 模块）更加一致.

Sized 别名

除了它们（大部分）源自C语言的名称外,整数、浮点数和复数数据类型也可以使用位宽约定,以确保始终可以创建正确大小的数组.还提供了两个别名（numpy.intp 和 numpy.uintp）,指向足够大的整数类型以容纳C指针.

numpy.int8

numpy.int16

numpy.int32

numpy.int64

有符号整数类型的别名（numpy.byte, numpy.short, numpy.intc, numpy.int_, numpy.long 和 numpy.longlong 之一）,具有指定的位数.

分别兼容 C99 的 int8_t, int16_t, int32_t, 和 int64_t.

numpy.uint8

numpy.uint16

numpy.uint32

numpy.uint64

指定位数的无符号整数类型（numpy.ubyte、numpy.ushort、numpy.uintc、numpy.uint、numpy.ulong 和 numpy.ulonglong 之一）的别名.

分别兼容 C99 的 uint8_t, uint16_t, uint32_t, 和 uint64_t.

numpy.intp

有符号整数类型（numpy.byte、numpy.short、numpy.intc、numpy.int_、numpy.long 和 numpy.longlong 之一）的别名,用作默认整数和索引.

与 C 的 Py_ssize_t 兼容.

字符代码:

'n'

在 2.0 版本发生变更: 在 NumPy 2 之前,这具有与指针相同的大小.实际上这几乎总是相同的,但字符代码 'p' 映射到 C 的 intptr_t.字符代码 'n' 是在 NumPy 2.0 中添加的.

numpy.uintp

与 intp 大小相同的无符号整数类型的别名.

兼容 C 语言的 size_t.

字符代码:

'N'

在 2.0 版本发生变更: 在 NumPy 2 之前,这具有与指针相同的大小.实际上这几乎总是一致的,但字符代码 'P' 映射到 C 语言的 uintptr_t.字符代码 'N' 是在 NumPy 2.0 中添加的.

numpy.float16

half 的别名

numpy.float32

single 的别名

numpy.float64

double 的别名

numpy.float96

numpy.float128

numpy.longdouble 的别名,根据其在位数上的大小命名.这些别名的存在取决于平台.

numpy.complex64

csingle 的别名

numpy.complex128

cdouble 的别名

numpy.complex192

numpy.complex256

numpy.clongdouble 的别名,根据其在位数上的大小命名.这些别名的存在取决于平台.

属性

数组标量对象具有 数组优先级 为 NPY_SCALAR_PRIORITY (-1,000,000.0).它们也没有（尚未）具有 ctypes 属性.否则,它们与数组具有相同的属性:

generic.flags	标志的整数值.
generic.shape	数组维度的元组.
generic.strides	每个维度中的字节步长的元组.
generic.ndim	数组的维度数量.
generic.data	指向数据起始的指针.
generic.size	gentype 中的元素数量.
generic.itemsize	一个元素的字节长度.
generic.base	标量属性与相应的数组属性相同.
generic.dtype	获取数组数据描述符.
generic.real	标量的实部.
generic.imag	标量的虚部.
generic.flat	标量的1-D视图.
generic.T	标量属性与相应的数组属性相同.
generic.__array_interface__	Python 端
generic.__array_struct__	struct
generic.__array_priority__	数组优先级.
generic.__array_wrap__	sc.__array_wrap__(obj) 从数组返回标量

索引

参见

数组.索引, 数组.数据类型

数组标量可以像 0 维数组一样被索引:如果 x 是一个数组标量,

• x[()] 返回数组标量的副本

• x[...] 返回一个 0 维的 ndarray

• x['field-name'] 返回字段 field-name 中的数组标量.（x 可以有字段,例如,当它对应于结构化数据类型时.）

方法

数组标量具有与数组完全相同的方法.这些方法的默认行为是将标量内部转换为等效的0维数组,并调用相应的数组方法.此外,数组标量的数学运算被定义为设置相同的硬件标志,并用于解释结果,如同用于 ufunc 一样,因此用于ufuncs的错误状态也适用于数组标量的数学运算.

上述规则的例外情况如下:

generic.__array__	sc.__array__(dtype) 从具有指定数据类型的标量返回0维数组
generic.__array_wrap__	sc.__array_wrap__(obj) 从数组返回标量
generic.squeeze	标量方法与相应的数组属性相同.
generic.byteswap	标量方法与相应的数组属性相同.
generic.__reduce__	pickle 的辅助工具.
generic.__setstate__
generic.setflags	标量方法与相应的数组属性相同.

用于输入的实用方法:

number.__class_getitem__(item, /)

返回一个围绕 number 类型的参数化包装器.

定义新类型

有两种方法可以有效地定义一个新的数组标量类型（除了从内置标量类型组成结构化类型 dtypes 之外）:一种方法是简单地子类化 ndarray 并重写感兴趣的方法.这在一定程度上会起作用,但内部某些行为是由数组的数据类型固定的.要完全自定义数组的数据类型,你需要定义一个新的数据类型,并将其注册到 NumPy.这种新类型只能在 C 中定义,使用 NumPy C-API.