API: Add environment variable for behavior planned in a 2.0

The idea of the flag is not to allow to change it right now, since
there may be some things where that is hard to do in general, and
it doesn't seem relevant:  nobody is supposed to use it besides for
testing.

5 files changed, 45 insertions, 2 deletions

diff --git a/doc/release/numpy2_changes/README.md b/doc/release/numpy2_changes/README.md
new file mode 100644
index 000000000..fb59749a9
--- /dev/null
+++ b/doc/release/numpy2_changes/README.md
@@ -0,0 +1,4 @@
+Same as ``../upcoming_changes`` but for changes that currently
+are opt-in behind ``NPY_NUMPY_2_BEHAVIOR=1``.
+
+This is to get a start on release notes for such changes.
diff --git a/doc/source/reference/global_state.rst b/doc/source/reference/global_state.rst
index f5c96c355..a110ce7c1 100644
--- a/doc/source/reference/global_state.rst
+++ b/doc/source/reference/global_state.rst
@@ -95,3 +95,17 @@ memory allocation policy, the default will be to call ``free``. If
 ``NUMPY_WARN_IF_NO_MEM_POLICY`` is set to ``"1"``, a ``RuntimeWarning`` will
 be emitted. A better alternative is to use a ``PyCapsule`` with a deallocator
 and set the ``ndarray.base``.
+
+
+Testing planned future behavior
+===============================
+
+NumPy has some code paths which are planned to be activated in the future
+but are not yet the default behavior.
+You can try testing some of these which may be shipped with a new "major"
+release (NumPy 2.0) by setting an environment before importing NumPy:
+
+    NPY_NUMPY_2_BEHAVIOR=1
+
+By default this will also activate the :ref:`NEP 50 <NEP50>` related setting
+``NPY_PROMOTION_STATE`` (please see the NEP for details on this).
diff --git a/numpy/__init__.py b/numpy/__init__.py
index 052ba7327..976062d13 100644
--- a/numpy/__init__.py
+++ b/numpy/__init__.py
@@ -122,6 +122,10 @@ except NameError:
 if __NUMPY_SETUP__:
     sys.stderr.write('Running from numpy source directory.\n')
 else:
+    # Make variable available during multiarray/C initialization
+    import os
+    _numpy2_behavior = os.environ.get("NPY_NUMPY_2_BEHAVIOR", "0") != "0"
+
     try:
         from numpy.__config__ import show as show_config
     except ImportError as e:
@@ -392,7 +396,6 @@ else:
     # is slow and thus better avoided.
     # Specifically kernel version 4.6 had a bug fix which probably fixed this:
     # https://github.com/torvalds/linux/commit/7cf91a98e607c2f935dbcc177d70011e95b8faff
-    import os
     use_hugepage = os.environ.get("NUMPY_MADVISE_HUGEPAGE", None)
     if sys.platform == "linux" and use_hugepage is None:
         # If there is an issue with parsing the kernel version,
@@ -415,13 +418,16 @@ else:
 
     # Note that this will currently only make a difference on Linux
     core.multiarray._set_madvise_hugepage(use_hugepage)
+    del use_hugepage
 
     # Give a warning if NumPy is reloaded or imported on a sub-interpreter
     # We do this from python, since the C-module may not be reloaded and
     # it is tidier organized.
     core.multiarray._multiarray_umath._reload_guard()
 
-    core._set_promotion_state(os.environ.get("NPY_PROMOTION_STATE", "legacy"))
+    # default to "weak" promotion for "NumPy 2".
+    core._set_promotion_state(os.environ.get(
+            "NPY_PROMOTION_STATE", "weak" if _numpy2_behavior else "legacy"))
 
     # Tell PyInstaller where to find hook-numpy.py
     def _pyinstaller_hooks_dir():
diff --git a/numpy/core/src/multiarray/multiarraymodule.c b/numpy/core/src/multiarray/multiarraymodule.c
index db7fda32d..86869c8e4 100644
--- a/numpy/core/src/multiarray/multiarraymodule.c
+++ b/numpy/core/src/multiarray/multiarraymodule.c
@@ -98,6 +98,12 @@ _umath_strings_richcompare(
  * future.
  */
 int npy_legacy_print_mode = INT_MAX;
+/*
+ * Global variable to check whether NumPy 2.0 behavior is opted in.
+ * This flag is considered a runtime constant.
+ */
+int npy_numpy2_behavior = NPY_FALSE;
+
 
 static PyObject *
 set_legacy_print_mode(PyObject *NPY_UNUSED(self), PyObject *args)
@@ -4913,6 +4919,17 @@ initialize_static_globals(void)
         return -1;
     }
 
+    PyObject *_is_numpy2 = NULL;
+    npy_cache_import("numpy", "_numpy2_behavior", &_is_numpy2);
+    if (_is_numpy2 == NULL) {
+        return -1;
+    }
+    npy_numpy2_behavior = PyObject_IsTrue(_is_numpy2);
+    Py_DECREF(_is_numpy2);
+    if (npy_numpy2_behavior < 0) {
+        return -1;
+    }
+
     return 0;
 }
 
diff --git a/numpy/core/src/multiarray/multiarraymodule.h b/numpy/core/src/multiarray/multiarraymodule.h
index 809736cd2..992acd09f 100644
--- a/numpy/core/src/multiarray/multiarraymodule.h
+++ b/numpy/core/src/multiarray/multiarraymodule.h
@@ -1,6 +1,8 @@
 #ifndef NUMPY_CORE_SRC_MULTIARRAY_MULTIARRAYMODULE_H_
 #define NUMPY_CORE_SRC_MULTIARRAY_MULTIARRAYMODULE_H_
 
+NPY_VISIBILITY_HIDDEN extern int npy_numpy2_behavior;
+
 NPY_VISIBILITY_HIDDEN extern PyObject * npy_ma_str_current_allocator;
 NPY_VISIBILITY_HIDDEN extern PyObject * npy_ma_str_array;
 NPY_VISIBILITY_HIDDEN extern PyObject * npy_ma_str_array_function;