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 头文件之前将其定义为 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 兼容。请参阅 对于下游包作者。