类型提示 (`numpy.typing`)#

版本 1.20 中的新功能。

NumPy API 的大部分内容都具有 PEP 484 样式的类型注释。此外，还有一些类型别名可供用户使用，其中最突出的是以下两个

ArrayLike：可以转换为数组的对象
DTypeLike：可以转换为 dtype 的对象

Mypy 插件#

版本 1.21 中的新功能。

一个用于管理许多平台特定注释的 mypy 插件。其功能可以分为三个不同的部分

为某些 number 子类（包括 int_、intp 和 longlong 等）分配（平台相关的）精度。有关受影响类的全面概述，请参见有关标量类型的文档。如果没有此插件，所有相关类的精度都将被推断为 Any。
移除所有针对目标平台不可用的扩展精度 number 子类。最值得注意的是，这包括 float128 和 complex256 等。如果没有此插件，就 mypy 而言，所有扩展精度类型都将对所有平台可用。
分配 c_intp 的（平台相关的）精度。如果没有此插件，该类型将默认为 ctypes.c_int64。

版本 1.22 中的新功能。

示例#

要启用此插件，必须将其添加到 mypy 的配置文件中

[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 代码，但类型检查器会对此提出警告，因为不鼓励使用它。请参见：数据类型对象

数字精度#

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的对象。

其中包括：

type 对象。
字符代码或type对象的名称。
具有.dtype属性的对象。

版本 1.20 中的新功能。

参见

指定和构造数据类型: 可以强制转换为数据类型的所有对象的全面概述。

示例

>>> 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[int, ...], numpy.dtype[+_ScalarType_co]][source]#

一个np.ndarray[tuple[int, ...], np.dtype[+ScalarType]] 类型别名，关于其dtype.type是泛型。

可在运行时用于为具有给定dtype和未指定形状的数组进行类型化。

版本 1.21 中的新功能。

示例

>>> import numpy as np
>>> import numpy.typing as npt

>>> print(npt.NDArray)
numpy.ndarray[tuple[int, ...], numpy.dtype[+_ScalarType_co]]

>>> print(npt.NDArray[np.float64])
numpy.ndarray[tuple[int, ...], 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[source]#

表示在静态类型检查期间numpy.number精度的类型。

仅用于静态类型检查，NBitBase表示一系列分层子类的基类。每个后续子类在此用于表示更低的精度级别，例如64Bit > 32Bit > 16Bit。

版本 1.20 中的新功能。

示例

下面是一个典型的用法示例：NBitBase在此用于注释一个函数，该函数接受任意精度的浮点数和整数作为参数，并返回一个精度最高的新的浮点数（例如np.float16 + np.int64 -> np.float64）。

>>> from __future__ import annotations
>>> 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*]

类型提示 (numpy.typing)#

Mypy 插件#

示例#

与运行时 NumPy API 的区别#

ArrayLike#

ndarray#

DTypeLike#

数字精度#

Timedelta64#

0D 数组#

记录数组 dtype#

API#

类型提示 (`numpy.typing`)#