科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载本文是 NumPy 官方变更说明31771.c_api.rst的技术深度解读面向编写 C/Cython 扩展模块的开发者解释PyArray_StringDTypeObject为何在 free-threading 兼容的稳定 ABIabi3t下从可访问结构体变为不透明opaque结构体、这一变更带来的崩溃风险以及如何通过NpyString分配器 API 迁移现有代码。读完本文你将能识别 abi3t 构建中的 StringDType 字段访问陷阱并掌握唯一受支持的、可安全读写 StringDType 数据的 C API 用法。变更背景StringDType 与 abi3t 稳定 ABIStringDType是 NumPy 2.0 引入的可变长度字符串数据类型底层数据由打包的静态字符串npy_packed_static_string与堆分配器npy_string_allocator共同管理。在完整 ABI非 limited API构建中其描述符结构体PyArray_StringDTypeObject在公开头文件 ndarraytypes.h 中具有完整的字段定义扩展模块可以直接访问na_object、coerce、allocator等内部字段。abi3t 是 Python 的 free-threading 兼容稳定 ABI对应编译宏Py_TARGET_ABI3T常用于 Python 3.13t/3.14t 等自由线程解释器上的扩展构建。问题在于NumPy 2.5 在面向 abi3t 编译时PyArray_StringDTypeObject被意外地以完整结构体形态暴露给了扩展模块。正如变更说明所述这个暴露是偶然的accidentally并非设计承诺。变更内容结构体在 abi3t 下转为不透明本次变更对应 gh-31771的核心结论是PyArray_StringDTypeObject现在是一个不透明结构体任何以 abi3t 方式编译的扩展都无法再访问其字段。在公开头文件 ndarraytypes.h 中可以清晰地看到这一条件编译的实现#ifndef Py_TARGET_ABI3T typedef struct { PyArray_Descr_fields base; // The object representing a null value PyObject *na_object; // Flag indicating whether or not to coerce arbitrary objects to strings char coerce; // Flag indicating the na object is NaN-like char has_nan_na; // Flag indicating the na object is a string char has_string_na; // If nonzero, indicates that this instance is owned by an array already char array_owned; // The string data to use when a default string is needed npy_static_string default_string; // The name of the missing data object, if any npy_static_string na_name; // the allocator should only be directly accessed after // acquiring the allocator_lock and the lock should // be released immediately after the allocator is // no longer needed npy_string_allocator *allocator; } PyArray_StringDTypeObject; #else /* * Accessing StringDType instance fields is not supported under the abi3t * stable ABI. The NpyString allocator API still works with the opaque * struct: pass the descriptor object pointer, i.e. * NpyString_acquire_allocator((PyArray_StringDTypeObject *)descr). */ typedef struct PyArray_StringDTypeObject PyArray_StringDTypeObject; #endif可以看到在非 abi3t 构建Py_TARGET_ABI3T未定义下结构体保留全部字段而在 abi3t 构建下仅保留一个不完整类型声明forward declaration任何对字段如descr-na_object、descr-allocator的直接访问在编译期就会报错。为什么必须转为不透明结构布局与对象头大小强相关变更说明中给出了直接原因该结构体的布局依赖于对象头object header的大小。PyArray_StringDTypeObject以PyArray_Descr_fields本身包含PyObject头作为base而在 free-threading 解释器中PyObject头会额外携带线程 ID 等字段对象头尺寸与常规non-free-threading构建不同。这意味着在 abi3t 构建中暴露完整结构体布局本质上是把依赖具体解释器 ABI 的内存排布泄漏给了扩展模块任何在 abi3t 构建中直接访问PyArray_StringDTypeObject字段的代码都会因为实际内存布局与编译期假设不一致而发生崩溃crash尤其当运行在 32 位系统上时指针/对齐尺寸差异进一步放大了崩溃风险——2.5.2 变更日志中 PR #31949 BUG: fix crash on 32 bit systems using abi3t (#31771) 正是这一问题的直接修复记录。正因如此NumPy 选择在bugfix 版本2.5.2中完成这次 API 收紧与其让使用方在崩溃中摸索不如在编译期就强制不透明。对扩展作者的影响与迁移方法受影响场景在 abi3tPy_TARGET_ABI3T模式下编译、且此前直接访问PyArray_StringDTypeObject字段的扩展模块。此类代码在 2.5.x 中随时可能崩溃在 2.5.2 及以后将无法通过编译。迁移方法变更说明明确表示NpyString分配器 API 完全不受影响只要改传描述符对象指针即可NpyString_acquire_allocator((PyArray_StringDTypeObject *)descr)即不透明的是结构体字段而不是描述符指针本身。把descr强制转换为不透明的PyArray_StringDTypeObject *后传给分配器 API是官方认可的通行做法。完整参考实现仓库的 limited API 测试扩展 limited_api.c 提供了可复制的完整示例——该函数从 StringDType 数组读取首元素全程不触碰任何结构体字段/* * Test the NpyString allocator API. Under the abi3t stable ABI * PyArray_StringDTypeObject is an opaque struct; the descriptor object * pointer is passed to NpyString_acquire_allocator without accessing any * struct fields. The API only exists when targeting NumPy 2.0. */ #if NPY_FEATURE_VERSION NPY_2_0_API_VERSION static PyObject * limited_api_stringdtype_load(PyObject *mod, PyArrayObject *arr) { npy_string_allocator *allocator NpyString_acquire_allocator( (PyArray_StringDTypeObject *)PyArray_DESCR(arr)); npy_packed_static_string *packed (npy_packed_static_string *)PyArray_DATA(arr); npy_static_string s {0, NULL}; PyObject *res NULL; int is_null NpyString_load(allocator, packed, s); if (is_null -1) { PyErr_SetString(PyExc_RuntimeError, NpyString_load failed); } else if (is_null) { res Py_None; Py_INCREF(res); } else { res PyUnicode_FromStringAndSize(s.buf, (Py_ssize_t)s.size); } NpyString_release_allocator(allocator); return res; } #endif /* NPY_FEATURE_VERSION NPY_2_0_API_VERSION */关键流程拆解获取分配器通过NpyString_acquire_allocator()传入描述符指针获取堆分配器。注意该 API 仅在目标 NumPy 版本 ≥ 2.0NPY_FEATURE_VERSION NPY_2_0_API_VERSION时可用因为NpyString系列 API 是 NumPy 2.0 起随 StringDType 一起引入的。读取元素用NpyString_load(allocator, packed, s)把打包的静态字符串解包为npy_static_string含buf指针与size长度返回值语义为-1表示出错、1表示缺失值NA、0表示正常字符串。转换输出正常字符串用PyUnicode_FromStringAndSize转成 Python 字符串缺失值映射为Py_None。释放分配器使用完毕立即调用NpyString_release_allocator()。这一点与完整结构体中的注释要求一致——分配器只应在持有allocator_lock期间被访问用完即释放。测试验证仓库的 test_limited_api.py 对该路径做了端到端验证覆盖三种典型数据形态# NpyString allocator API; under abi3t PyArray_StringDTypeObject is # opaque and only the descriptor object pointer is passed. Absent # when the module targets NumPy 2.0 (the default target). if hasattr(mod, stringdtype_load): arr np.array([hello, world], dtypenp.dtypes.StringDType()) assert mod.stringdtype_load(arr) hello # A long string is stored on the heap, so loading it # dereferences the allocator acquired from the descriptor. text numpy * 20 arr np.array([text, world], dtypenp.dtypes.StringDType()) assert mod.stringdtype_load(arr) text arr np.array([None, world], dtypenp.dtypes.StringDType(na_objectNone)) assert mod.stringdtype_load(arr) is None三个断言分别验证短字符串内联存储在元素槽位中、长字符串需要经分配器从堆上解引用、缺失值na_objectNone场景。其中长字符串用例最能体现必须经分配器 API的原因——只有拿到描述符对应的分配器才能正确找到堆上的数据。发布与版本信息该变更随 NumPy 2.5.2 bugfix 版本发布仓库中的发布说明 2.5.2-notes.rst 与变更日志 2.5.2-changelog.rst 均有对应记录。变更日志显示2.5.2 同时合入了一批 StringDType 相关的稳定性修复如 ufunc 提升中的 coerce 标志、np.fromiter复用描述符时的数据损坏问题等本次 opaque 化是其中面向扩展作者的关键 ABI 决策。总结与行动清单关注点结论PyArray_StringDTypeObject字段访问abi3t 构建下从 2.5.2 起禁止编译期即报错为什么会崩溃结构体布局依赖对象头大小free-threading 与 32 位环境下布局不一致正确替代方案NpyString_acquire_allocator((PyArray_StringDTypeObject *)descr)等NpyString分配器 APIAPI 可用前提目标 NumPy ≥ 2.0NPY_FEATURE_VERSION NPY_2_0_API_VERSION参考实现与测试limited_api.c、test_limited_api.py如果你的扩展模块同时面向 abi3t 与 StringDType请尽快把对PyArray_StringDTypeObject字段的直接访问改写为经NpyString分配器 API 的间接访问并升级到 NumPy 2.5.2 验证。赞分享科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载相关推荐CPython C API 与 ABI 稳定性指南Py_LIMITED_API、abi3/abi3t 与 Stable ABI 检查机制CPython C API 与 ABI 稳定性指南Py_LIMITED_API、abi3/abi3t 与 Stable ABI 检查机制 C API 的稳定性编程语言语言运行时解释器标准库NumPy 1.16.4 发布说明深度解析随机流修复、C-API 弃用与结构化数组行为变更NumPy 1.16.4 发布说明深度解析随机流修复、C API 弃用与结构化数组行为变更 本篇技术指南以 NumPy 1.16.4 官方发布说明为主体结合科学计算数据分析CPython C API 四层头文件体系导读从 Include 目录结构理解稳定 ABI、Unstable API 与内部接口CPython C API 四层头文件体系导读从 Include 目录结构理解稳定 ABI、Unstable API 与内部接口 导读 C 扩展开发者在接触编程语言语言运行时解释器标准库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考