waiting for a review ...

@charris could you take a look

I don't think this is correct. The versions here refer to the include files only, and are for deprecating the functions/macros therein. They are independent of the API versions tracked in cversions.txt and as far as the include files go, I don't think anything has been deprecated since 1.8. If we decide to replace some other structure access by a function, or otherwise remove a current macro or structure access, then the number will need updating. We might want to improve the documentation of this feature.

I don;t understand, the NPY_API_VERSION macro influences more than just the the headers. It matters in PyArray_XDECREF_ERR. Why would we want to preserve an inconsistency between the numbers in cversions.txt and numpyconfig.h? One of the files should be fixed.

Same name, different things. Call it NPY_FOO_VERSION. It has never has a relation to the other API version.

Well, we should update the number anyway since the headers have changed, PyArray_XDECREF_ERR is now deprecated.

It has never has a relation to the other API version.

So the NPY_API_VERSION and, for instance, NPY_1_16_API_VERSION have no correlation? That indeed is confusing. Wouldn't it be better to keep them in sync? What would it harm?

Think of it this way, the NPY_API_VERSION allows the user to choose which API they want to see, one using inline functions to access PyArrayObject internals, or one using macros and direct access. The purpose was not to change functionality, but to change implementation as we increasingly hid internals.

Now I search into the include files and see that you did use the version to deprecate PyArray_XDECREF_ERR, but I think you should simply have deprecated it regardless of version, then at some point it will be removed, preferably when it no longer can be used. It's not like we want to keep that interface around so the people who don't want to update their code can continue using it, we want them to stop using it regardless of whether or not they directly access the PyArrayObject internals. I think the cversions.txt method is the proper way to do that.

To summarize, the NPY_API_VERSION was intended to control direct access to array internals, anything different should not use it.

A question. Will code compiled with older NumPy PyArray_XDECREF_ERR be forward compatible with newer NumPy versions?

the NPY_API_VERSION allows the user to choose which API they want to see,

Isn't that mattip's point? If they #define NPY_NO_DEPRECATED_API NPY_1_14_API_VERSION, then they do not get the API with PyArray_XDECREF_ERR, and if they define something older, they do.

For that to work, NPY_1_14_API_VERSION needs to be greater than NPY_1_13_API_VERSION

They also don't get direct access to the structures. The point is that those two things follow separate deprecation paths.

ok, closing. Thanks for the explanations

@mattip Thanks for making me think about it :)

Another way to see what was intended is to think of the NPY_API_VERSION as a group deprecation of direct access to the PyArrayObject, achieved by renaming it. That is, it is a single deprecation of specific functionality. It probably could have been done by just changing the macros rather than replacing them with inline functions, but inline functions do have the advantage of compile time type checking.

I think we still need to figure out how to handle the PyArray_XDECREF_ERR function.