Merge pull request numpy#26241 from seberg/intp-doc-fixups

DOC: Fixup intp/uintp documentation for ssize_t/size_t changes

Author: charris

doc/source/reference/arrays.scalars.rst

@@ -37,9 +37,8 @@ of the flexible itemsize array types (:class:`str_`,
 
    **Figure:** Hierarchy of type objects representing the array data
    types. Not shown are the two integer types :class:`intp` and
-   :class:`uintp` which just point to the integer type that holds a
-   pointer for the platform. All the number types can be obtained
-   using bit-width names as well.
+   :class:`uintp` which are used for indexing (the same as the
+   default integer since NumPy 2).
 
 
 .. TODO - use something like this instead of the diagram above, as it generates
@@ -377,21 +376,29 @@ are also provided.
 
    Alias for the signed integer type (one of `numpy.byte`, `numpy.short`,
    `numpy.intc`, `numpy.int_`, `numpy.long` and `numpy.longlong`)
-   that is the same size as a pointer.
+   that is used as a default integer and for indexing.
 
-   Compatible with the C ``intptr_t``.
+   Compatible with the C ``Py_ssize_t``.
 
-   :Character code: ``'p'``
+   :Character code: ``'n'``
+
+   .. versionchanged:: 2.0
+      Before NumPy 2, this had the same size as a pointer.  In practice this
+      is almost always identical, but the character code ``'p'`` maps to the C
+      ``intptr_t``.  The character code ``'n'`` was added in NumPy 2.0.
 
 .. attribute:: uintp
 
-   Alias for the unsigned integer type (one of `numpy.ubyte`, `numpy.ushort`,
-   `numpy.uintc`, `numpy.uint`, `numpy.ulong` and `numpy.ulonglong`)
-   that is the same size as a pointer.
+   Alias for the unsigned integer type that is the same size as ``intp``.
+
+   Compatible with the C ``size_t``.
 
-   Compatible with the C ``uintptr_t``.
+   :Character code: ``'N'``
 
-   :Character code: ``'P'``
+   .. versionchanged:: 2.0
+      Before NumPy 2, this had the same size as a pointer.  In practice this
+      is almost always identical, but the character code ``'P'`` maps to the C
+      ``uintptr_t``.  The character code ``'N'`` was added in NumPy 2.0.
 
 .. autoclass:: numpy.float16
 

doc/source/reference/c-api/dtype.rst

@@ -170,14 +170,26 @@ Enumerated types
 
     .. c:enumerator:: NPY_INTP
 
-        The enumeration value for a signed integer type which is the same
-        size as a (void \*) pointer. This is the type used by all
+        The enumeration value for a signed integer of type ``Py_ssize_t``
+        (same as ``ssize_t`` if defined). This is the type used by all
         arrays of indices.
 
+        .. versionchanged:: 2.0
+            Previously, this was the same as ``intptr_t`` (same size as a
+            pointer).  In practice, this is identical except on very niche
+            platforms.
+            You can use the ``'p'`` character code for the pointer meaning.
+
     .. c:enumerator:: NPY_UINTP
 
-        The enumeration value for an unsigned integer type which is the
-        same size as a (void \*) pointer.
+        The enumeration value for an unsigned integer type that is identical
+        to a ``size_t``.
+
+        .. versionchanged:: 2.0
+            Previously, this was the same as ``uintptr_t`` (same size as a
+            pointer).  In practice, this is identical except on very niche
+            platforms.
+            You can use the ``'P'`` character code for the pointer meaning.
 
     .. c:enumerator:: NPY_MASK
 
@@ -287,14 +299,20 @@ all platforms for all the kinds of numeric types. Commonly 8-, 16-,
 types are available.
 
 
-Integer that can hold a pointer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Further integer aliases
+~~~~~~~~~~~~~~~~~~~~~~~
 
-The constants **NPY_INTP** and **NPY_UINTP** refer to an
-enumerated integer type that is large enough to hold a pointer on the
-platform. Index arrays should always be converted to **NPY_INTP**
-, because the dimension of the array is of type npy_intp.
+The constants **NPY_INTP** and **NPY_UINTP** refer to an ``Py_ssize_t``
+and ``size_t``.
+Although in practice normally true, these types are strictly speaking not
+pointer sized and the character codes ``'p'`` and ``'P'`` can be used for
+pointer sized integers.
+(Before NumPy 2, ``intp`` was pointer size, but this almost never matched
+the actual use, which is the reason for the name.)
 
+Since NumPy 2, **NPY_DEFAULT_INT** is additionally defined.
+The value of the macro is runtime dependent:  Since NumPy 2, it maps to
+``NPY_INTP`` while on earlier versions it maps to ``NPY_LONG``.
 
 C-type names
 ------------