NumPy 1.24.4 维护版发布解析Masked Array 展平顺序修复与 Windows 构建工具链演进【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpyNumPy 1.24.4 是紧随 1.24.3 之后发布的维护版本maintenance release面向 Python 3.8–3.11核心目的是修复 1.24.3 发布后被发现的 bug 与回归regression同时小幅改进文档与类型标注。本文以 doc/changelog/1.24.4-changelog.rst 为骨架结合仓库内源码、测试与 CI 配置逐条还原本次发布合并的 6 个 PR 的技术背景、修复原理与验证方式帮助读者理解 NumPy 维护版本的工作方式以及 masked array 内存布局与 Windows 工具链管理中的关键细节。一、发布概览一次典型的 bugfix 维护发布维护版本maintenance release是 NumPy 发布节奏中的常规组成部分主版本引入新特性补丁版本则在已冻结的功能范围内集中修复回归与缺陷通常不包含新功能、不改变公开 API 语义并尽量降低对下游用户的破坏风险。从 1.24.4 的变更清单见 doc/changelog/1.24.4-changelog.rst 与对应的 doc/source/release/1.24.4-notes.rst可以看出本次发布的两个主要方向功能正确性修复修复 masked array掩码数组ravel在A顺序下的错误构建/维护性改进Windows 构建中 rtools 工具链的版本固定与安装流程整理以及 dtypemetadata参数的文档与类型标注补全。本次共 4 位贡献者参与其中 Hongyang Peng 为首次贡献名单中带 标记共合并 6 个 PR。下表为 PR 类型分布PR类型主题#23720MAINT, BLDWindows 构建将 rtools 固定到 4.0 版本#23739BUG修复 1.24.x 分支检查本地文件的方法#23760MAINT复制 install-rtools 的 rtools 安装逻辑#23761BUG修复 masked arrayravel在 A及部分 K顺序下的问题#23890TYP, DOC为 dtype 的metadata参数补充标注与文档#23994MAINT更新 rtools 安装方式下文按功能修复与构建维护两条主线分别展开。二、核心功能修复Masked Array 的ravel顺序语义2.1 问题背景ravel的四种顺序MaskedArray.ravel用于将掩码数组展平为一维视图其order参数与ndarray.ravel保持一致取值含义如下见 numpy/ma/core.py 中的 docstringCC 风格行主序最后一维索引变化最快FFortran 风格列主序第一维索引变化最快A若底层数组在内存中为 Fortran 连续contiguous则按F读取否则按C读取K按元素在内存中的实际出现顺序读取strides 为负时反转。由于掩码数组是数据 掩码的双数组结构ravel必须保证数据与掩码以相同的顺序展平否则展平后数据与掩码会错位导致filled()等操作返回错误结果。这正是本次修复的核心难点。2.2 修复前的缺陷数据与掩码的内存顺序不一致在 1.24.4 之前MaskedArray.ravel的实现大致为当用户传入A或K时直接透传给底层ndarray.ravel。问题在于掩码数组的_data与_mask两块内存的连续性C-contiguous 或 F-contiguous未必相同——例如数据按 C 顺序存放而掩码恰好是 F 连续的。此时按A语义数据会被按数据自身的连续方式展平而掩码若按掩码自身的连续方式展平两者顺序就不一致出现数据对不上掩码的错位 bug。2.3 修复方案显式统一数据与掩码的展平顺序修复后的实现见 numpy/ma/core.py做了两件事# The order of _data and _mask could be different (it shouldnt be # normally). Passing order K or A would be incorrect. # So we ignore the mask memory order. # TODO: We dont actually support K, so use A instead. We could # try to guess this correct by sorting strides or deprecate. if order in kKaA: order F if self._data.flags.fnc else C r ndarray.ravel(self._data, orderorder).view(type(self)) r._update_from(self) if self._mask is not nomask: r._mask ndarray.ravel(self._mask, orderorder).reshape(r.shape) else: r._mask nomask return r关键点在于统一顺序决策源当收到K或A时不再分别按_data和_mask各自的连续属性独立判断而是只看_data的连续标志self._data.flags.fnc即 Fortran 连续则取F否则取C并把该顺序同时用于_data与_mask的展平从根源上杜绝错位掩码形状修正展平后掩码用reshape(r.shape)对齐到结果形状保留元信息通过r._update_from(self)保持fill_value等属性并通过view(type(self))维持掩码数组类型。代码注释也坦诚地标出了遗留问题K目前并未真正按内存顺序实现而是降级为A语义order F if ... else C并标注了TODO——这属于已知的后续改进空间而不是本次发布声称支持的完整K语义。2.4 测试验证回归测试如何锁定该行为本次修复配套的回归测试位于 numpy/ma/tests/test_core.py通过参数化穷举顺序与数据布局组合来验证数据与掩码永远同序展平pytest.mark.parametrize(order, AKCF) pytest.mark.parametrize(data_order, CF) def test_ravel_order(self, order, data_order): # Ravelling must ravel mask and data in the same order always to avoid # misaligning the two in the ravel result. arr np.ones((5, 10), orderdata_order) arr[0, :] 0 mask np.ones((10, 5), dtypebool, orderdata_order).T mask[0, :] False x array(arr, maskmask) assert x._data.flags.fnc ! x._mask.flags.fnc assert (x.filled(0) 0).all() raveled x.ravel(order) assert (raveled.filled(0) 0).all() # NOTE: Can be wrong if arr order is neither C nor F and orderK assert_array_equal(arr.ravel(order), x.ravel(order)._data)该测试刻意构造_data与_mask连续属性相反的数组assert x._data.flags.fnc ! x._mask.flags.fnc这正是旧实现会出错、新实现必须保证正确的情形。assert (raveled.filled(0) 0).all()直接以填充后的结果正确这一用户可观察行为为断言语义清晰。更早的基础用例见同文件 test_ravel覆盖了掩码形状、small_mask保留、fill_value保留与C/F顺序等常规路径。从源码结构看ravel之外掩码数组的reshapenumpy/ma/core.py也遵循类似数据、掩码同步变换的约束说明双数组一致性问题贯穿于掩码数组的所有形状变换操作中本次修复为其他操作提供了可参考的模式。三、文档与类型标注dtypemetadata参数正式见诸文档PR #23890类型为 TYP, DOC为numpy.dtype的metadata参数补充了类型标注与官方文档。在此之前dtype 的元数据功能虽然长期存在并被部分项目使用但从未被正式文档化。在 numpy/_core/_add_newdocs.py 中本次新增的文档给出了权威定义metadataNone或只读字典mappingproxy。可在 dtype 创建时用任意字典设置。NumPy 目前没有统一的元数据传播机制——部分数组操作会保留元数据但其他操作并不保证。配套示例说明了其用法与行为边界 dt np.dtype(float, metadata{key: value}) dt.metadata[key] value arr np.array([1, 2, 3], dtypedt) arr.dtype.metadata mappingproxy({key: value}) # 相同 dtype 相加时保留元数据 (arr arr).dtype.metadata mappingproxy({key: value}) # 元数据不同的 dtype 相加时取先者的元数据 dt2 np.dtype(float, metadata{key2: value2}) arr2 np.array([3, 2, 1], dtypedt2) print((arr arr2).dtype.metadata) {key: value}文档同时包含明确的警告该特性长期未文档化、支持不完善部分传播行为未来可能变化。文档化不等于承诺稳定——metadata仍属于实验性、尽力而为的机制生产代码不应依赖其传播语义。从实现侧看dtype 的metadata在 C 层对应PyArray_Descr结构体中的PyObject *metadata字段见 numpy/_core/include/numpy/ndarraytypes.h并在 numpy/_core/_internal.py 中体现复制而非共享的传递策略。需要区分的是dtype 的用户元数据字典与 datetime64/timedelta64 的时间单位元数据_datetime_metadata_str见 numpy/_core/_dtype.py是两套完全不同的机制前者是用户自定义的通用键值对后者是时间精度与锚点的结构化描述阅读文档时不要混淆。四、构建维护Windows 下 rtools 工具链的版本固定与安装整理本次 6 个 PR 中有 3 个#23720、#23760、#23994与 Windows 构建工具链 rtools 相关足见 Windows 构建稳定性在维护版中的分量。4.1 背景为什么需要 rtoolsrtools 是 Windows 上提供 gcc/gfortran 等 GNU 工具链的环境。NumPy 在 Windows 上构建/测试时f2py 相关测试需要 gfortran 可执行文件在PATH中见 .github/workflows/windows.yml- name: Run test suite ${{ matrix.TEST_MODE }} run: | cd tools # Get a gfortran onto the path for f2py tests $env:PATH c:\\rtools45\\x86_64-w64-mingw32.static.posix\\bin;$env:PATHrtools 属于滚动更新的外部工具链其版本变化可能引入与 NumPy 不兼容的编译器行为导致 CI 偶发失败。维护版本中固定工具链版本是降低 CI 噪音、提升发布可复现性的常见手段。4.2 三个 PR 的演进脉络#23720MAINT, BLD将 rtools 固定到 4.0 版本避免上游 rtools 更新破坏 NumPy 1.24.x 分支的 Windows 构建#23760MAINT将 rtools 的安装方式调整为复制自官方install-rtools项目的安装脚本逻辑统一安装流程#23994MAINT继续更新 rtools 的安装步骤使其与当时工具链的最新布局保持一致。这类 PR 不会改变 NumPy 的运行时行为但保证了 1.24.x 分支在持续集成中的可构建、可测试性是维护版发布质量的基石。需要说明的是当前仓库主分支的 Windows CI 已演进出更细化的构建参数如spin config-openblas、-Csetup-args--vsenv等见 .github/workflows/windows.ymlrtools 的具体安装细节在不同版本分支间存在差异上述 PR 描述的是 1.24.x 发布周期内的状态。4.3 剩余的 BUG 修复#23739PR #23739BUG修复了 1.24.x 分支中检查本地文件的方法存在的缺陷。它属于发布流程/脚本层面的正确性问题与运行时库无关其目标是确保发布打包时对本地文件的校验逻辑正确工作。从仓库现状看发布相关的文件校验逻辑分布在 tools 目录如 tools/check_installed_files.py中但该 PR 针对的具体代码在 1.24.x 发布分支内当前主分支已不保留完全相同的实现。五、升级建议与维护版使用要点结合 1.24.4 的修复内容可以总结出以下实用要点受 masked arrayA/K顺序影响的项目应优先升级如果代码中对掩码数组调用x.ravel(orderA)或依赖filled()结果的展平逻辑1.24.4 之前可能存在数据/掩码错位风险。升级后可通过numpy.ma.tests.test_core.py中的test_ravel_order用例验证行为。需要注意K在当前实现下仍以A语义处理属于已知限制。dtypemetadata可用但需谨慎可在 dtype 创建时附带元数据np.dtype(float, metadata{...})并在部分操作中保留但传播语义无保证不应用于关键业务逻辑。构建侧改进不影响运行时rtools 相关改动仅影响 Windows CI 与发布流程终端用户无需感知但提示了在 1.24.x 分支上自行从源码构建时建议采用固定版本的 rtools 4.0 以获得可复现的构建环境。Python 版本范围1.24.4 支持 Python 3.8–3.11见 doc/source/release/1.24.4-notes.rst使用更高 Python 版本的环境应选择更新的 NumPy 主版本。六、从维护版看待 NumPy 的发布工程回看 1.24.4 的 6 个 PR——2 个运行时 bug 修复其中 1 个为文档/标注、3 个构建维护、1 个流程修复——可以看到 NumPy 维护版的典型画像规模小、聚焦、以回归修复为主、兼有构建稳定性的持续投入。掩码数组展平顺序的修复体现了双数组结构下数据与掩码必须同序变换这一核心设计约束rtools 的固定与更新则展示了开源项目对 CI 工具链漂移的系统性管理。对于希望深入 NumPy 内部或参与贡献的读者从numpy/ma/core.py的ravel/reshape实现出发结合numpy/ma/tests/test_core.py的参数化测试是一条低门槛且高信息密度的学习路径。【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
NumPy 1.24.4 维护版发布解析：Masked Array 展平顺序修复与 Windows 构建工具链演进
NumPy 1.24.4 维护版发布解析Masked Array 展平顺序修复与 Windows 构建工具链演进【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpyNumPy 1.24.4 是紧随 1.24.3 之后发布的维护版本maintenance release面向 Python 3.8–3.11核心目的是修复 1.24.3 发布后被发现的 bug 与回归regression同时小幅改进文档与类型标注。本文以 doc/changelog/1.24.4-changelog.rst 为骨架结合仓库内源码、测试与 CI 配置逐条还原本次发布合并的 6 个 PR 的技术背景、修复原理与验证方式帮助读者理解 NumPy 维护版本的工作方式以及 masked array 内存布局与 Windows 工具链管理中的关键细节。一、发布概览一次典型的 bugfix 维护发布维护版本maintenance release是 NumPy 发布节奏中的常规组成部分主版本引入新特性补丁版本则在已冻结的功能范围内集中修复回归与缺陷通常不包含新功能、不改变公开 API 语义并尽量降低对下游用户的破坏风险。从 1.24.4 的变更清单见 doc/changelog/1.24.4-changelog.rst 与对应的 doc/source/release/1.24.4-notes.rst可以看出本次发布的两个主要方向功能正确性修复修复 masked array掩码数组ravel在A顺序下的错误构建/维护性改进Windows 构建中 rtools 工具链的版本固定与安装流程整理以及 dtypemetadata参数的文档与类型标注补全。本次共 4 位贡献者参与其中 Hongyang Peng 为首次贡献名单中带 标记共合并 6 个 PR。下表为 PR 类型分布PR类型主题#23720MAINT, BLDWindows 构建将 rtools 固定到 4.0 版本#23739BUG修复 1.24.x 分支检查本地文件的方法#23760MAINT复制 install-rtools 的 rtools 安装逻辑#23761BUG修复 masked arrayravel在 A及部分 K顺序下的问题#23890TYP, DOC为 dtype 的metadata参数补充标注与文档#23994MAINT更新 rtools 安装方式下文按功能修复与构建维护两条主线分别展开。二、核心功能修复Masked Array 的ravel顺序语义2.1 问题背景ravel的四种顺序MaskedArray.ravel用于将掩码数组展平为一维视图其order参数与ndarray.ravel保持一致取值含义如下见 numpy/ma/core.py 中的 docstringCC 风格行主序最后一维索引变化最快FFortran 风格列主序第一维索引变化最快A若底层数组在内存中为 Fortran 连续contiguous则按F读取否则按C读取K按元素在内存中的实际出现顺序读取strides 为负时反转。由于掩码数组是数据 掩码的双数组结构ravel必须保证数据与掩码以相同的顺序展平否则展平后数据与掩码会错位导致filled()等操作返回错误结果。这正是本次修复的核心难点。2.2 修复前的缺陷数据与掩码的内存顺序不一致在 1.24.4 之前MaskedArray.ravel的实现大致为当用户传入A或K时直接透传给底层ndarray.ravel。问题在于掩码数组的_data与_mask两块内存的连续性C-contiguous 或 F-contiguous未必相同——例如数据按 C 顺序存放而掩码恰好是 F 连续的。此时按A语义数据会被按数据自身的连续方式展平而掩码若按掩码自身的连续方式展平两者顺序就不一致出现数据对不上掩码的错位 bug。2.3 修复方案显式统一数据与掩码的展平顺序修复后的实现见 numpy/ma/core.py做了两件事# The order of _data and _mask could be different (it shouldnt be # normally). Passing order K or A would be incorrect. # So we ignore the mask memory order. # TODO: We dont actually support K, so use A instead. We could # try to guess this correct by sorting strides or deprecate. if order in kKaA: order F if self._data.flags.fnc else C r ndarray.ravel(self._data, orderorder).view(type(self)) r._update_from(self) if self._mask is not nomask: r._mask ndarray.ravel(self._mask, orderorder).reshape(r.shape) else: r._mask nomask return r关键点在于统一顺序决策源当收到K或A时不再分别按_data和_mask各自的连续属性独立判断而是只看_data的连续标志self._data.flags.fnc即 Fortran 连续则取F否则取C并把该顺序同时用于_data与_mask的展平从根源上杜绝错位掩码形状修正展平后掩码用reshape(r.shape)对齐到结果形状保留元信息通过r._update_from(self)保持fill_value等属性并通过view(type(self))维持掩码数组类型。代码注释也坦诚地标出了遗留问题K目前并未真正按内存顺序实现而是降级为A语义order F if ... else C并标注了TODO——这属于已知的后续改进空间而不是本次发布声称支持的完整K语义。2.4 测试验证回归测试如何锁定该行为本次修复配套的回归测试位于 numpy/ma/tests/test_core.py通过参数化穷举顺序与数据布局组合来验证数据与掩码永远同序展平pytest.mark.parametrize(order, AKCF) pytest.mark.parametrize(data_order, CF) def test_ravel_order(self, order, data_order): # Ravelling must ravel mask and data in the same order always to avoid # misaligning the two in the ravel result. arr np.ones((5, 10), orderdata_order) arr[0, :] 0 mask np.ones((10, 5), dtypebool, orderdata_order).T mask[0, :] False x array(arr, maskmask) assert x._data.flags.fnc ! x._mask.flags.fnc assert (x.filled(0) 0).all() raveled x.ravel(order) assert (raveled.filled(0) 0).all() # NOTE: Can be wrong if arr order is neither C nor F and orderK assert_array_equal(arr.ravel(order), x.ravel(order)._data)该测试刻意构造_data与_mask连续属性相反的数组assert x._data.flags.fnc ! x._mask.flags.fnc这正是旧实现会出错、新实现必须保证正确的情形。assert (raveled.filled(0) 0).all()直接以填充后的结果正确这一用户可观察行为为断言语义清晰。更早的基础用例见同文件 test_ravel覆盖了掩码形状、small_mask保留、fill_value保留与C/F顺序等常规路径。从源码结构看ravel之外掩码数组的reshapenumpy/ma/core.py也遵循类似数据、掩码同步变换的约束说明双数组一致性问题贯穿于掩码数组的所有形状变换操作中本次修复为其他操作提供了可参考的模式。三、文档与类型标注dtypemetadata参数正式见诸文档PR #23890类型为 TYP, DOC为numpy.dtype的metadata参数补充了类型标注与官方文档。在此之前dtype 的元数据功能虽然长期存在并被部分项目使用但从未被正式文档化。在 numpy/_core/_add_newdocs.py 中本次新增的文档给出了权威定义metadataNone或只读字典mappingproxy。可在 dtype 创建时用任意字典设置。NumPy 目前没有统一的元数据传播机制——部分数组操作会保留元数据但其他操作并不保证。配套示例说明了其用法与行为边界 dt np.dtype(float, metadata{key: value}) dt.metadata[key] value arr np.array([1, 2, 3], dtypedt) arr.dtype.metadata mappingproxy({key: value}) # 相同 dtype 相加时保留元数据 (arr arr).dtype.metadata mappingproxy({key: value}) # 元数据不同的 dtype 相加时取先者的元数据 dt2 np.dtype(float, metadata{key2: value2}) arr2 np.array([3, 2, 1], dtypedt2) print((arr arr2).dtype.metadata) {key: value}文档同时包含明确的警告该特性长期未文档化、支持不完善部分传播行为未来可能变化。文档化不等于承诺稳定——metadata仍属于实验性、尽力而为的机制生产代码不应依赖其传播语义。从实现侧看dtype 的metadata在 C 层对应PyArray_Descr结构体中的PyObject *metadata字段见 numpy/_core/include/numpy/ndarraytypes.h并在 numpy/_core/_internal.py 中体现复制而非共享的传递策略。需要区分的是dtype 的用户元数据字典与 datetime64/timedelta64 的时间单位元数据_datetime_metadata_str见 numpy/_core/_dtype.py是两套完全不同的机制前者是用户自定义的通用键值对后者是时间精度与锚点的结构化描述阅读文档时不要混淆。四、构建维护Windows 下 rtools 工具链的版本固定与安装整理本次 6 个 PR 中有 3 个#23720、#23760、#23994与 Windows 构建工具链 rtools 相关足见 Windows 构建稳定性在维护版中的分量。4.1 背景为什么需要 rtoolsrtools 是 Windows 上提供 gcc/gfortran 等 GNU 工具链的环境。NumPy 在 Windows 上构建/测试时f2py 相关测试需要 gfortran 可执行文件在PATH中见 .github/workflows/windows.yml- name: Run test suite ${{ matrix.TEST_MODE }} run: | cd tools # Get a gfortran onto the path for f2py tests $env:PATH c:\\rtools45\\x86_64-w64-mingw32.static.posix\\bin;$env:PATHrtools 属于滚动更新的外部工具链其版本变化可能引入与 NumPy 不兼容的编译器行为导致 CI 偶发失败。维护版本中固定工具链版本是降低 CI 噪音、提升发布可复现性的常见手段。4.2 三个 PR 的演进脉络#23720MAINT, BLD将 rtools 固定到 4.0 版本避免上游 rtools 更新破坏 NumPy 1.24.x 分支的 Windows 构建#23760MAINT将 rtools 的安装方式调整为复制自官方install-rtools项目的安装脚本逻辑统一安装流程#23994MAINT继续更新 rtools 的安装步骤使其与当时工具链的最新布局保持一致。这类 PR 不会改变 NumPy 的运行时行为但保证了 1.24.x 分支在持续集成中的可构建、可测试性是维护版发布质量的基石。需要说明的是当前仓库主分支的 Windows CI 已演进出更细化的构建参数如spin config-openblas、-Csetup-args--vsenv等见 .github/workflows/windows.ymlrtools 的具体安装细节在不同版本分支间存在差异上述 PR 描述的是 1.24.x 发布周期内的状态。4.3 剩余的 BUG 修复#23739PR #23739BUG修复了 1.24.x 分支中检查本地文件的方法存在的缺陷。它属于发布流程/脚本层面的正确性问题与运行时库无关其目标是确保发布打包时对本地文件的校验逻辑正确工作。从仓库现状看发布相关的文件校验逻辑分布在 tools 目录如 tools/check_installed_files.py中但该 PR 针对的具体代码在 1.24.x 发布分支内当前主分支已不保留完全相同的实现。五、升级建议与维护版使用要点结合 1.24.4 的修复内容可以总结出以下实用要点受 masked arrayA/K顺序影响的项目应优先升级如果代码中对掩码数组调用x.ravel(orderA)或依赖filled()结果的展平逻辑1.24.4 之前可能存在数据/掩码错位风险。升级后可通过numpy.ma.tests.test_core.py中的test_ravel_order用例验证行为。需要注意K在当前实现下仍以A语义处理属于已知限制。dtypemetadata可用但需谨慎可在 dtype 创建时附带元数据np.dtype(float, metadata{...})并在部分操作中保留但传播语义无保证不应用于关键业务逻辑。构建侧改进不影响运行时rtools 相关改动仅影响 Windows CI 与发布流程终端用户无需感知但提示了在 1.24.x 分支上自行从源码构建时建议采用固定版本的 rtools 4.0 以获得可复现的构建环境。Python 版本范围1.24.4 支持 Python 3.8–3.11见 doc/source/release/1.24.4-notes.rst使用更高 Python 版本的环境应选择更新的 NumPy 主版本。六、从维护版看待 NumPy 的发布工程回看 1.24.4 的 6 个 PR——2 个运行时 bug 修复其中 1 个为文档/标注、3 个构建维护、1 个流程修复——可以看到 NumPy 维护版的典型画像规模小、聚焦、以回归修复为主、兼有构建稳定性的持续投入。掩码数组展平顺序的修复体现了双数组结构下数据与掩码必须同序变换这一核心设计约束rtools 的固定与更新则展示了开源项目对 CI 工具链漂移的系统性管理。对于希望深入 NumPy 内部或参与贡献的读者从numpy/ma/core.py的ravel/reshape实现出发结合numpy/ma/tests/test_core.py的参数化测试是一条低门槛且高信息密度的学习路径。【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
