Merge pull request #26173 from charris/backport-26172

charris · web-flow · commit ebedc68f643b · 2024-03-29T13:57:34.000-06:00
DOC, TST: make ``numpy.version`` officially public
diff --git a/doc/source/reference/module_structure.rst b/doc/source/reference/module_structure.rst
@@ -35,6 +35,7 @@ Special-purpose namespaces
 - :ref:`numpy.emath <routines.emath>` - mathematical functions with automatic domain
 - :ref:`numpy.lib <routines.lib>` - utilities & functionality which do not fit the main namespace
 - :ref:`numpy.rec <routines.rec>` - record arrays (largely superseded by dataframe libraries)
+- :ref:`numpy.version <routines.version>` - small module with more detailed version info
 
 Legacy namespaces
 =================
@@ -67,6 +68,7 @@ and/or this code is deprecated or isn't reliable.
    numpy.emath <routines.emath>
    numpy.lib <routines.lib>
    numpy.rec <routines.rec>
+   numpy.version <routines.version>
    numpy.char <routines.char>
    numpy.distutils <distutils>
    numpy.f2py <../f2py/index>
diff --git a/doc/source/reference/routines.version.rst b/doc/source/reference/routines.version.rst
@@ -0,0 +1,38 @@
+.. currentmodule:: numpy.version
+
+.. _routines.version:
+
+*******************
+Version information
+*******************
+
+The ``numpy.version`` submodule includes several constants that expose more
+detailed information about the exact version of the installed ``numpy``
+package:
+
+.. data:: version
+
+    Version string for the installed package - matches ``numpy.__version__``.
+
+.. data:: full_version
+
+    Version string - the same as ``numpy.version.version``.
+
+.. data:: short_version
+
+    Version string without any local build identifiers.
+
+    .. rubric:: Examples
+
+    >>> np.__version__
+    '2.1.0.dev0+git20240319.2ea7ce0'  # may vary
+    >>> np.version.short_version
+    '2.1.0.dev0'  # may vary
+
+.. data:: git_revision
+
+    String containing the git hash of the commit from which ``numpy`` was built.
+
+.. data:: release
+
+    ``True`` if this version is a ``numpy`` release, ``False`` if a dev version.
diff --git a/numpy/_build_utils/gitversion.py b/numpy/_build_utils/gitversion.py
@@ -70,6 +70,9 @@ def git_version(version):
 
     # For NumPy 2.0, this should only have one field: `version`
     template = textwrap.dedent(f'''
+        """
+        Module to expose more detailed version info for the installed `numpy`
+        """
         version = "{version}"
         __version__ = version
         full_version = version
diff --git a/numpy/tests/test_numpy_version.py b/numpy/tests/test_numpy_version.py
@@ -39,3 +39,16 @@ def test_short_version():
     else:
         assert_(np.__version__.split("+")[0] == np.version.short_version,
                 "short_version mismatch in development version")
+
+
+def test_version_module():
+    contents = set([s for s in dir(np.version) if not s.startswith('_')])
+    expected = set([
+        'full_version',
+        'git_revision',
+        'release',
+        'short_version',
+        'version',
+    ])
+
+    assert contents == expected
diff --git a/numpy/tests/test_public_api.py b/numpy/tests/test_public_api.py
@@ -114,14 +114,14 @@ def test_NPY_NO_EXPORT():
     "f2py",
     "fft",
     "lib",
-    "lib.format",  # was this meant to be public?
+    "lib.array_utils",
+    "lib.format",
+    "lib.introspect",
     "lib.mixins",
-    "lib.recfunctions",
+    "lib.npyio",
+    "lib.recfunctions",  # note: still needs cleaning, was forgotten for 2.0
     "lib.scimath",
     "lib.stride_tricks",
-    "lib.npyio",
-    "lib.introspect",
-    "lib.array_utils",
     "linalg",
     "ma",
     "ma.extras",
@@ -134,11 +134,12 @@ def test_NPY_NO_EXPORT():
     "polynomial.legendre",
     "polynomial.polynomial",
     "random",
+    "strings",
     "testing",
     "testing.overrides",
     "typing",
     "typing.mypy_plugin",
-    "version"  # Should be removed for NumPy 2.0
+    "version",
 ]]
 if sys.version_info < (3, 12):
     PUBLIC_MODULES += [
@@ -158,7 +159,6 @@ def test_NPY_NO_EXPORT():
     "numpy.char",
     "numpy.emath",
     "numpy.rec",
-    "numpy.strings",
 ]
 
 
@@ -535,7 +535,7 @@ def test_core_shims_coherence():
         # no need to add it to np.core
         if (
             member_name.startswith("_")
-            or member_name == "tests"
+            or member_name in ["tests", "strings"]
             or f"numpy.{member_name}" in PUBLIC_ALIASED_MODULES 
         ):
             continue
