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