Background#

The API exposed by NumPy for third-party extensions has grown overyears of releases, and has allowed programmers to directly accessNumPy functionality from C. This API can be best described as“organic”. It has emerged from multiple competing desires and frommultiple points of view over the years, strongly influenced by thedesire to make it easy for users to move to NumPy from Numeric andNumarray. The core API originated with Numeric in 1995 and there arepatterns such as the heavy use of macros written to mimic Python’sC-API as well as account for compiler technology of the late 90’s.There is also only a small group of volunteers who have had very littletime to spend on improving this API.

There is an ongoing effort to improve the API.It is important in this effortto ensure that code that compiles for NumPy 1.X continues tocompile for NumPy 1.X. At the same time, certain API’s will be markedas deprecated so that future-looking code can avoid these API’s andfollow better practices.

Another important role played by deprecation markings in the C API is to movetowards hiding internal details of the NumPy implementation. For thoseneeding direct, easy, access to the data of ndarrays, this will notremove this ability. Rather, there are many potential performanceoptimizations which require changing the implementation details, andNumPy developers have been unable to try them because of the highvalue of preserving ABI compatibility. By deprecating this directaccess, we will in the future be able to improve NumPy’s performancein ways we cannot presently.

Deprecation mechanism NPY_NO_DEPRECATED_API#

In C, there is no equivalent to the deprecation warnings that Pythonsupports. One way to do deprecations is to flag them in thedocumentation and release notes, then remove or change the deprecatedfeatures in a future major version (NumPy 2.0 and beyond). Minorversions of NumPy should not have major C-API changes, however, thatprevent code that worked on a previous minor release. For example, wewill do our best to ensure that code that compiled and worked on NumPy1.4 should continue to work on NumPy 1.7 (but perhaps with compilerwarnings).

To use the NPY_NO_DEPRECATED_API mechanism, you need to #define it tothe target API version of NumPy before #including any NumPy headers.If you want to confirm that your code is clean against 1.7, use:

#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

On compilers which support a #warning mechanism, NumPy issues acompiler warning if you do not define the symbol NPY_NO_DEPRECATED_API.This way, the fact that there are deprecations will be flagged forthird-party developers who may not have read the release notes closely.

Note that defining NPY_NO_DEPRECATED_API is not sufficient to make yourextension ABI compatible with a given NumPy version. SeeFor downstream package authors.