Yesterday I proposed a plan to evolve our C-API (where we can/want). I believe that needs to be a two step separate things:

1. Change how we build backwards compatible NumPy versions:

   • Introduce NUMPY_TARGET_VERSION=0x01013000 // NumPy 1.19, when compiling, by default any newer API is hidden behind #if guards.
   • If a user wants newer API, they use:

     /* require NumPy 1.22 for mem-handler API: */
     NUMPY_TARGET_VERSION=0x01016000
     

   • We "take care of the rest". I.e. checking versions on import.
   • oldest-support-numpy would always be happy with >1.25.
   • Cython: In this context .pyd files are bit special. In most cases it is OK for them to include definitions that are not actually available (because they too new). There are some exceptions, though. The one I am aware of is that new Python classes must live in a new .pyd file because otherwise Cython would generate backwards incompatible initialization code.

2. Point 1 means that users can always use the newest headers. For a 2.0 release we could enforce a rebuilt of NumPy so that we know they are using 2.0+ headers. That gives us a huge amount of flexibility in what we could do. (Of course many changes themselves will impact users).

   • This point, I suspect needs to be fleshed out a little bit as a document anyway (if just to have something to point to and more formally agree on).

I don't want to discuss 2. here (we can open separate issue, yesterday it sounded like we will give forcing both a rebuild and some code changes a shot).

What I will push now is point 1. Some points for feedback, if we are unsure about it I can flesh this out:

1. Let's sync up the NumPy C-API feature version and the actual NumPy version?
   • Yes, one includes the major version and the other one does not. Our C-ABI version would be left untouched. As soon as NumPy 2.0 gets released the C-ABI version would be identical to NumPyVersion & 0xFF000000 (right now it is 0x01000009)
   • We'll bump it anyway in 1.25.
2. Users of memory handler API will have to add the define. This seems so niche and easy to do that I think it is firmly "no worry".
3. Are there other things we need to consider? (I.e. testing? For that I suspect it isn't a big issue and downstream wheels will be runtime tested against older NumPy versions.)

Any other bike-sheds, like the name of the define? :)

This is just for potentially longer discussion. I hope to open a PR soon (step 1 is really quite simple).