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 并不足以使你的扩展 ABI 与给定的 NumPy 版本兼容. 参见 对于下游软件包的作者 .