C API 弃用

背景

NumPy 为第三方扩展公开的 API 随着多年的发布而增长,并允许程序员直接从 C 访问 NumPy 功能. 此 API 可以最好地描述为"有机".多年来,它源于多个相互竞争的愿望和多个观点,并受到使用户可以轻松地从 Numeric 和 Numarray 迁移到 NumPy 的强烈愿望的影响.核心 API 起源于 1995 年的 Numeric,并且存在诸如大量使用宏来模仿 Python 的 C-API 以及考虑到 90 年代后期的编译器技术的模式. 并且只有一小部分志愿者几乎没有时间来改进此 API.

目前正在努力改进 API.在这项工作中,重要的是要确保为 NumPy 1.X 编译的代码继续为 NumPy 1.X 编译.同时,某些 API 将被标记为已弃用,以便面向未来的代码可以避免这些 API 并遵循更好的实践.

C API 中弃用标记的另一个重要作用是朝着隐藏 NumPy 实现的内部细节迈进.对于那些需要直接,轻松地访问 ndarray 数据的人来说,这不会消除这种能力.相反,许多潜在的性能优化需要更改实现细节,而 NumPy 开发人员一直无法尝试它们,因为保持 ABI 兼容性具有很高的价值.通过弃用这种直接访问,我们将来能够以目前无法实现的方式提高 NumPy 的性能.

弃用机制 NPY_NO_DEPRECATED_API

在 C 中,没有与 Python 支持的弃用警告等效的东西.一种弃用方式是在文档和发行说明中标记它们,然后在未来的主要版本(NumPy 2.0 及更高版本)中删除或更改已弃用的功能.NumPy 的次要版本不应有重大的 C-API 更改,但是,这会阻止在以前的次要版本上工作的代码.例如,我们将尽最大努力确保在 NumPy 1.4 上编译和工作的代码应继续在 NumPy 1.7 上工作(但可能带有编译器警告).

要使用 NPY_NO_DEPRECATED_API 机制,您需要在 #including 任何 NumPy 标头之前将其 #define 为 NumPy 的目标 API 版本. 如果您想确认您的代码对于 1.7 是干净的,请使用:

#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

在支持 #warning 机制的编译器上,如果您未定义符号 NPY_NO_DEPRECATED_API,NumPy 会发出编译器警告. 这样,对于可能没有仔细阅读发行说明的第三方开发人员,将标记出存在弃用的事实.

请注意,定义 NPY_NO_DEPRECATED_API 不足以使您的扩展与给定 NumPy 版本的 ABI 兼容. 请参阅 面向下游软件包作者 .