类型标注 ( numpy.typing )#
在 1.20 版本加入.
NumPy API 的大部分都有 PEP 484 风格的类型注解.此外,还有一些类型别名可供用户使用,其中最突出的是以下两个:
Mypy 插件#
在 1.21 版本加入.
一个 mypy 插件,用于管理许多平台特定的注解.它的功能可以分为三个不同的部分:
分配某些
number子类(包括int_,intp和longlong等)的(平台相关的)精度. 有关受影响类的全面概述,请参见 scalar types 的文档. 如果没有插件,所有相关类的精度将被推断为Any.删除所有不可用于相关平台的扩展精度
number子类. 其中最值得注意的是float128和complex256等. 如果没有插件,就 mypy 而言,所有扩展精度类型都可用于所有平台.分配
c_intp的(平台相关的)精度. 如果没有插件,该类型将默认为ctypes.c_int64.在 1.22 版本加入.
自 2.3 版本弃用.
示例#
要启用该插件,必须将其添加到 mypy configuration file 中:
[mypy]
plugins = numpy.typing.mypy_plugin
与运行时 NumPy API 的差异#
NumPy 非常灵活. 尝试静态地描述所有可能性会导致类型不是很有帮助. 因此,类型化的 NumPy API 通常比运行时 NumPy API 更严格. 本节描述了一些值得注意的差异.
ArrayLike#
ArrayLike 类型试图避免创建对象数组. 例如,
>>> np.array(x**2 for x in range(10))
array(<generator object <genexpr> at ...>, dtype=object)
是有效的 NumPy 代码,它将创建一个 0 维对象数组. 但是,当使用 NumPy 类型时,类型检查器会抱怨上面的例子. 如果您真的打算这样做,那么您可以使用 # type: ignore 注释:
>>> np.array(x**2 for x in range(10)) # type: ignore
或者将数组类的对象显式键入为 Any :
>>> from typing import Any
>>> array_like: Any = (x**2 for x in range(10))
>>> np.array(array_like)
array(<generator object <genexpr> at ...>, dtype=object)
ndarray#
可以在运行时改变数组的 dtype. 例如,以下代码是有效的:
>>> x = np.array([1, 2])
>>> x.dtype = np.bool
类型不允许这种改变. 想要编写静态类型代码的用户应该使用 numpy.ndarray.view 方法来创建一个具有不同 dtype 的数组视图.
DTypeLike#
DTypeLike 类型试图避免使用如下字段字典创建 dtype 对象:
>>> x = np.dtype({"field1": (float, 1), "field2": (int, 3)})
虽然这是有效的 NumPy 代码,但类型检查器会对此提出异议,因为不鼓励使用它. 请参阅: Data type objects
数字精度#
numpy.number 子类的精度被视为不变的泛型参数(参见 NBitBase ),从而简化了涉及基于精度的类型转换过程的标注.
>>> from typing import TypeVar
>>> import numpy as np
>>> import numpy.typing as npt
>>> T = TypeVar("T", bound=npt.NBitBase)
>>> def func(a: "np.floating[T]", b: "np.floating[T]") -> "np.floating[T]":
... ...
因此,像 float16 , float32 和 float64 仍然是 floating 的子类型,但是,与运行时相反,它们不一定被认为是子类.
Timedelta64#
静态类型检查时, timedelta64 类不被认为是 signedinteger 的子类,前者仅从 generic 继承.
0D 数组#
在运行时,numpy 会积极地将任何传递的 0D 数组强制转换为相应的 generic 实例. 在引入形状类型(参见 PEP 646 )之前,不幸的是,无法对 0D 和 >0D 数组进行必要的区分. 因此,虽然并非完全正确,但所有可能执行 0D 数组 -> 标量转换的操作目前都仅被标注为返回 ndarray .
如果事先知道某个操作将执行 0D 数组到标量的转换,那么可以考虑使用 typing.cast 或 # type: ignore 注释手动纠正这种情况.
记录数组 dtype#
numpy.recarray 的 dtype,以及通常 创建记录数组 函数,可以通过以下两种方式之一指定:
直接通过
dtype参数.最多可以使用五个辅助参数,这些参数通过
numpy.rec.format_parser运行:formats,names,titles,aligned和byteorder.
这两种方法目前被类型化为互斥的,即如果指定了 dtype ,则不能指定 formats .虽然这种互斥性在运行时并非(严格地)强制执行,但组合两个 dtype 说明符可能会导致意外甚至完全错误的行为.
API#
- numpy.typing.ArrayLike = typing.Union[...]#
一个
Union,表示可以强制转换为ndarray的对象.其中包括:
标量.
(嵌套) 序列.
实现 __array__ 协议的对象.
在 1.20 版本加入.
另请参阅
- array_like :
任何可以解释为 ndarray 的标量或序列.
示例
>>> import numpy as np >>> import numpy.typing as npt >>> def as_array(a: npt.ArrayLike) -> np.ndarray: ... return np.array(a)
- numpy.typing.DTypeLike = typing.Union[...]#
一个
Union,表示可以强制转换为dtype的对象.其中包括:
在 1.20 版本加入.
另请参阅
- Specifying and constructing data types
可以强制转换为数据类型的所有对象的全面概述.
示例
>>> import numpy as np >>> import numpy.typing as npt >>> def as_dtype(d: npt.DTypeLike) -> np.dtype: ... return np.dtype(d)
- numpy.typing.NDArray = numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]]#
一个
np.ndarray[tuple[Any, ...], np.dtype[ScalarT]]类型别名,相对于它的dtype.type而言是 generic .可以在运行时用于类型化具有给定 dtype 和未指定形状的数组.
在 1.21 版本加入.
示例
>>> import numpy as np >>> import numpy.typing as npt >>> print(npt.NDArray) numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]] >>> print(npt.NDArray[np.float64]) numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] >>> NDArrayInt = npt.NDArray[np.int_] >>> a: NDArrayInt = np.arange(10) >>> def func(a: npt.ArrayLike) -> npt.NDArray[Any]: ... return np.array(a)
- class numpy.typing.NBitBase[源代码]#
一个表示静态类型检查期间
numpy.number精度的类型.NBitBase仅用于静态类型检查,它表示一个分层子类的基础.每个后续子类在此用于表示较低的精度级别,例如64Bit > 32Bit > 16Bit.在 1.20 版本加入.
自 2.3 版本弃用: 请改用
@typing.overload或以标量类型作为上限的TypeVar.示例
下面是一个典型的用法示例:
NBitBase在此用于注释一个函数,该函数接受任意精度的浮点数和整数作为参数,并返回一个精度最高的新的浮点数(例如np.float16 + np.int64 -> np.float64).>>> from typing import TypeVar, TYPE_CHECKING >>> import numpy as np >>> import numpy.typing as npt >>> S = TypeVar("S", bound=npt.NBitBase) >>> T = TypeVar("T", bound=npt.NBitBase) >>> def add(a: np.floating[S], b: np.integer[T]) -> np.floating[S | T]: ... return a + b >>> a = np.float16() >>> b = np.int64() >>> out = add(a, b) >>> if TYPE_CHECKING: ... reveal_locals() ... # note: Revealed local types are: ... # note: a: numpy.floating[numpy.typing._16Bit*] ... # note: b: numpy.signedinteger[numpy.typing._64Bit*] ... # note: out: numpy.floating[numpy.typing._64Bit*]