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 兼容。请参阅 面向下游包作者。