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 机制，您需要在包含任何 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 兼容。请参阅对于下游软件包作者。