BLD: Add support for NPY_TARGET_VERSION macro

This is a way for downstream users to specify which NumPy version
they wish to be compaible with.

Note that we provide a conservative default here (because almost nobody
actually uses new API as they would lose backwards compatibility).

Initially I had thought we should just redefine it so that the target
version uses the same scheme as the Python hex version (and limited API),
but since we have `NPY_1_15_API_VERSION` defines, use those...

This commit does not include any actual use of this!

3 files changed, 74 insertions, 33 deletions

diff --git a/numpy/core/include/numpy/ndarraytypes.h b/numpy/core/include/numpy/ndarraytypes.h
index 45ecb6955..f771d62cd 100644
--- a/numpy/core/include/numpy/ndarraytypes.h
+++ b/numpy/core/include/numpy/ndarraytypes.h
@@ -44,23 +44,6 @@
 #define NPY_FAIL 0
 #define NPY_SUCCEED 1
 
-/*
- * Binary compatibility version number.  This number is increased
- * whenever the C-API is changed such that binary compatibility is
- * broken, i.e. whenever a recompile of extension modules is needed.
- */
-#define NPY_VERSION NPY_ABI_VERSION
-
-/*
- * Minor API version.  This number is increased whenever a change is
- * made to the C-API -- whether it breaks binary compatibility or not.
- * Some changes, such as adding a function pointer to the end of the
- * function table, can be made without breaking binary compatibility.
- * In this case, only the NPY_FEATURE_VERSION (*not* NPY_VERSION)
- * would be increased.  Whenever binary compatibility is broken, both
- * NPY_VERSION and NPY_FEATURE_VERSION should be increased.
- */
-#define NPY_FEATURE_VERSION NPY_API_VERSION
 
 enum NPY_TYPES {    NPY_BOOL=0,
                     NPY_BYTE, NPY_UBYTE,
diff --git a/numpy/core/include/numpy/numpyconfig.h b/numpy/core/include/numpy/numpyconfig.h
index b7d7e2ca4..117f3a9c7 100644
--- a/numpy/core/include/numpy/numpyconfig.h
+++ b/numpy/core/include/numpy/numpyconfig.h
@@ -56,30 +56,83 @@
 
 
 /**
- * To help with the NPY_NO_DEPRECATED_API macro, we include API version
- * numbers for specific versions of NumPy. To exclude all API that was
- * deprecated as of 1.7, add the following before #including any NumPy
- * headers:
+ * To help with both NPY_TARGET_VERSION and the NPY_NO_DEPRECATED_API macro,
+ * we include API version numbers for specific versions of NumPy.
+ * To exclude all API that was deprecated as of 1.7, add the following before
+ * #including any NumPy headers:
  *   #define NPY_NO_DEPRECATED_API  NPY_1_7_API_VERSION
+ * The same is true for NPY_TARGET_VERSION, although NumPy will default to
+ * a backwards compatible build anyway.
  */
 #define NPY_1_7_API_VERSION 0x00000007
 #define NPY_1_8_API_VERSION 0x00000008
-#define NPY_1_9_API_VERSION 0x00000008
-#define NPY_1_10_API_VERSION 0x00000008
-#define NPY_1_11_API_VERSION 0x00000008
-#define NPY_1_12_API_VERSION 0x00000008
-#define NPY_1_13_API_VERSION 0x00000008
-#define NPY_1_14_API_VERSION 0x00000008
-#define NPY_1_15_API_VERSION 0x00000008
-#define NPY_1_16_API_VERSION 0x00000008
-#define NPY_1_17_API_VERSION 0x00000008
-#define NPY_1_18_API_VERSION 0x00000008
-#define NPY_1_19_API_VERSION 0x00000008
+#define NPY_1_9_API_VERSION 0x00000009
+#define NPY_1_10_API_VERSION 0x0000000a
+#define NPY_1_11_API_VERSION 0x0000000a
+#define NPY_1_12_API_VERSION 0x0000000a
+#define NPY_1_13_API_VERSION 0x0000000b
+#define NPY_1_14_API_VERSION 0x0000000c
+#define NPY_1_15_API_VERSION 0x0000000c
+#define NPY_1_16_API_VERSION 0x0000000d
+#define NPY_1_17_API_VERSION 0x0000000d
+#define NPY_1_18_API_VERSION 0x0000000d
+#define NPY_1_19_API_VERSION 0x0000000d
 #define NPY_1_20_API_VERSION 0x0000000e
 #define NPY_1_21_API_VERSION 0x0000000e
 #define NPY_1_22_API_VERSION 0x0000000f
 #define NPY_1_23_API_VERSION 0x00000010
 #define NPY_1_24_API_VERSION 0x00000010
-#define NPY_1_25_API_VERSION 0x00000010
+#define NPY_1_25_API_VERSION 0x00000011
+
+
+/*
+ * Binary compatibility version number.  This number is increased
+ * whenever the C-API is changed such that binary compatibility is
+ * broken, i.e. whenever a recompile of extension modules is needed.
+ */
+#define NPY_VERSION NPY_ABI_VERSION
+
+/*
+ * Minor API version we are compiling to be compatible with.  The version
+ * Number is always increased when the API changes via: `NPY_API_VERSION`
+ * (and should maybe just track the NumPy version).
+ *
+ * If we have an internal build, we always target the current version of
+ * course.
+ *
+ * For downstream users, we default to an older version to provide them with
+ * maximum compatibility by default.  Downstream can choose to extend that
+ * default, or narrow it down if they wish to use newer API.  If you adjust
+ * this, consider the Python version support (example for 1.25.x):
+ *
+ * NumPy 1.25.x supports Python:                     3.9  3.10  3.11  (3.12)
+ * NumPy 1.19.x supports Python:      3.6  3.7  3.8  3.9
+ * NumPy 1.17.x supports Python: 3.5  3.6  3.7  3.8
+ * NumPy 1.15.x supports Python: ...  3.6  3.7
+ *
+ * Users of the stable ABI may wish to target the last Python that is not
+ * end of life.  This would be 3.8 at NumPy 1.25 release time.
+ * 1.17 as default was the choice of oldest-support-numpy at the time and
+ * has in practice no limit (comapared to 1.19).  Even earlier becomes legacy.
+ */
+#ifdef NPY_TARGET_VERSION
+  #define NPY_FEATURE_VERSION NPY_TARGET_VERSION
+#else
+  #if defined(NPY_INTERNAL_BUILD) && NPY_INTERNAL_BUILD
+    #define NPY_FEATURE_VERSION NPY_API_VERSION
+  #else
+    /* NOTE: This default should be increased over time: */
+    #define NPY_FEATURE_VERSION NPY_1_17_API_VERSION
+  #endif
+#endif
+
+/* Sanity check the (requested) feature version */
+#if NPY_FEATURE_VERSION > NPY_API_VERSION
+    #error "NPY_TARGET_VERSION higher than NumPy headers!"
+#elif NPY_FEATURE_VERSION < NUMPY_1_15_API_VERSION
+    /* Older than NumPy 1.15 requires Python 3.6... */
+    #error "NPY_TARGET_VERSION cannot ask for a version before 1.15."
+#endif
+
 
 #endif  /* NUMPY_CORE_INCLUDE_NUMPY_NPY_NUMPYCONFIG_H_ */
diff --git a/numpy/core/setup_common.py b/numpy/core/setup_common.py
index ef8d21fa7..af8eeecde 100644
--- a/numpy/core/setup_common.py
+++ b/numpy/core/setup_common.py
@@ -50,6 +50,11 @@ C_ABI_VERSION = 0x01000009
 # 0x00000010 - 1.24.x
 C_API_VERSION = 0x00000010
 
+# When compiling against NumPy (downstream libraries), NumPy will by default
+# pick an older feature version.  For example, for 1.25.x we default to the
+# 1.17 API and support going back all the way to 1.15.x (if so desired).
+# This is set up in `numpyconfig.h`.
+
 class MismatchCAPIError(ValueError):
     pass