numpy · charris · Jul 26, 2023 · Oct 20, 2020 · Oct 20, 2020 · Oct 20, 2020
diff --git a/doc/neps/nep-0051-scalar-representation.rst b/doc/neps/nep-0051-scalar-representation.rst
@@ -232,6 +232,15 @@ found `here <https://github.com/numpy/numpy/pull/22449>`_
 Implementation
 ==============
 
+.. note::
+    This part has *not* been implemented in the
+    `initial PR <https://github.com/numpy/numpy/pull/22449>`_.
+    A similar change will be required to fix certain cases in printing and
+    allow fully correct printing e.g. of structured scalars which include
+    longdoubles.
+    A similar solution is also expected to be necessary in the future
+    to allow custom DTypes to correctly print.
+
 The new representations can be mostly implemented on the scalar types with
 the largest changes needed in the test suite.
 

diff --git a/doc/release/upcoming_changes/22449.change.rst b/doc/release/upcoming_changes/22449.change.rst
@@ -0,0 +1,15 @@
+Representation of NumPy scalars changed
+---------------------------------------
+As per :ref:`NEP 51 <NEP51>`, the scalar representation has been
+updated to include the type information to avoid confusion with
+Python scalars.
+The are now printed as ``np.float64(3.0)`` rather than just ``3.0``.
+This may disrupt workflows that store representations of numbers
+(e.g. to files) making it harder to read them.  They should be stored as
+explicit strings, for example by using ``str()`` or ``f"{scalar!s}"``.
+For the time being, affected users can use ``np.set_printoptions(legacy="1.25")``
+to get the old behavior (with possibly a few exceptions).
+Documentation of downstream projects may require larger updates,
+if code snippets are tested.  We are working on tooling for:
+`doctest-plus <https://github.com/scientific-python/pytest-doctestplus/issues/107>`__
+to facilitate updates.
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
@@ -657,9 +657,9 @@ objects as inputs and returns an iterator that returns tuples
 providing each of the input sequence elements in the broadcasted
 result.
 
->>> for val in np.broadcast([[1,0],[2,3]],[0,1]):
+>>> for val in np.broadcast([[1, 0], [2, 3]], [0, 1]):
 ...     print(val)
-(1, 0)
-(0, 1)
-(2, 0)
-(3, 1)
+(np.int64(1), np.int64(0))
+(np.int64(0), np.int64(1))
+(np.int64(2), np.int64(0))
+(np.int64(3), np.int64(1))
diff --git a/doc/source/reference/arrays.datetime.rst b/doc/source/reference/arrays.datetime.rst
@@ -62,32 +62,32 @@ letters, for a "Not A Time" value.
     A simple ISO date:
 
     >>> np.datetime64('2005-02-25')
-    numpy.datetime64('2005-02-25')
+    np.datetime64('2005-02-25')
 
     From an integer and a date unit, 1 year since the UNIX epoch:
 
     >>> np.datetime64(1, 'Y')
-    numpy.datetime64('1971')
+    np.datetime64('1971')
 
     Using months for the unit:
 
     >>> np.datetime64('2005-02')
-    numpy.datetime64('2005-02')
+    np.datetime64('2005-02')
 
     Specifying just the month, but forcing a 'days' unit:
 
     >>> np.datetime64('2005-02', 'D')
-    numpy.datetime64('2005-02-01')
+    np.datetime64('2005-02-01')
 
     From a date and time:
 
     >>> np.datetime64('2005-02-25T03:30')
-    numpy.datetime64('2005-02-25T03:30')
+    np.datetime64('2005-02-25T03:30')
 
     NAT (not a time):
 
     >>> np.datetime64('nat')
-    numpy.datetime64('NaT')
+    np.datetime64('NaT')
 
 When creating an array of datetimes from a string, it is still possible
 to automatically select the unit from the inputs, by using the
@@ -168,39 +168,39 @@ data type also accepts the string "NAT" in place of the number for a "Not A Time
 .. admonition:: Example
 
     >>> np.timedelta64(1, 'D')
-    numpy.timedelta64(1,'D')
+    np.timedelta64(1,'D')
 
     >>> np.timedelta64(4, 'h')
-    numpy.timedelta64(4,'h')
+    np.timedelta64(4,'h')
 
     >>> np.timedelta64('nAt')
-    numpy.timedelta64('NaT')
+    np.timedelta64('NaT')
 
 Datetimes and Timedeltas work together to provide ways for
 simple datetime calculations.
 
 .. admonition:: Example
 
     >>> np.datetime64('2009-01-01') - np.datetime64('2008-01-01')
-    numpy.timedelta64(366,'D')
+    np.timedelta64(366,'D')
 
     >>> np.datetime64('2009') + np.timedelta64(20, 'D')
-    numpy.datetime64('2009-01-21')
+    np.datetime64('2009-01-21')
 
     >>> np.datetime64('2011-06-15T00:00') + np.timedelta64(12, 'h')
-    numpy.datetime64('2011-06-15T12:00')
+    np.datetime64('2011-06-15T12:00')
 
     >>> np.timedelta64(1,'W') / np.timedelta64(1,'D')
     7.0
 
     >>> np.timedelta64(1,'W') % np.timedelta64(10,'D')
-    numpy.timedelta64(7,'D')
+    np.timedelta64(7,'D')
 
     >>> np.datetime64('nat') - np.datetime64('2009-01-01')
-    numpy.timedelta64('NaT','D')
+    np.timedelta64('NaT','D')
 
     >>> np.datetime64('2009-01-01') + np.timedelta64('nat')
-    numpy.datetime64('NaT')
+    np.datetime64('NaT')
 
 There are two Timedelta units ('Y', years and 'M', months) which are treated
 specially, because how much time they represent changes depending
@@ -289,10 +289,10 @@ specified in business days to datetimes with a unit of 'D' (day).
 .. admonition:: Example
 
     >>> np.busday_offset('2011-06-23', 1)
-    numpy.datetime64('2011-06-24')
+    np.datetime64('2011-06-24')
 
     >>> np.busday_offset('2011-06-23', 2)
-    numpy.datetime64('2011-06-27')
+    np.datetime64('2011-06-27')
 
 When an input date falls on the weekend or a holiday,
 :func:`busday_offset` first applies a rule to roll the
@@ -308,16 +308,16 @@ The rules most typically used are 'forward' and 'backward'.
     ValueError: Non-business day date in busday_offset
 
     >>> np.busday_offset('2011-06-25', 0, roll='forward')
-    numpy.datetime64('2011-06-27')
+    np.datetime64('2011-06-27')
 
     >>> np.busday_offset('2011-06-25', 2, roll='forward')
-    numpy.datetime64('2011-06-29')
+    np.datetime64('2011-06-29')
 
     >>> np.busday_offset('2011-06-25', 0, roll='backward')
-    numpy.datetime64('2011-06-24')
+    np.datetime64('2011-06-24')
 
     >>> np.busday_offset('2011-06-25', 2, roll='backward')
-    numpy.datetime64('2011-06-28')
+    np.datetime64('2011-06-28')
 
 In some cases, an appropriate use of the roll and the offset
 is necessary to get a desired answer.
@@ -327,16 +327,16 @@ is necessary to get a desired answer.
     The first business day on or after a date:
 
     >>> np.busday_offset('2011-03-20', 0, roll='forward')
-    numpy.datetime64('2011-03-21')
+    np.datetime64('2011-03-21')
     >>> np.busday_offset('2011-03-22', 0, roll='forward')
-    numpy.datetime64('2011-03-22')
+    np.datetime64('2011-03-22')
 
     The first business day strictly after a date:
 
     >>> np.busday_offset('2011-03-20', 1, roll='backward')
-    numpy.datetime64('2011-03-21')
+    np.datetime64('2011-03-21')
     >>> np.busday_offset('2011-03-22', 1, roll='backward')
-    numpy.datetime64('2011-03-23')
+    np.datetime64('2011-03-23')
 
 The function is also useful for computing some kinds of days
 like holidays. In Canada and the U.S., Mother's day is on
@@ -346,7 +346,7 @@ weekmask.
 .. admonition:: Example
 
     >>> np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun')
-    numpy.datetime64('2012-05-13')
+    np.datetime64('2012-05-13')
 
 When performance is important for manipulating many business dates
 with one particular choice of weekmask and holidays, there is

diff --git a/doc/source/reference/maskedarray.generic.rst b/doc/source/reference/maskedarray.generic.rst
@@ -117,7 +117,7 @@ There are several ways to construct a masked array.
      >>> x.view(ma.MaskedArray)
      masked_array(data=[(1, 1.0), (2, 2.0)],
                   mask=[(False, False), (False, False)],
-            fill_value=(999999, 1.e+20),
+            fill_value=(999999, 1e+20),
                  dtype=[('a', '<i8'), ('b', '<f8')])
 
 * Yet another possibility is to use any of the following functions:

diff --git a/doc/source/user/absolute_beginners.rst b/doc/source/user/absolute_beginners.rst
@@ -581,10 +581,11 @@ example::
 
   >>> for coord in list_of_coordinates:
   ...     print(coord)
-  (0, 0)
-  (0, 1)
-  (0, 2)
-  (0, 3)
+  (np.int64(0), np.int64(0))
+  (np.int64(0), np.int64(1))
+  (np.int64(0), np.int64(2))
+  (np.int64(0), np.int64(3))
+
 
 You can also use ``np.nonzero()`` to print the elements in an array that are less
 than 5 with::

diff --git a/doc/source/user/basics.rec.rst b/doc/source/user/basics.rec.rst
@@ -24,7 +24,7 @@ a 32-bit integer named 'age', and 3. a 32-bit float named 'weight'.
 If you index ``x`` at position 1 you get a structure::
 
  >>> x[1]
- ('Fido', 3, 27.)
+ np.void(('Fido', 3, 27.0), dtype=[('name', '<U10'), ('age', '<i4'), ('weight', '<f4')])
 
 You can access and modify individual fields of a structured array by indexing
 with the field name::
@@ -515,7 +515,7 @@ a structured scalar::
  >>> x = np.array([(1, 2., 3.)], dtype='i, f, f')
  >>> scalar = x[0]
  >>> scalar
- (1, 2., 3.)
+ np.void((1, 2.0, 3.0), dtype=[('f0', '<i4'), ('f1', '<f4'), ('f2', '<f4')])
  >>> type(scalar)
  <class 'numpy.void'>
 

diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
@@ -4663,7 +4663,7 @@
 
     >>> x[0] = (9, 10)
     >>> z[0]
-    (9, 10)
+    np.record((9, 10), dtype=[('a', 'i1'), ('b', 'i1')])
 
     Views that change the dtype size (bytes per entry) should normally be
     avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

diff --git a/numpy/core/_add_newdocs_scalars.py b/numpy/core/_add_newdocs_scalars.py
@@ -267,13 +267,13 @@ def add_newdoc_for_scalar_type(obj, fixed_aliases, doc):
     Examples
     --------
     >>> np.void(5)
-    void(b'\x00\x00\x00\x00\x00')
+    np.void(b'\x00\x00\x00\x00\x00')
     >>> np.void(b'abcd')
-    void(b'\x61\x62\x63\x64')
-    >>> np.void((5, 3.2, "eggs"), dtype="i,d,S5")
-    (5, 3.2, b'eggs')  # looks like a tuple, but is `np.void`
+    np.void(b'\x61\x62\x63\x64')
+    >>> np.void((3.2, b'eggs'), dtype="d,S5")
+    np.void((3.2, b'eggs'), dtype=[('f0', '<f8'), ('f1', 'S5')])
     >>> np.void(3, dtype=[('x', np.int8), ('y', np.int8)])
-    (3, 3)  # looks like a tuple, but is `np.void`
+    np.void((3, 3), dtype=[('x', 'i1'), ('y', 'i1')])
 
     """)
 

diff --git a/numpy/core/_ufunc_config.py b/numpy/core/_ufunc_config.py
@@ -379,7 +379,7 @@ class errstate:
     array([nan, inf, inf])
 
     >>> np.sqrt(-1)
-    nan
+    np.float64(nan)
     >>> with np.errstate(invalid='raise'):
     ...     np.sqrt(-1)
     Traceback (most recent call last):

diff --git a/numpy/core/arrayprint.py b/numpy/core/arrayprint.py
@@ -88,12 +88,14 @@ def _make_options_dict(precision=None, threshold=None, edgeitems=None,
         options['legacy'] = 113
     elif legacy == '1.21':
         options['legacy'] = 121
+    elif legacy == '1.25':
+        options['legacy'] = 125
     elif legacy is None:
         pass  # OK, do nothing.
     else:
         warnings.warn(
-            "legacy printing option can currently only be '1.13', '1.21', or "
-            "`False`", stacklevel=3)
+            "legacy printing option can currently only be '1.13', '1.21', "
+            "'1.25', or `False`", stacklevel=3)
 
     if threshold is not None:
         # forbid the bad threshold arg suggested by stack overflow, gh-12351
@@ -288,6 +290,8 @@ def set_printoptions(precision=None, threshold=None, edgeitems=None,
         _format_options['sign'] = '-'
     elif _format_options['legacy'] == 121:
         set_legacy_print_mode(121)
+    elif _format_options['legacy'] == 125:
+        set_legacy_print_mode(125)
     elif _format_options['legacy'] == sys.maxsize:
         set_legacy_print_mode(0)
 
@@ -321,7 +325,7 @@ def get_printoptions():
     """
     opts = _format_options.copy()
     opts['legacy'] = {
-        113: '1.13', 121: '1.21', sys.maxsize: False,
+        113: '1.13', 121: '1.21', 125: '1.25', sys.maxsize: False,
     }[opts['legacy']]
     return opts
 
@@ -395,9 +399,13 @@ def _object_format(o):
     return fmt.format(o)
 
 def repr_format(x):
+    if isinstance(x, (np.str_, np.bytes_)):
+        return repr(x.item())
     return repr(x)
 
 def str_format(x):
+    if isinstance(x, (np.str_, np.bytes_)):
+        return str(x.item())
     return str(x)
 
 def _get_formatdict(data, *, precision, floatmode, suppress, sign, legacy,
@@ -1400,13 +1408,23 @@ def __call__(self, x):
             return "({})".format(", ".join(str_fields))
 
 
-def _void_scalar_repr(x):
+def _void_scalar_to_string(x, is_repr=True):
     """
     Implements the repr for structured-void scalars. It is called from the
     scalartypes.c.src code, and is placed here because it uses the elementwise
     formatters defined above.
     """
-    return StructuredVoidFormat.from_data(array(x), **_format_options)(x)
+    options = _format_options.copy()
+    if options.get('formatter') is None:
+        options['formatter'] = {}
+    options['formatter'].setdefault('float_kind', str)
+    val_repr = StructuredVoidFormat.from_data(array(x), **options)(x)
+    if not is_repr:
+        return val_repr
+    cls = type(x)
+    cls_fqn = cls.__module__.replace("numpy", "np") + "." + cls.__name__
+    void_dtype = np.dtype((np.void, x.dtype))
+    return f"{cls_fqn}({val_repr}, dtype={void_dtype!s})"
 
 
 _typelessdata = [int_, float_, complex_, bool_]

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
@@ -2786,7 +2786,7 @@ def max(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,
     >>> b = np.arange(5, dtype=float)
     >>> b[2] = np.NaN
     >>> np.max(b)
-    nan
+    np.float64(nan)
     >>> np.max(b, where=~np.isnan(b), initial=-1)
     4.0
     >>> np.nanmax(b)
@@ -2930,7 +2930,7 @@ def min(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,
     >>> b = np.arange(5, dtype=float)
     >>> b[2] = np.NaN
     >>> np.min(b)
-    nan
+    np.float64(nan)
     >>> np.min(b, where=~np.isnan(b), initial=10)
     0.0
     >>> np.nanmin(b)

diff --git a/numpy/core/function_base.py b/numpy/core/function_base.py
@@ -505,9 +505,9 @@ def add_newdoc(place, obj, doc, warn_on_python=True):
     ----------
     place : str
         The absolute name of the module to import from
-    obj : str
+    obj : str or None
         The name of the object to add documentation to, typically a class or
-        function name
+        function name.
     doc : {str, Tuple[str, str], List[Tuple[str, str]]}
         If a string, the documentation to apply to `obj`