NumPy 2.3.0 版本说明

NumPy 2.3.0 版本继续致力于改进 free threaded Python 支持和注解，并包含常规的错误修复。它在已过期的弃用、代码现代化和样式清理方面数量异常之多。后者可能对用户不可见，但对长期的代码维护至关重要。请注意，我们还已从 manylinux2014 升级到 manylinux_2_28。

在 M4 CPU 的 Mac 上运行的用户可能会看到有关无效值等的各种警告。这些警告是 Accelerate 的已知问题。它们很烦人，但否则无害。苹果公司承诺会修复它们。

此版本支持 Python 3.11-3.13。当 Python 3.14 发布后，也将支持该版本。

亮点

• NumPy 文档中的交互式示例。

• 使用 OpenMP 并行化构建 NumPy。

• 对 Windows ARM 的初步支持。

• 改进了对 free threaded Python 的支持。

• 改进了注解。

新增函数

新函数 numpy.strings.slice

添加了新函数 numpy.strings.slice，它实现了字符串数组的快速本机切片。它支持完整的切片 API，包括负切片偏移量和步长。

(gh-27789)

弃用

• 为了支持平台无关的静态类型推断，numpy.typing.mypy_plugin 已被弃用。请从 mypy 配置的 plugins 部分移除 numpy.typing.mypy_plugin。如果此更改导致报告了新的错误，请打开一个 issue。

  (gh-28129)

• numpy.typing.NBitBase 类型已被弃用，将在未来版本中移除。

  此类型先前旨在用作类型参数的通用上限，例如

  import numpy as np
  import numpy.typing as npt
  
  def f[NT: npt.NBitBase](x: np.complexfloating[NT]) -> np.floating[NT]: ...
  

  但在 NumPy 2.2.0 中，float64 和 complex128 已更改为具体子类型，导致静态类型检查器拒绝 x: np.float64 = f(np.complex128(42j))。

  因此，更好的方法是使用 typing.overload

  import numpy as np
  from typing import overload
  
  @overload
  def f(x: np.complex64) -> np.float32: ...
  @overload
  def f(x: np.complex128) -> np.float64: ...
  @overload
  def f(x: np.clongdouble) -> np.longdouble: ...
  

  (gh-28884)

已过期的弃用

• 从 Cython 接口中移除弃用的宏，如 NPY_OWNDATA，以支持 NPY_ARRAY_OWNDATA（自 1.7 起弃用）

  (gh-28254)

• 移除 numpy/npy_1_7_deprecated_api.h 和 C 宏，如 NPY_OWNDATA，以支持 NPY_ARRAY_OWNDATA（自 1.7 起弃用）

  (gh-28254)

• 移除别名 generate_divbyzero_error 到 npy_set_floatstatus_divbyzero 和 generate_overflow_error 到 npy_set_floatstatus_overflow（自 1.10 起弃用）

  (gh-28254)

• 移除 np.tostring（自 1.19 起弃用）

  (gh-28254)

• 对非数值类型的 np.conjugate 引发错误（自 1.13 起弃用）

  (gh-28254)

• 使用 np.bincount(...minlength=None) 时引发错误，请使用 0 代替（自 1.14 起弃用）

  (gh-28254)

• 将 shape=None 传递给具有非可选 shape 参数的函数会引发错误，请使用 () 代替（自 1.20 起弃用）

  (gh-28254)

• 对 mode 和 searchside 的不精确匹配会引发错误（自 1.20 起弃用）

  (gh-28254)

• 设置 __array_finalize__ = None 会引发错误（自 1.23 起弃用）

  (gh-28254)

• np.fromfile 和 np.fromstring 对损坏数据引发错误，以前它们会猜测（自 1.18 起弃用）

  (gh-28254)

• 使用元组构造 datetime64 和 timedelta64 不再接受 event 值，可以使用 (unit, num) 的二元组或 (unit, num, den, 1) 的四元组（自 1.14 起弃用）

  (gh-28254)

• 从具有 dtype 属性的类构造 dtype 时，该属性必须是 dtype 实例，而不是可以解析为 dtype 实例的内容（自 1.19 起弃用）。稍后，使用 dtype 属性的整个构造将被弃用（参见 #25306）。

  (gh-28254)

• 将布尔值作为分区索引传递会引发错误（自 1.23 起弃用）

  (gh-28254)

• 越界索引即使在空数组上也引发错误（自 1.20 起弃用）

  (gh-28254)

• np.tostring 已被移除，请使用 tobytes 代替（自 1.19 起弃用）

  (gh-28254)

• 不允许将不可写数组设置为可写，前提是该数组的基础（base）不拥有其数据（自 1.17 起弃用）

  (gh-28254)

• concatenate() 结合 axis=None 默认使用 same-kind 转换，而不是 unsafe（自 1.20 起弃用）

  (gh-28254)

• 反序列化具有 object dtype 的标量会引发错误（自 1.20 起弃用）

  (gh-28254)

• fromstring 的二进制模式现在会引发错误，请使用 frombuffer 代替（自 1.14 起弃用）

  (gh-28254)

• 将 np.inexact 或 np.floating 转换为 dtype 会引发错误（自 1.19 起弃用）

  (gh-28254)

• 将 np.complex、np.integer、np.signedinteger、np.unsignedinteger、np.generic 转换为 dtype 会引发错误（自 1.19 起弃用）

  (gh-28254)

• Python 内置的 round 对复数标量会引发错误。请使用 np.round 或 scalar.round 代替（自 1.19 起弃用）

  (gh-28254)

• ‘np.bool’ 标量不能再被解释为索引（自 1.19 起弃用）

  (gh-28254)

• 通过浮点字符串解析整数不再受支持。（自 1.23 起弃用）为避免此错误，您可以：* 确保原始数据存储为整数。* 使用 converters=float 关键字参数。* 使用 np.loadtxt(...).astype(np.int64)

  (gh-28254)

• 为 ufunc signature 使用长度为 1 的元组会引发错误。请使用 dtype 或用 None 填充元组（自 1.19 起弃用）

  (gh-28254)

• 在 np.outer 中已移除对矩阵的特殊处理。通过 matrix.A 转换为 ndarray（自 1.20 起弃用）

  (gh-28254)

• 移除了 np.compat 包的源代码（在 2.0 中移除）

  (gh-28961)

C API 更改

• NpyIter_GetTransferFlags 现在可用，用于检查迭代器是否需要 Python API 或转换是否可能导致浮点错误 (FPE)。例如，当将 float64(1e300) 转换为 float32（溢出为无穷大）或将 NaN 转换为整数（无效值）时，可能会设置 FPE。

  (gh-27883)

• NpyIter 现在对操作数的数量没有限制。

  (gh-28080)

新的 NpyIter_GetTransferFlags 和 NpyIter_IterationNeedsAPI 更改

NumPy 现在拥有新的 NpyIter_GetTransferFlags 函数，作为检查迭代器/缓冲需求的更精确的方法。也就是说，是否需要 Python API/GIL，或者是否可能发生浮点错误。如果您已经知道自己的需求而不进行缓冲，此函数也更快。

NpyIter_IterationNeedsAPI 函数现在执行所有先前在设置时执行的检查。虽然从未有必要多次调用它，但现在多次调用它的成本会更高。

(gh-27998)

新功能

• np.dtype 的类型参数现在默认为 typing.Any。这样，静态类型检查器会将 dtype: np.dtype 推断为 dtype: np.dtype[Any]，而不会报告错误。

  (gh-28669)

• 静态类型检查器现在解释

  • _: np.ndarray 为 _: npt.NDArray[typing.Any]。

  • _: np.flatiter 为 _: np.flatiter[np.ndarray]。

  这是因为它们的类型参数现在具有默认值。

  (gh-28940)

NumPy 现在将其 pkg-config 路径注册到 pkgconf PyPI 包

pkgconf PyPI 包提供了一个接口，允许像 NumPy 这样的项目注册自己的路径以添加到 pkg-config 搜索路径。这意味着，当使用 pkgconf (来自 PyPI) 时，无需任何自定义环境配置即可发现 NumPy。

注意

注意

这仅在从 PyPI 使用 pkgconf 包时适用，换句话说，这仅在通过 Python 包管理器安装 pkgconf 时适用。

如果您使用的是系统提供的 pkg-config 或 pkgconf，或者任何其他不使用 pkgconf-pypi 项目的来源，NumPy 的 pkg-config 目录将不会自动添加到搜索路径。在这些情况下，您可能希望使用 numpy-config。

(gh-28214)

允许 ufunc 中的 out=... 来确保数组结果

NumPy 有一个有时难以处理的行为，那就是它通常返回标量而不是 0-D 数组（即使输入是 0-D 数组）。这对于非数值 dtype（例如 object）尤其成问题。

对于 ufunc（即大多数简单的数学函数），现在可以使用 out=...（字面意思是 `…`，例如 out=Ellipsis），其行为与不传递 out 相同，但它会确保返回非标量。这种拼写是从 arr1d[0, ...] 借用的，其中 ... 也确保返回非标量。

其他带有 out= kwargs 的函数最终也将获得支持。通过 __array_ufunc__ 或 __array_function__ 进行互操作的下游库可能需要适应以支持此功能。

(gh-28576)

使用 OpenMP 并行化构建 NumPy

使用 -Denable_openmp=true Meson 构建标志构建 NumPy 时，它现在支持 OpenMP 并行处理功能。此功能默认禁用。启用后，np.sort 和 np.argsort 函数可以利用 OpenMP 进行并行线程执行，从而提高这些操作的性能。

(gh-28619)

NumPy 文档中的交互式示例

NumPy 文档包含许多示例，现在可以使用 WebAssembly 和 Pyodide 在浏览器中交互式运行它们。

请注意，这些示例目前是实验性的，可能并非在所有公共 API 方法上都能按预期工作。

(gh-26745)

改进

• 非可比 dtype 之间的标量比较，例如 np.array(1) == np.array('s')，现在返回 NumPy 布尔值而不是 Python 布尔值。

  (gh-27288)

• np.nditer 现在对支持的操作数数量没有限制（C 整数）。

  (gh-28080)

• 现在支持任何可以转置为 C 连续数组的数组的无复制打包。

  (gh-28105)

• 用户定义 dtype 的 __repr__ 现在更倾向于使用自定义 dtype 的 __name__，而不是由其 kind 和 itemsize 构建的更通用的名称。

  (gh-28250)

• np.dot 现在报告浮点异常。

  (gh-28442)

• np.dtypes.StringDType 现在是一个 泛型类型，它接受一个 na_object 的类型参数，该参数默认为 typing.Never。例如，StringDType(na_object=None) 返回 StringDType[None]，而 StringDType() 返回 StringDType[typing.Never]。

  (gh-28856)

向 np.isclose 添加了警告

如果在 np.isclose 中的 atol 或 rtol 至少有一个是 np.nan 或 np.inf，则添加了警告消息。

• 警告遵循用户的 np.seterr 设置

(gh-28205)

性能改进和更改

np.unique 的性能改进

np.unique 现在尝试使用哈希表查找唯一值，而不是先对值进行排序再查找唯一值。目前这仅限于某些 dtype，并且对于这些 dtype，该函数现在更快。该函数现在还公开了一个 sorted 参数，允许将唯一值按找到的顺序返回，而不是之后进行排序。

(gh-26018)

np.sort 和 np.argsort 的性能改进

np.sort 和 np.argsort 函数现在可以利用 OpenMP 进行并行线程执行，在具有 AVX2 或 AVX-512 指令的 x86 架构上可提高高达 3.5 倍的速度。此可选功能需要使用 -Denable_openmp Meson 标志构建 NumPy。用户可以通过设置 OMP_NUM_THREADS 环境变量来控制使用的线程数。

(gh-28619)

np.float16 转换的性能改进

以前，浮点数与 np.float16 类型之间的转换在所有平台上都通过软件模拟。

现在，在支持 Neon float16 内置函数（如最新的 Apple Silicon）的 ARM 设备上，会使用本机 float16 路径以获得最佳性能。

(gh-28769)

np.matmul 的性能改进

即使操作数不连续，也能通过在需要时进行复制来使用 BLAS 进行 matmul。

(gh-23752)

更改

• 向量范数 ord=inf 和矩阵范数 ord={1, 2, inf, 'nuc'} 现在对空数组始终返回零。空数组至少有一个尺寸为零的轴。这会影响 np.linalg.norm、np.linalg.vector_norm 和 np.linalg.matrix_norm。以前，NumPy 会根据数组的形状引发错误或返回零。

  (gh-28343)

• 在通过 np.format_float_positional 方法将字符串转换为浮点数时返回的错误消息中的拼写错误已得到修复。

  (gh-28569)

• NumPy 的 __array_api_version__ 已从 2023.12 升级到 2024.12。

• numpy.count_nonzero 对于 axis=None（默认）现在返回 NumPy 标量而不是 Python 整数。

• numpy.take_along_axis 函数中的 axis 参数现在默认值为 -1。

  (gh-28615)

• 通过调整基于浮点精度对科学记数法的转换，改进了 np.float16 和 np.float32 标量和数组的打印。已添加新的旧版 np.printoptions 模式 '2.2' 以实现向后兼容。

  (gh-28703)

• 字符串和整数之间的乘法现在会引发 OverflowError 而不是 MemoryError，如果乘法的结果会创建一个过大的字符串。这遵循 Python 的行为。

  (gh-29060)

unique_values 可能返回未排序的数据

相对较新的函数（在 NumPy 2.0 中添加）unique_values 现在可能返回未排序的结果。就像 unique_counts 和 unique_all 一样，它们从不保证结果已排序，但直到现在结果都是已排序的。在这些情况下返回已排序结果，未来版本可能会更改以提高性能。

(gh-26018)

主迭代器和潜在的数值更改

主迭代器（在数学函数中使用，并通过 Python 的 np.nditer 和 C 的 NpyIter 使用）现在对于某些缓冲迭代行为不同。这意味着：

• 使用的缓冲区大小通常会小于 buffersize 参数允许的最大缓冲区大小。

• 当没有操作数需要缓冲时，“growinner”标志现在会得到遵守，用于缓冲归约。

对于 np.sum()，缓冲区大小的此类更改可能会轻微改变浮点运算的数值结果。使用“growinner”进行自定义归约的用户可能会注意到精度的变化（例如，在 NumPy 中，我们将其从 einsum 中移除，以避免大多数精度变化并提高某些 64 位浮点输入的精度）。

(gh-27883)

最低支持的 GCC 版本现在是 9.3.0

最低支持版本已从 8.4.0 更新到 9.3.0，主要目的是减少旧 GCC 版本中平台特定 bug 导致问题的可能性。

(gh-28102)

numpy.histogram 中自动 bin 选择的更改

numpy.histogram 中的自动 bin 选择算法已得到修改，以避免对变异度低的样本出现内存不足错误。如需对所选 bin 进行完全控制，用户可以使用 numpy.histogram 的 bin 或 range 参数。

(gh-28426)

构建 manylinux_2_28 轮子

linux 系统的轮子将使用 manylinux_2_28 标签（而不是 manylinux2014 标签），这意味着将不再支持 redhat7/centos7、amazonlinux2、debian9、ubuntu18.04 和其他 glibc2.28 之前的操作系统版本，具体请参见 PEP 600 支持表。

(gh-28436)

在 macOS 上移除对 -Wl,-ld_classic 的使用

在 macOS 上移除对 -Wl,-ld_classic 的使用。Spack 不再需要此 hack，并且会导致无法链接到使用 ld（新）构建的其他库的库。

(gh-28713)

重新启用覆盖 numpy.strings 中的函数

重新启用覆盖 numpy.strings 模块中的函数。

(gh-28741)