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实现的内部细节.对于那些需要直接、轻松访问ndarrays数据的人来说,这不会移除这种能力.相反,有许多潜在的性能优化需要改变实现细节,而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 机制,你需要在 #include 任何 NumPy 头文件之前将其 #define 为目标 API 版本的 NumPy.如果你想确认你的代码针对 1.7 是干净的,请使用:

#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

在支持 #warning 机制的编译器上,如果你没有定义符号 NPY_NO_DEPRECATED_API,NumPy 会发出编译器警告.这样,第三方开发者即使没有仔细阅读发布说明,也会知道存在弃用的情况.

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