NumPy 2.0.0 发布说明#

NumPy 2.0.0 是自 2006 年以来的首次重大发布。它是距离上次功能发布 11 个月开发的成果，由 212 位贡献者通过 1078 个拉取请求完成。它包含大量令人兴奋的新功能，以及对 Python 和 C API 的更改。

此次重大发布包含无法在常规次要（功能）版本中进行的重大更改，包括 ABI 更改、类型提升规则的更改以及可能未在 1.26.x 中发出弃用警告的 API 更改。除了这些发布说明外，与适应 NumPy 2.0 更改相关的重要文档还包括：

亮点#

本次发布亮点包括：

  • 新功能

    • 新的可变长度字符串 dtype StringDType 和新的 numpy.strings 命名空间，提供高性能的字符串操作 ufunc，

    • 在所有 numpy.fft 函数中支持 float32 和 longdouble，

    • 在主要的 numpy 命名空间中支持数组 API 标准。

  • 性能改进

    • 排序函数（sort、argsort、partition、argpartition）已通过使用 Intel x86-simd-sort 和 Google Highway 库进行了加速，可能会看到（硬件特定）的大幅速度提升，

    • macOS Accelerate 支持和 macOS >=14 的二进制 wheel，在 macOS 上线性代数运算的性能显著提升，且 wheel 文件大小减小约 3 倍，

    • 《numpy.char》的固定长度字符串操作已通过实现支持 StringDType 以及固定长度字符串 dtype 的 ufunc 进行了加速，

    • 新的跟踪和内省 API opt_func_info，用于确定哪些硬件特定内核可用并将被分派。

    • 《numpy.save》现在使用 pickle 协议版本 4 来保存具有 object dtype 的数组，这允许保存大于 4GB 的 pickle 对象，并将大数组的保存速度提高约 5%。

  • Python API 改进

    • 公共 API 和私有 API 之间的清晰划分，以及新的《模块结构》，每个公共函数现在都可以在一个地方找到，

    • 许多不推荐使用的函数和别名已被移除。这应该使学习和使用 NumPy 更加容易。主命名空间中的对象数量减少了约 10%，numpy.lib 中的对象数量减少了约 80%，

    • 《规范的 dtype 名称》和一个新的 isdtype 内省函数，

  • C API 改进

  • 行为改进

    • 通过采纳《NEP 50》，类型提升行为得到了改进。这解决了用户关于提升的许多意外情况，过去提升常常依赖于输入数组的数据值而非仅其 dtype。请参阅 NEP 和《NumPy 2.0 迁移指南》了解详情，因为此更改可能会导致混合 dtype 操作的输出 dtype 和较低精度结果发生变化。

    • Windows 上的默认整数类型现在是 int64 而不是 int32，与其他平台行为一致，

    • 数组维度的最大数量从 32 更改为 64

  • 文档

此外，NumPy 内部也进行了许多更改，包括继续将 C 代码迁移到 C++，这将使未来改进和维护 NumPy 更加容易。

“没有免费午餐”定理规定，所有这些 API 和行为改进以及更好的未来可扩展性都有代价。这个代价是：

  1. 向后兼容性。Python 和 C API 都有大量重大更改。在大多数情况下，有清晰的错误消息会告知用户如何修改其代码。但是，也有一些行为更改无法提供此类错误消息——这些情况都涵盖在下面的弃用和兼容性部分以及《NumPy 2.0 迁移指南》中。

    请注意，有一个 ruff 模式可以自动修复 Python 代码中的许多问题。

  2. NumPy ABI 的重大更改。因此，使用 NumPy C API 并针对 NumPy 1.xx 版本构建的软件包二进制文件将无法与 NumPy 2.0 一起使用。导入时，此类软件包将看到一个 ImportError，并带有关于二进制不兼容的消息。

    可以针对 NumPy 2.0 构建二进制文件，这些文件在运行时可以与 NumPy 2.0 和 1.x 一起使用。有关更多详细信息，请参阅《NumPy 2.0 特定建议》。

    所有依赖 NumPy ABI 的下游软件包都被建议针对 NumPy 2.0 进行新的发布，并验证该发布是否与 2.0 和 1.26 都能正常工作——最好是在 2.0.0rc1（将是 ABI 稳定版）和最终的 2.0.0 版本之间进行，以避免用户遇到问题。

此版本支持的 Python 版本为 3.9-3.12。

NumPy 2.0 Python API 移除#

  • 已移除 np.geterrobj、np.seterrobj 以及相关的 ufunc 关键字参数 extobj=。所有这些的首选替代方法是使用上下文管理器 with np.errstate():。

    (gh-23922)

  • 已移除 np.cast。对于 np.cast[dtype](arg)，字面上的替换是 np.asarray(arg, dtype=dtype)。

  • 已移除 np.source。首选的替代方法是 inspect.getsource。

  • 已移除 np.lookfor。

    (gh-24144)

  • 已移除 numpy.who。作为被移除功能的替代方案，可以使用 IDE（如 Spyder 或 Jupyter Notebook）中提供的变量浏览器。

    (gh-24321)

  • 《numpy.exceptions》（例如 ComplexWarning、VisibleDeprecationWarning）中存在的警告和异常不再暴露在主命名空间中。

  • 多个小众枚举、已过期成员和函数已从主命名空间中移除，例如：ERR_*、SHIFT_*、np.fastCopyAndTranspose、np.kernel_version、np.numarray、np.oldnumeric 和 np.set_numeric_ops。

    (gh-24316)

  • 已将 numpy/__init__.py 中的 from ... import * 替换为显式导入。因此，以下主命名空间成员已被移除：np.FLOATING_POINT_SUPPORT、np.FPE_*、np.NINF、np.PINF、np.NZERO、np.PZERO、np.CLIP、np.WRAP、np.WRAP、np.RAISE、np.BUFSIZE、np.UFUNC_BUFSIZE_DEFAULT、np.UFUNC_PYVALS_NAME、np.ALLOW_THREADS、np.MAXDIMS、np.MAY_SHARE_EXACT、np.MAY_SHARE_BOUNDS、add_newdoc、np.add_docstring 和 np.add_newdoc_ufunc。

    (gh-24357)

  • 别名 np.float_ 已被移除。请使用 np.float64 代替。

  • 别名 np.complex_ 已被移除。请使用 np.complex128 代替。

  • 别名 np.longfloat 已被移除。请使用 np.longdouble 代替。

  • 别名 np.singlecomplex 已被移除。请使用 np.complex64 代替。

  • 别名 np.cfloat 已被移除。请使用 np.complex128 代替。

  • 别名 np.longcomplex 已被移除。请使用 np.clongdouble 代替。

  • 别名 np.clongfloat 已被移除。请使用 np.clongdouble 代替。

  • 别名 np.string_ 已被移除。请使用 np.bytes_ 代替。

  • 别名 np.unicode_ 已被移除。请使用 np.str_ 代替。

  • 别名 np.Inf 已被移除。请使用 np.inf 代替。

  • 别名 np.Infinity 已被移除。请使用 np.inf 代替。

  • 别名 np.NaN 已被移除。请使用 np.nan 代替。

  • 别名 np.infty 已被移除。请使用 np.inf 代替。

  • 别名 np.mat 已被移除。请使用 np.asmatrix 代替。

  • 已移除 np.issubclass_。请使用内置的 issubclass 代替。

  • 已移除 np.asfarray。请使用带有正确 dtype 的 np.asarray 代替。

  • 已移除 np.set_string_function。请使用带有自定义 NumPy 对象打印格式化器的 np.set_printoptions 代替。

  • np.tracemalloc_domain 现在只能从 np.lib 访问。

  • 已从主命名空间移除了 np.recfromcsv 和 np.recfromtxt。请使用逗号分隔符的 np.genfromtxt 代替。

  • 已从主命名空间移除了 np.issctype、np.maximum_sctype、np.obj2sctype、np.sctype2char、np.sctypes、np.issubsctype，且无替代品，因为它们是小众成员。

  • 已从主命名空间移除了弃用的 np.deprecate 和 np.deprecate_with_doc。请使用 DeprecationWarning 代替。

  • 已从主命名空间移除了弃用的 np.safe_eval。请使用 ast.literal_eval 代替。

    (gh-24376)

  • 已移除 np.find_common_type。请使用 numpy.promote_types 或 numpy.result_type 代替。为了实现 scalar_types 参数的语义，请使用 numpy.result_type 并将 Python 标量 0、0.0 或 0j 作为参数传递。

  • 已移除 np.round_。请使用 np.round 代替。

  • 已移除 np.nbytes。请使用 np.dtype(<dtype>).itemsize 代替。

    (gh-24477)

  • 已从主命名空间移除了 np.compare_chararrays。请使用 np.char.compare_chararrays 代替。

  • 主命名空间中的 chararray 已被弃用。目前可以从 np.char.chararray 导入而不会收到弃用警告，但我们计划将来完全弃用并移除 chararray。

  • 已从主命名空间移除了 np.format_parser。请使用 np.rec.format_parser 代替。

    (gh-24587)

  • 已从 np.dtype 中移除了对七个数据类型字符串别名的支持：int0、uint0、void0、object0、str0、bytes0 和 bool8。

    (gh-24807)

  • 实验性的 numpy.array_api 子模块已被移除。请在日常使用中改用主 numpy 命名空间，或使用单独的 array-api-strict 包来处理 numpy.array_api 主要用于的合规性测试用例。

    (gh-25911)

__array_prepare__ 已被移除#

Ufunc 在执行正常 ufunc 调用（非通用 ufunc、归约等）的计算之前会调用 __array_prepare__。此函数还在某些线性代数函数的计算结果上被调用，而不是 __array_wrap__。

现已移除。如果您使用了它，请迁移到 __array_ufunc__ 或依赖 __array_wrap__，它在所有情况下都会传递一个上下文，但仅在结果数组填充后调用。在这些代码路径中，__array_wrap__ 现在将传递一个基类，而不是一个子类数组。

(gh-25105)

弃用#

  • 由于不再支持 Python 2，np.compat 已被弃用。

  • 《numpy.int8》及类似类将不再支持将超出边界的 Python 整数转换为整数数组。例如，将 255 转换为 int8 将不会返回 -1。可以使用 np.iinfo(dtype) 来检查数据类型的机器限制。例如，np.iinfo(np.uint16) 返回 min = 0 和 max = 65535。

    np.array(value).astype(dtype) 将产生所需的结果。

  • np.safe_eval 已被弃用。应使用 ast.literal_eval 代替。

    (gh-23830)

  • 已弃用 np.recfromcsv、np.recfromtxt、np.disp、np.get_array_wrap、np.maximum_sctype、np.deprecate 和 np.deprecate_with_doc。

    (gh-24154)

  • 已弃用 np.trapz。请使用 np.trapezoid 或 scipy.integrate 函数代替。

  • 已弃用 np.in1d。请使用 np.isin 代替。

  • 别名 np.row_stack 已被弃用。请直接使用 np.vstack。

    (gh-24445)

  • __array_wrap__ 现在接收 arr, context, return_scalar，不支持所有三个参数的实现已被弃用。其签名应为 __array_wrap__(self, arr, context=None, return_scalar=False)

    (gh-25409)

  • 《np.cross》的二维向量数组已被弃用。请使用三维向量数组代替。

    (gh-24818)

  • 别名 np.dtype("a") 用于 np.dtype(np.bytes_) 已被弃用。请使用别名 np.dtype("S") 代替。

    (gh-24854)

  • 在 assert_array_equal 和 assert_array_almost_equal 函数中使用关键字参数 x 和 y 已被弃用。请改用位置参数传递前两个参数。

    (gh-24978)

NumPy.fft n-D 变换的参数中 None 值的弃用#

使用 fftn、ifftn、rfftn、irfftn、fft2、ifft2、rfft2 或 irfft2，并将 s 参数设置为非 None 值，同时将 axes 参数设置为 None，这已根据数组 API 标准被弃用。为保留当前行为，对于维度为 k 的数组，请将 axes 设置为一个序列 [0, …, k-1]。

此外，将一个包含 None 值的数组传递给 s 参数已被弃用，因为 NumPy 文档和数组 API 规范都声明该参数接受一个整数序列。要使用相应的 1-D 变换的默认行为，请将 s 参数设置为与其 n 参数默认值匹配的值。要对所有轴使用默认行为，可以省略 s 参数。

(gh-25495)

np.linalg.lstsq 现在默认使用新的 rcond 值#

lstsq 现在使用新的 rcond 值，即机器精度乘以 max(M, N)。先前使用的是机器精度，但会给出 FutureWarning 以通知该更改最终会发生。通过传递 rcond=-1 仍然可以实现旧的行为。

(gh-25721)

已过期的弃用#

  • 《np.core.umath_tests》子模块已从公共 API 中移除。（在 NumPy 1.15 中已弃用）

    (gh-23809)

  • 《PyDataMem_SetEventHook》的弃用已过期并已被移除。请使用 tracemalloc 和 np.lib.tracemalloc_domain 域。（在 NumPy 1.23 中已弃用）

    (gh-23921)

  • 《set_numeric_ops》以及 C 函数 PyArray_SetNumericOps 和 PyArray_GetNumericOps 的弃用已过期，函数已被移除。（在 NumPy 1.16 中已弃用）

    (gh-23998)

  • 《fasttake》、《fastclip》和《fastputmask》ArrFuncs 的弃用现已最终确定。

  • 已弃用的函数 fastCopyAndTranspose 及其 C 对应函数现已移除。

  • 《PyArray_ScalarFromObject》的弃用现已最终确定。

    (gh-24312)

  • 已移除 np.msort。替代方案应使用 np.sort(a, axis=0)。

    (gh-24494)

  • np.dtype(("f8", 1) 现在将返回形状为 1 的子数组 dtype，而不是非子数组 dtype。

    (gh-25761)

  • 禁止向 ndarray 的 .data 属性赋值，否则会引发异常。

  • np.binary_repr(a, width) 如果 width 过小将引发异常。

  • 在 PyArray_DescrFromType() 中使用 NPY_CHAR 将引发异常，请改用 NPY_STRING、NPY_UNICODE 或 NPY_VSTRING。

    (gh-25794)

兼容性说明#

loadtxt 和 genfromtxt 默认编码已更改#

loadtxt 和 genfromtxt 现在都默认使用 encoding=None，这主要会修改 converters 的工作方式。这些现在将接收 str 而不是 bytes。通过显式传递编码来始终获得新行为或旧行为。对于 genfromtxt，此更改还意味着返回的值现在将是 unicode 字符串而不是字节。

(gh-25158)

f2py 兼容性说明#

  • f2py 将不再接受模糊的 -m 和 .pyf CLI 组合。当传递多个 .pyf 文件时，会引发错误。当同时传递 -m 和 .pyf 时，会发出警告并忽略 -m 提供的名称。

    (gh-25181)

  • 已移除 f2py.compile() 辅助函数，因为它会泄漏内存，已被标记为实验性多年，并且实现为一个简单的 subprocess.run 包装器。它也是测试瓶颈之一。有关完整理由，请参阅 gh-25122。它还使用了几个 np.distutils 功能，这些功能对于移植到与 meson 配合使用来说过于脆弱。

  • 强烈建议用户将 f2py.compile 的调用替换为调用 subprocess.run("python", "-m", "numpy.f2py",...，并使用环境变量与 meson 进行交互。原生文件也是一个选项。

    (gh-25193)

排序函数行为的小改动#

由于算法更改和 SIMD 代码的使用，在 2.0.0 版本中，不稳定的排序函数可能与 1.26.x 版本相比返回稍有不同的结果。这包括 argsort 和 argpartition 的默认方法。

解决了 np.solve 中广播时的歧义#

当 b 的维度比 a 少一个时，np.solve(a, b) 的广播规则存在歧义。这已以一种不兼容向后兼容的方式得到解决，现在符合 Array API。可以通过使用 np.solve(a, b[..., None])[..., 0] 来重现旧行为。

(gh-25914)

修改了 Polynomial 的表示形式#

更新了 Polynomial 的表示方法，以包含域。纯文本和 latex 表示现在是一致的。例如，str(np.polynomial.Polynomial([1, 1], domain=[.1, .2])) 的输出曾经是 1.0 + 1.0 x，但现在是 1.0 + 1.0 (-3.0000000000000004 + 20.0 x)。

(gh-21760)

C API 更改#

  • 已删除 PyArray_CGT、PyArray_CLT、PyArray_CGE、PyArray_CLE、PyArray_CEQ、PyArray_CNE 宏。

  • PyArray_MIN 和 PyArray_MAX 已从 ndarraytypes.h 移至 npy_math.h。

    (gh-24258)

  • 已公开用于处理 numpy.dtypes.StringDType 数组的 C API。这包括用于获取和释放锁定字符串数据访问的互斥锁的函数，以及从数组条目打包和解包 UTF-8 字节流的函数。

  • NPY_NTYPES 已重命名为 NPY_NTYPES_LEGACY，因为它不包含新的 NumPy 内置 DTypes。特别是，新的字符串 DType 可能无法与处理旧 DTypes 的代码正确配合使用。

    (gh-25347)

  • C-API 现在仅导出数组访问器的静态内联函数版本（以前这取决于使用“已弃用的 API”）。虽然我们不鼓励这样做，但仍然可以直接使用结构体字段。

    (gh-25789)

  • NumPy 现在定义了 PyArray_Pack 来设置单个内存地址。与 PyArray_SETITEM 不同，此函数等同于设置单个数组项，并且不需要 NumPy 数组输入。

    (gh-25954)

  • 已从 PyArray_Descr 中删除 ->f 插槽。如果您使用此插槽，请使用 PyDataType_GetArrFuncs（请参阅其文档和 NumPy 2.0 迁移指南）替换对其的访问。在某些情况下，使用 PyArray_GETITEM 等其他函数可能是一个替代方案。

  • PyArray_GETITEM 和 PyArray_SETITEM 现在需要导入 NumPy API 表才能使用，并且不再定义在 ndarraytypes.h 中。

    (gh-25812)

  • 由于运行时依赖项，访问 dtype 标志的功能定义已从 numpy/ndarraytypes.h 移出，并且仅在包含 numpy/ndarrayobject.h 后可用，因为它需要 import_array()。这包括 PyDataType_FLAGCHK、PyDataType_REFCHK 和 NPY_BEGIN_THREADS_DESCR。

  • 现在必须通过 PyDataType_FLAGS 内联函数访问 PyArray_Descr 上的 dtype 标志，以兼容 1.x 和 2.x。此函数定义在 npy_2_compat.h 中，以允许向后移植。大多数或所有用户应使用 PyDataType_FLAGCHK，它在 1.x 中可用且不需要向后移植。Cython 用户应使用 Cython 3。否则，访问将通过 Python 进行，除非他们使用 PyDataType_FLAGCHK 而不是。

    (gh-25816)

C API 和 Cython 绑定中公开的日期时间功能#

已将 NpyDatetime_ConvertDatetime64ToDatetimeStruct、NpyDatetime_ConvertDatetimeStructToDatetime64、NpyDatetime_ConvertPyDateTimeToDatetimeStruct、NpyDatetime_GetDatetimeISO8601StrLen、NpyDatetime_MakeISO8601Datetime 和 NpyDatetime_ParseISO8601Datetime 函数添加到 C API，以方便在外部库中进行字符串、Python datetime 和 NumPy datetime 之间的转换。

(gh-21199)

广义 ufunc C API 的 const 正确性#

NumPy C API 用于构建广义 ufuncs 的函数（PyUFunc_FromFuncAndData、PyUFunc_FromFuncAndDataAndSignature、PyUFunc_FromFuncAndDataAndSignatureAndIdentity）接受 NumPy 内部不会修改的 types 和 data 参数。与 name 和 doc 参数一样，第三方 Python 扩展模块很可能会从静态常量提供这些参数。types 和 data 参数现在是 const 正确的：它们分别声明为 const char *types 和 void *const *data。C 代码不应受影响，但 C++ 代码可能会。

(gh-23847)

更大的 NPY_MAXDIMS 和 NPY_MAXARGS，引入了 NPY_RAVEL_AXIS#

NPY_MAXDIMS 现在是 64，您可能需要审查其用法。这通常用于堆栈分配，因此增加应该是安全的。但是，我们普遍鼓励删除对 NPY_MAXDIMS 和 NPY_MAXARGS 的任何使用，以便最终完全删除限制。对于转换辅助函数和镜像 Python 函数的 C API 函数，例如 take，NPY_MAXDIMS 用于表示 axis=None。此类用法必须替换为 NPY_RAVEL_AXIS。另请参阅 最大维度数增加。

(gh-25149)

NPY_MAXARGS 不再是常量，并且 PyArrayMultiIterObject 的大小已更改#

由于 NPY_MAXARGS 已增加，它现在是运行时常量而不是编译时常量。我们预计几乎没有用户会注意到这一点。但如果用于堆栈分配，现在必须用自定义常量替换，并将 NPY_MAXARGS 作为额外的运行时检查。

sizeof(PyArrayMultiIterObject) 不再包含对象的大小。我们预计没有人会注意到此更改。这是为了避免与 Cython 相关的疑问。

(gh-25271)

自定义旧用户 dtype 所需的更改#

为了改进我们的 DTypes，不幸的是，必须打破 ABI，这需要对使用 PyArray_RegisterDataType 注册的 dtype 进行一些更改。请参阅 PyArray_RegisterDataType 的文档，了解如何调整您的代码并实现与 1.x 和 2.x 的兼容性。

(gh-25792)

新的公共 DType API#

NEP 42 DType API 的 C 实现现已公开。虽然 DType API 已在 NumPy 中发布了几个版本，但只能在设置了特殊环境变量的会话中使用。现在可以使用新的 DType API 和用于导入 NumPy C API 的常规 import_array() 机制，在 NumPy 外部编写自定义 DType。

有关 API 的更多详细信息，请参阅 自定义数据类型。与任何新功能一样，请报告您在实现或使用新 DType 时遇到的任何错误。下游 C 代码（与 dtypes 交互）可能需要更新才能与新 DTypes 正确配合使用。

(gh-25754)

新的 C-API 导入函数#

我们现在已将 PyArray_ImportNumPyAPI 和 PyUFunc_ImportUFuncAPI 添加为静态内联函数，用于导入 NumPy C-API 表。新函数比 import_array 和 import_ufunc 有两个优点：

  • 它们会检查导入是否已执行，并且在未执行时开销很小，从而允许谨慎地添加它们（尽管在大多数情况下不推荐这样做）。

  • 旧机制是宏而不是函数，其中包含一个 return 语句。

PyArray_ImportNumPyAPI() 函数包含在 npy_2_compat.h 中，以便于向后移植。

(gh-25866)

通过函数访问结构化 dtype 信息#

现在必须通过同名的新函数（例如 PyDataType_NAMES）来访问 dtype 结构体字段 c_metadata、names、fields 和 subarray。直接访问字段无效，因为它们并非对所有 PyArray_Descr 实例都存在。保留了 metadata 字段，但仍建议使用宏版本。

(gh-25802)

描述符 elsize 和 alignment 访问#

除非仅使用 NumPy 2 支持进行编译，否则现在必须通过 PyDataType_ELSIZE、PyDataType_SET_ELSIZE 和 PyDataType_ALIGNMENT 来访问 elsize 和 alignment 字段。在描述符附加到数组的情况下，我们建议使用 PyArray_ITEMSIZE，因为它存在于所有 NumPy 版本中。有关更多信息，请参阅 PyArray_Descr 结构已更改。

(gh-25943)

NumPy 2.0 C API 移除#

  • 已删除 npy_interrupt.h 和相应的宏，如 NPY_SIGINT_ON。我们建议定期查询 PyErr_CheckSignals() 或 PyOS_InterruptOccurred()（目前这些确实需要持有 GIL）。

  • 已删除 noprefix.h 头文件。用带前缀的对应项（通常是添加的 NPY_ 或 npy_）替换丢失的符号。

    (gh-23919)

  • 已删除 PyUFunc_GetPyVals、PyUFunc_handlefperr 和 PyUFunc_checkfperr。如果需要，可以恢复一个向后兼容的新函数来引发浮点错误。移除原因：没有已知用户，并且这些函数将使 with np.errstate() 的修复变得更加困难。

    (gh-23922)

  • 已删除 numpy/old_defines.h，它是自 NumPy 1.7 起已弃用的 API 的一部分。这移除了 PyArray_CONSTANT 形式的宏。 replace_old_macros.sed 脚本可能有助于将其转换为 NPY_CONSTANT 版本。

    (gh-24011)

  • 已移除 ufunc 结构体的 legacy_inner_loop_selector 成员，以简化对调度系统的改进。没有已知用户会覆盖或直接访问此成员。

    (gh-24271)

  • 已删除 NPY_INTPLTR 以避免混淆（请参阅 intp 重定义）。

    (gh-24888)

  • 已移除高级索引 MapIter 及相关 API。（真正）公开的部分经过测试不充分，并且只有一个已知用户（Theano）。将其设为私有将简化对 ufunc.at 加速的改进，使高级索引更易于维护，并且对于将数组的最大维度增加到 64 很重要。如果您认为此 API 对您很重要，请告诉我们，以便我们共同找到解决方案。

    (gh-25138)

  • 已删除 NPY_MAX_ELSIZE 宏，因为它仅反映内置数字类型，并且不服务于内部目的。

    (gh-25149)

  • 已删除 PyArray_REFCNT 和 NPY_REFCOUNT。请使用 Py_REFCNT。

    (gh-25156)

  • PyArrayFlags_Type 和 PyArray_NewFlagsObject 以及 PyArrayFlagsObject 现在是私有的。没有已知的用例；如果需要，请使用 Python API。

  • 已删除 PyArray_MoveInto、PyArray_CastTo、PyArray_CastAnyTo，请使用 PyArray_CopyInto，如果绝对需要，则使用 PyArray_CopyAnyInto（后者执行扁平复制）。

  • 已删除 PyArray_FillObjectArray，它的唯一实际用途是实现 np.empty。创建一个新的空数组或使用 PyArray_FillWithScalar()（会 decref 现有对象）。

  • 已删除 PyArray_CompareUCS4 和 PyArray_CompareString。使用标准的 C 字符串比较函数。

  • 已删除 PyArray_ISPYTHON，因为它具有误导性，没有已知的用例，并且易于替换。

  • 已删除 PyArray_FieldNames，因为它不清楚它有什么用。它在某些可能的用例中也具有不正确的语义。

  • 已删除 PyArray_TypestrConvert，因为它似乎是误称，并且不太可能被任何人使用。如果您知道大小或仅限于几种类型，请直接显式使用它，否则通过 Python 字符串进行。

    (gh-25292)

  • 已删除 PyDataType_GetDatetimeMetaData，自 NumPy 1.7 起它实际上什么也没做。

    (gh-25802)

  • 已删除 PyArray_GetCastFunc。请注意，自定义旧用户 dtype 仍然可以提供 castfunc 作为其实现，但对其的任何访问都已移除。原因在于 NumPy 多年来从未在内部使用过它们。如果您使用简单的数字类型，请直接使用 C 转换。如果您需要替代方案，请告诉我们，以便我们可以创建新的 API，例如 PyArray_CastBuffer()，它可以使用旧的或新的转换函数，具体取决于 NumPy 版本。

    (gh-25161)

新功能#

np.add 已扩展为可与 unicode 和 bytes dtypes 一起使用。#

新的 bitwise_count 函数#

此新函数计算数字中 1 的位数。bitwise_count 可用于所有 numpy 整数类型和类似整数的对象。

>>> a = np.array([2**i - 1 for i in range(16)])
>>> np.bitwise_count(a)
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
      dtype=uint8)

(gh-19355)

macOS Accelerate 支持，包括 ILP64#

已添加对 macOS 13.3 中更新的 Accelerate BLAS/LAPACK 库的支持，包括 ILP64（64 位整数）支持。这带来了 arm64 支持，并显著提高了常用线性代数运算的性能，最高可达 10 倍。当在构建时选择 Accelerate，或者未明确选择 BLAS 库时，如果可用，将自动使用 13.3+ 版本。

(gh-24053)

还提供二进制 wheel。在 macOS >=14.0 上，从 PyPI 安装 NumPy 的用户将获得针对 Accelerate 构建的 wheel，而不是 OpenBLAS。

(gh-25255)

为 quantile 和 percentile 函数使用权重的选项#

现在 quantile、percentile、nanquantile 和 nanpercentile 中提供了 weights 关键字。只有 method="inverted_cdf" 支持权重。

(gh-24254)

改进的 CPU 优化跟踪#

提供了一种新的跟踪器机制，该机制能够跟踪 NumPy 库中每个优化函数（即使用硬件特定 SIMD 指令的函数）的启用目标。通过此增强功能，可以精确地监视已启用的 CPU 分派目标，用于分派的函数。

在新的命名空间 numpy.lib.introspect 中添加了一个名为 opt_func_info 的新函数，该函数提供了此跟踪功能。此函数允许您根据函数名称和数据类型签名检索有关已启用目标的信息。

(gh-24420)

为 f2py 新增 Meson 后端#

f2py 在编译模式下（即 f2py -c）现在接受 --backend meson 选项。这是 Python >=3.12 的默认选项。对于旧版本的 Python，f2py 仍将默认为 --backend distutils。

为了在实际用例中支持这一点，在编译模式下，f2py 接受一个或多个 --dep 标志，该标志映射到 meson 后端的 dependency() 调用，在 distutils 后端则不起作用。

对于仅将 f2py 用作代码生成器的用户（即不使用 -c）没有变化。

(gh-24532)

bind(c) 对 f2py 的支持#

函数和子例程都可以用 bind(c) 进行注释。f2py 将处理正确的类型映射，并为其他 C 接口保留唯一的标签。

注意：bind(c, name = 'routine_name_other_than_fortran_routine') 根据设计，f2py 绑定不会考虑此选项，因为带有 name 的 bind(c) 旨在仅保证 C 和 Fortran 中的名称相同，而不是 Python 和 Fortran 中的名称。

(gh-24555)

为多个测试函数新增 strict 选项#

现在 assert_allclose、assert_equal 和 assert_array_less 中提供了 strict 关键字。将 strict=True 设置为 True 将禁用标量广播行为，并确保输入数组具有相同的数据类型。

(gh-24680, gh-24770, gh-24775)

添加 np.core.umath.find 和 np.core.umath.rfind UFuncs#

添加两个 find 和 rfind UFuncs，它们在 unicode 或字节字符串上运行，并用于 np.char。它们的操作方式类似于 str.find 和 str.rfind。

(gh-24868)

numpy.linalg 的 diagonal 和 trace#

numpy.linalg.diagonal 和 numpy.linalg.trace 已添加，它们是 numpy.diagonal 和 numpy.trace 的与数组 API 标准兼容的变体。它们在定义 2-D 子数组的默认轴选择上有所不同。

(gh-24887)

新增 long 和 ulong 数据类型#

numpy.long 和 numpy.ulong 已添加为映射到 C 的 long 和 unsigned long 的 NumPy 整数。在 NumPy 1.24 之前，numpy.long 是 Python 的 int 的别名。

(gh-24922)

numpy.linalg 的 svdvals#

已添加 numpy.linalg.svdvals。它计算矩阵（或矩阵堆栈）的奇异值。执行 np.svdvals(x) 等同于调用 np.svd(x, compute_uv=False, hermitian=False)。此函数与数组 API 标准兼容。

(gh-24940)

新的 isdtype 函数#

添加了 numpy.isdtype，以提供一种符合数组 API 标准的分类 NumPy 数据类型的方法。

(gh-25054)

新的 astype 函数#

添加了 numpy.astype，以提供 numpy.ndarray.astype 方法的与数组 API 标准兼容的替代方案。

(gh-25079)

与数组 API 兼容的函数别名#

添加了 13 个现有函数的别名，以提高与数组 API 标准的兼容性。

  • 三角函数：acos、acosh、asin、asinh、atan、atanh、atan2。

  • 位运算：bitwise_left_shift、bitwise_invert、bitwise_right_shift。

  • 杂项：concat、permute_dims、pow。

  • numpy.linalg 中：tensordot、matmul。

(gh-25086)

新的 unique_* 函数#

添加了 unique_all、unique_counts、unique_inverse 和 unique_values 函数。它们提供了 unique 的功能，具有不同的标志集。它们与数组 API 标准兼容，并且由于它们返回的数组数量不取决于输入参数的值，因此更容易成为 JIT 编译的目标。

(gh-25088)

ndarray 的矩阵转置支持#

NumPy 现在支持计算数组（或数组堆栈）的矩阵转置。矩阵转置等同于交换数组的最后两个轴。np.ndarray 和 np.ma.MaskedArray 现在都公开了 .mT 属性，并且有一个匹配的新 numpy.matrix_transpose 函数。

(gh-23762)

numpy.linalg 的与数组 API 兼容的函数#

为 numpy.linalg 添加了六个新函数和两个别名，以提高与数组 API 标准的兼容性。

var 和 std 的 correction 参数#

向 var 和 std 添加了 correction 参数，这是 ddof 的与数组 API 标准兼容的替代方案。由于两个参数的作用相似，因此一次只能提供其中一个。

(gh-25169)

ndarray.device 和 ndarray.to_device#

为 numpy.ndarray 添加了 ndarray.device 属性和 ndarray.to_device 方法，以实现数组 API 标准的兼容性。

此外，为以下函数添加了 device 关键字参数：asarray、arange、empty、empty_like、eye、full、full_like、linspace、ones、ones_like、zeros 和 zeros_like。

对于所有这些新参数，仅支持 device="cpu"。

(gh-25233)

NumPy 中添加了 StringDType#

我们添加了一种新的可变宽度 UTF-8 编码字符串数据类型，实现了“Python 字符串的 NumPy 数组”，包括对用户提供的缺失数据标记的支持。它旨在作为对象 dtype 的 Python 字符串数组和缺失数据标记的即插即用替代品。有关更多详细信息，请参阅 NEP 55 和 文档。

(gh-25347)

cholesky 和 pinv 的新关键字参数#

分别向 numpy.linalg.cholesky 和 numpy.linalg.pinv 添加了 upper 和 rtol 关键字参数，以提高数组 API 标准的兼容性。

对于 pinv，如果未指定 rcond 或 rtol，则使用 rcond 的默认值。我们计划在未来弃用并删除 rcond。

(gh-25388)

sort、argsort 和 linalg.matrix_rank 的新关键字参数#

添加了新的关键字参数以提高数组 API 标准的兼容性。

(gh-25437)

字符串 ufunc 的新 numpy.strings 命名空间#

NumPy 现在将一些字符串操作实现为 ufuncs。旧的 np.char 命名空间仍然可用，并且在可能的情况下，该命名空间中的字符串操作函数已更新为使用新的 ufuncs，从而大大提高了它们的性能。

在可能的情况下，我们建议更新代码以使用 np.strings 中的函数，而不是 np.char。未来我们可能会弃用 np.char 以支持 np.strings。

(gh-25463)

numpy.fft 对不同精度和原地计算的支持#

numpy.fft 中的各种 FFT 例程现在根据输入精度以浮点、双精度或长双精度进行本地计算，而不是始终以双精度计算。因此，单精度计算的精度将降低，长双精度计算的精度将提高。输出数组的数据类型将相应调整。

此外，所有 FFT 例程都增加了 out 参数，可用于原地计算。

(gh-25536)

configtool 和 pkg-config 支持#

现在有一个新的 numpy-config CLI 脚本，可以查询 NumPy 版本和使用 NumPy C API 所需的编译标志。这将使构建系统能够更好地支持将 NumPy 作为依赖项。此外，Numpy 现在包含一个 numpy.pc pkg-config 文件。为了找到其位置以与 PKG_CONFIG_PATH 一起使用，请使用 numpy-config --pkgconfigdir。

(gh-25730)

主命名空间中的数组 API 标准支持#

主 numpy 命名空间现在支持数组 API 标准。有关详细信息，请参阅 数组 API 标准兼容性。

(gh-25911)

改进#

字符串现在受 any、all 和逻辑 ufuncs 支持。#

memmap 的 shape 参数支持整数序列#

numpy.memmap 现在可以使用任何整数序列作为 shape 参数来创建，例如整数列表或 NumPy 数组。以前，只有元组和 int 类型可以在不引发错误的情况下使用。

(gh-23729)

errstate 现在更快且上下文安全#

numpy.errstate 上下文管理器/装饰器现在更快且更安全。以前，它不是上下文安全的，并且存在（罕见的）线程安全问题。

(gh-23936)

AArch64 的快速排序速度通过使用 Highway 的 VQSort 得到提高#

Google Highway 库的首次引入，在 AArch64 上使用 VQSort。某些情况下，执行时间最多可提高 16 倍，有关基准测试结果，请参阅 PR。将来会扩展到其他平台。

(gh-24018)

复数类型 - 底层 C 类型更改#

  • NumPy 所有复数类型的底层 C 类型已更改为使用 C99 复数类型。

  • 虽然此更改不影响复数类型的内存布局，但它改变了用于直接检索或写入复数实部或虚部的 API，因为直接字段访问（如 c.real 或 c.imag）不再是选项。您现在可以使用 numpy/npy_math.h 中提供的实用程序来执行这些操作，如下所示。

    npy_cdouble c;
npy_csetreal(&c, 1.0);
npy_csetimag(&c, 0.0);
printf("%d + %di\n", npy_creal(c), npy_cimag(c));

  • 为了简化跨版本兼容性，已添加等效宏和兼容层，下游包可以使用它们来继续支持 NumPy 1.x 和 2.x。有关更多信息，请参阅 对复数​​的支持。

  • numpy/npy_common.h 现在包含 complex.h，这意味着 complex 现在是一个保留关键字。

(gh-24085)

对 f2py 的 iso_c_binding 支持和改进的公用块#

以前，用户必须定义自己的自定义 f2cmap 文件才能使用 Fortran2003 iso_c_binding 内建模块定义的类型映射。现在 f2py 原生地支持这些类型映射。

(gh-24555)

f2py 现在处理具有来自模块的 kind 规范的 common 块。这进一步扩展了 iso_fortran_env 和 iso_c_binding 等内建模块的可用性。

(gh-25186)

自动对 assert_equal 等函数中的第三个参数调用 str#

现在会自动对 assert_equal 等函数中的第三个参数调用 str。这样它就模仿了内建的 assert 语句，其中 assert_equal(a, b, obj) 的工作方式类似于 assert a == b, obj。

(gh-24877)

isclose、allclose 中对数组状 atol/rtol 的支持#

isclose 和 allclose 中的 atol 和 rtol 关键字现在同时接受标量和数组。如果给定数组，它必须广播到前两个数组参数的形状。

(gh-24878)

测试函数中一致的失败消息#

以前，一些 numpy.testing 断言打印的消息将实际结果和期望结果称为 x 和 y。现在，这些值一致地称为 ACTUAL 和 DESIRED。

(gh-24931)

n-D FFT 变换允许 s[i] == -1#

fftn、ifftn、rfftn、irfftn、fft2、ifft2、rfft2 和 irfft2 函数现在使用沿轴 i 的整个输入数组（如果 s[i] == -1），这与数组 API 标准一致。

(gh-25495)

为有限 API 保护 PyArrayScalar_VAL 和 PyUnicodeScalarObject#

PyUnicodeScalarObject 包含一个 PyUnicodeObject，在使用 Py_LIMITED_API 时不可用。添加了保护来隐藏它，从而也隐藏了 PyArrayScalar_VAL 宏。

(gh-25531)

更改#

  • np.gradient() 现在返回一个元组而不是列表，使返回值不可变。

    (gh-23861)

  • 由于 np.errstate 完全是上下文安全和线程安全的，现在只能进入一次。

  • np.setbufsize 现在与 np.errstate() 关联：离开 np.errstate 上下文也会重置 bufsize。

    (gh-23936)

  • 引入了一个新的公共 np.lib.array_utils 子模块，其中包含三个函数：byte_bounds（从 np.lib.utils 移动）、normalize_axis_tuple 和 normalize_axis_index。

    (gh-24540)

  • 将 numpy.bool 引入为 NumPy 布尔数据类型的新规范名称，并将 numpy.bool_ 设为其别名。请注意，直到 NumPy 1.24，np.bool 都是 Python 内建 bool 的别名。新名称有助于实现数组 API 标准兼容性，并且名称更直观。

    (gh-25080)

  • 以前，dtype.flags 值存储为有符号整数。这意味着对齐的数据类型结构标志会导致设置负标志（-128 而不是 128）。此标志现在存储为无符号（正数）。手动检查标志的代码可能需要调整。这可能包括使用 Cython 0.29.x 编译的代码。

    (gh-25816)

NumPy 标量的表示已更改#

根据 NEP 51，标量表示已更新，以包含类型信息，避免与 Python 标量混淆。

标量现在打印为 np.float64(3.0)，而不是仅仅 3.0。这可能会扰乱存储数字表示（例如，存储到文件）的工作流程，使其更难读取。它们应存储为显式字符串，例如使用 str() 或 f"{scalar!s}"。暂时，受影响的用户可以使用 np.set_printoptions(legacy="1.25") 来获得旧行为（可能有一些例外）。如果测试了代码片段，下游项目的文档可能需要进行更大更新。我们正在为 doctest-plus 开发工具以方便更新。

(gh-22449)

NumPy 字符串的真值性已更改#

NumPy 字符串以前在定义字符串为 True 还是 False 时不一致，并且定义与 Python 使用的不匹配。字符串现在被视为 True 当它们非空时，以及 False 当它们为空时。这改变了以下不同情况。

  • 从字符串到布尔值的转换以前大致等同于 string_array.astype(np.int64).astype(bool)，这意味着只有有效的整数才能被转换。现在，字符串 "0" 将被视为 True，因为它不是空的。如果需要旧的行为，可以使用上述步骤（先转换为整数）或 string_array == "0"（如果输入仅为 0 或 1）。要在旧版 NumPy 中获得新结果，请使用 string_array != ""。

  • np.nonzero(string_array) 以前会忽略空格，因此仅包含空格的字符串被视为 False。现在，空格被视为 True。

此更改不影响 np.loadtxt、np.fromstring 或 np.genfromtxt。前两者仍使用整数定义，而 genfromtxt 继续匹配 "true"（忽略大小写）。但是，如果 np.bool_ 用作转换器，则结果将发生变化。

此更改确实会影响 np.fromregex，因为它使用直接赋值。

(gh-23871)

在 var 和 std 函数中添加了 mean 关键字参数#

通常，当需要标准差时，也需要均值。方差和均值也是如此。到目前为止，均值将被计算两次。此更改针对 var 和 std 函数引入的更改允许将预先计算的均值作为关键字参数传入。有关详细信息和说明速度提升的示例，请参阅文档字符串。

(gh-24126)

构造时包含时区信息的 datetime64 弃用警告已移除#

现在，每当在提供的日期时间字符串中包含时区时，numpy.datetime64 方法将发出 UserWarning 而不是 DeprecationWarning。

(gh-24193)

64 位 Windows 上的默认整数 dtype 为 64 位#

在所有 64 位系统上，NumPy 的默认整数现在为 64 位，因为 Windows 上历史悠久的 32 位默认值是一个常见的错误来源。大多数用户应该不会注意到此变化。主要问题可能出现在与 C 等编译语言编写的库交互的代码中。有关更多信息，请参阅 Windows 默认整数。

(gh-24224)

将 numpy.core 重命名为 numpy._core#

访问 numpy.core 现在会发出 DeprecationWarning。实际上，我们发现 numpy.core 的大多数下游用法是为了访问主 numpy 命名空间中可用的功能。如果出于某种原因，您正在使用 numpy.core 中主 numpy 命名空间中不可用的功能，这意味着您可能正在使用 NumPy 的内部私有功能。您仍然可以通过 numpy._core 访问这些内部功能，而不会出现弃用警告，但我们不对 NumPy 内部功能提供任何向后兼容性保证。如果您认为存在错误并且某些内容应该公开，请提交一个 issue。

(gh-24634)

已移除通过 NPY_RELAXED_STRIDES_DEBUG 环境变量或 -Drelaxed-strides-debug config-settings 标志启用的“宽松步幅”调试构建选项。

(gh-24717)

重新定义 np.intp/np.uintp（几乎不会改变）#

由于这些类型的实际使用几乎总是与 size_t/Py_ssize_t 的使用相匹配，因此现在在 C 中定义为如此。以前，它与 intptr_t 和 uintptr_t 匹配，这通常是细微错误的。由于这些类型的尺寸仅在非常小众的平台上才不同，因此这对于绝大多数机器没有影响。

但是，这意味着

  • 指针不再一定能放入 intp 类型数组中。不过，仍然可以使用 p 和 P 字符代码。

  • 通过 PyArray_DescrFromType('p')，仍然可以跨平台地创建 intptr_t 或 uintptr_t 类型数组。

  • 引入了新的字符代码 nN。

  • 现在，在解析为 npy_intp 类型参数时，使用 Python C-API 函数是正确的。

(gh-24888)

numpy.fft.helper 已设为私有#

numpy.fft.helper 已重命名为 numpy.fft._helper，以表明它是一个私有子模块。所有由它导出的公共函数都应从 numpy.fft 访问。

(gh-24945)

numpy.linalg.linalg 已设为私有#

numpy.linalg.linalg 已重命名为 numpy.linalg._linalg，以表明它是一个私有子模块。所有由它导出的公共函数都应从 numpy.linalg 访问。

(gh-24946)

越界的轴与 axis=None 不同#

在某些情况下，axis=32 或连接（concatenate）时任何较大的值都与 axis=None 相同。除了 concatenate 外，这已被弃用。任何越界的轴值现在都会导致错误，请确保使用 axis=None。

(gh-25149)

对 array 和 asarray 构造函数新增了 copy 关键字参数含义#

现在 numpy.array 和 numpy.asarray 支持 copy 参数的三个值：

  • None - 只有在必要时才会复制。

  • True - 始终复制。

  • False - 绝不复制。如果需要复制，将引发 ValueError。

由于 False 现在在需要复制时会引发异常，因此其含义已更改。

(gh-25168)

特殊方法 __array__ 现在接受 copy 关键字参数#

在 copy 被设置为非默认值的情况下（例如，在调用 np.asarray(some_object, copy=False) 时），NumPy 会将 copy 传递给特殊方法 __array__。目前，如果在此之后引发了意外的关键字参数错误，NumPy 将发出警告并尝试在不带 copy 关键字参数的情况下重试。实现实现 __array__ 协议的对象应该接受一个 copy 关键字参数，其含义与传递给 numpy.array 或 numpy.asarray 时相同。

(gh-25168)

清理使用逗号的字符串初始化 numpy.dtype#

带有逗号的字符串的解释略有改变，即尾随逗号现在将始终创建一个结构化 dtype。例如，以前 np.dtype("i") 和 np.dtype("i,") 被视为相同，而现在 np.dtype("i,") 将创建一个结构化 dtype，其中包含一个字段。这类似于 np.dtype("i,i") 创建一个包含两个字段的结构化 dtype，并使行为与预期的元组行为一致。

同时，使用括在括号中的单个数字来表示子数组形状（例如 np.dtype("(2)i,")）已被弃用。相反，应该使用 np.dtype("(2,)i") 或 np.dtype("2i")。最终，使用括号中的数字将引发异常，就像没有逗号的初始化一样（例如 np.dtype("(2)i")）。

(gh-25434)

计算复数符号的方式改变#

遵循数组 API 标准，复数符号现在计算为 z / |z|（而不是取实部符号，除非实部为零，此时返回虚部符号的相当不合逻辑的情况）。与实数一样，如果 z==0，则返回零。

(gh-25441)

返回数组列表的函数的返回类型#

返回 ndarray 列表的函数已更改为返回 ndarray 元组。在返回数组序列时始终返回元组，这使得 JIT 编译器（如 Numba）以及在某些情况下静态类型检查器更容易支持这些函数。更改的函数包括：atleast_1d、atleast_2d、atleast_3d、broadcast_arrays、meshgrid、ogrid、histogramdd。

多维输入时 np.unique return_inverse 的形状#

当 return_inverse=True 时，将多维输入传递给 np.unique，现在 unique_inverse 输出的形状使得可以使用 np.take(unique, unique_inverse) 在 axis=None 时直接重建输入，否则使用 np.take_along_axis(unique, unique_inverse, axis=axis)。

注意

此更改在 2.0.1 中被撤销，axis=None 除外。正确的重建始终是 np.take(unique, unique_inverse, axis=axis)。当需要支持 2.0.0 时，请将 unique_inverse.reshape(-1) 添加到代码中。

(gh-25553, gh-25570)

对象数组的 any 和 all 返回布尔值#

对于对象数组，any 和 all 函数和方法现在也返回布尔值。以前，它们会进行约简，其行为类似于 Python 的 or 和 and 运算符，这些运算符会评估为其中一个参数。您可以使用 np.logical_or.reduce 和 np.logical_and.reduce 来实现以前的行为。

(gh-25712)

np.can_cast 不能用于 Python int、float 或 complex#

现在不能再将 Python int、float 或 complex 实例用于 np.can_cast。这是因为 NEP 50 意味着 can_cast 的结果不得依赖于传入的值。不幸的是，对于 Python 标量，是否应将转换视为 "same_kind" 或 "safe" 可能取决于上下文和值，因此目前尚未实现。在某些情况下，您可能需要添加一个特定路径：if type(obj) in (int, float, complex): ...。

(gh-26393)

在此页面