Address review comments

numpy · ngoldbaum · Nov 28, 2023 · Nov 2, 2023 · Nov 14, 2023 · Nov 14, 2023
commit 0498d8cf18e1d061d17622fac680f901e5f15e36
diff --git a/doc/release/upcoming_changes/25149.c_api.rst b/doc/release/upcoming_changes/25149.c_api.rst
@@ -5,6 +5,6 @@ Lager ``NPY_MAXDIMS`` and ``NPY_MAXARGS``, ``NPY_RAVEL_AXIS`` introduced
 used in a stack allocation, where the increase should be safe.
 However, we do encourage generally to remove any use of ``NPY_MAXDIMS`` and
 ``NPY_MAXARGS`` to eventually allow removing the constraint completely.
-In some cases, ``NPY_MAXDIMS`` was passed (and returned) to mean ``axis=None``
-these must be replaced with ``NPY_RAVEL_AXIS``.
-See also :ref:`migration_maxdims`.
+For the conversion helper and C-API functions mirrowing Python ones such as
+``tale``, ``NPY_MAXDIMS`` was used to mean ``axis=None`` these must be
+replaced with ``NPY_RAVEL_AXIS``.  See also :ref:`migration_maxdims`.
diff --git a/doc/release/upcoming_changes/25149.c_api_removal.rst b/doc/release/upcoming_changes/25149.c_api_removal.rst
@@ -0,0 +1,2 @@
+* ``NPY_MAX_ELSIZE`` macro has been removed as it only ever reflected
+  builtin numeric types and served no internal purpose.
diff --git a/doc/source/numpy_2_0_migration_guide.rst b/doc/source/numpy_2_0_migration_guide.rst
@@ -59,10 +59,12 @@ NumPy can remove this limitation on the number of dimensions.
 
 ``NPY_MAXDIMS`` was also used to signal ``axis=None`` in the C-API, including
 the ``PyArray_AxisConverter``.
-If you run into this problem, you will see ``-2147483648``
-(the minimum integer value) or ``64`` being used as an invalid axis.
-Wherever you do, you must replace ``NPY_MAXDIMS`` with ``NPY_RAVEL_AXIS``.
-This is defined in the ``npy_2_compat.h`` header and runtime dependent.
+The latter will return ``-2147483648`` as an axis (the smallest integer value).
+Other functions may error with
+``AxisError: axis 64 is out of bounds for array of dimension`` in which
+case you need to pass ``NPY_RAVEL_AXIS`` instead of ``NPY_MAXDIMS``.
+``NPY_RAVEL_AXIS`` is defined in the ``npy_2_compat.h`` header and runtime
+dependent (mapping to 32 on NumPy 1.x and ``-2147483648`` on NumPy 2.x).
 
 
 Namespace changes

diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst
@@ -3456,7 +3456,9 @@ Other constants
     have an ``axis`` argument.  This macro may be passed for ``axis=None``.
 
     .. note::
-        This macro is NumPy version dependent at runtime.
+        This macro is NumPy version dependent at runtime. The value is now
+        the minimum integer. However, on NumPy 1.x ``NPY_MAXDIMS`` was used
+        (at the time set to 32).
 
 
 Miscellaneous Macros

diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst
@@ -120,10 +120,11 @@ PyArray_Type and PyArrayObject
        array. Such arrays have undefined dimensions and strides and
        cannot be accessed. Macro :c:data:`PyArray_NDIM` defined in
        ``ndarraytypes.h`` points to this data member.
-       Although most operations may be limited in dimensionality, we do not
-       advertise a maximum dimension.  Anyone explicitly relying on one
-       must check for it.  Before NumPy 2.0, NumPy used 32 dimensions at most
-       after it, the limit is currently 64.
+       ``NPY_MAXDIMS`` is defined as a compile time constant limiting the
+       number of dimensions.  This number is 64 since NumPy 2 and was 32
+       before. However, we may wish to remove this limitations in the future
+       so that it is best to explicitly check dimensionality for code
+       that relies on such an upper bound.
 
    .. c:member:: npy_intp *dimensions
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		* ``NPY_MAX_ELSIZE`` macro has been removed as it only ever reflected
		builtin numeric types and served no internal purpose.