DOC: Clarify the type alias deprecation message

This tries to clarify the type alias deprecation message slightly
to give more guidance on how to review the replacement (if desired).

2 files changed, 99 insertions, 47 deletions

diff --git a/doc/source/release/1.20.0-notes.rst b/doc/source/release/1.20.0-notes.rst
index e26aa0d40..d191e9ee1 100644
--- a/doc/source/release/1.20.0-notes.rst
+++ b/doc/source/release/1.20.0-notes.rst
@@ -75,32 +75,59 @@ Using the aliases of builtin types like ``np.int`` is deprecated
 ----------------------------------------------------------------
 
 For a long time, ``np.int`` has been an alias of the builtin ``int``. This is
-repeatedly a cause of confusion for newcomers, and is also simply not useful.
+repeatedly a cause of confusion for newcomers, and existed mainly for historic
+reasons.
 
 These aliases have been deprecated. The table below shows the full list of
 deprecated aliases, along with their exact meaning. Replacing uses of items in
 the first column with the contents of the second column will work identically
 and silence the deprecation warning.
 
-In many cases, it may have been intended to use the types from the third column.
-Be aware that use of these types may result in subtle but desirable behavior
-changes.
-
-==================  =================================  ==================================================================
-Deprecated name     Identical to                       Possibly intended numpy type
-==================  =================================  ==================================================================
-``numpy.bool``      ``bool``                           `numpy.bool_`
-``numpy.int``       ``int``                            `numpy.int_` (default int dtype), `numpy.cint` (C ``int``)
-``numpy.float``     ``float``                          `numpy.float_`, `numpy.double` (equivalent)
-``numpy.complex``   ``complex``                        `numpy.complex_`, `numpy.cdouble` (equivalent)
-``numpy.object``    ``object``                         `numpy.object_`
-``numpy.str``       ``str``                            `numpy.str_`
-``numpy.long``      ``int`` (``long`` on Python 2)     `numpy.int_` (C ``long``), `numpy.longlong` (largest integer type)
-``numpy.unicode``   ``str`` (``unicode`` on Python 2)  `numpy.unicode_`
-==================  =================================  ==================================================================
-
-Note that for technical reasons these deprecation warnings will only be emitted
-on Python 3.7 and above.
+The third column lists alternative NumPy names which may occasionally be
+preferential. See also :doc:`user/basics.types` for additional details.
+
+=================  ============  ==================================================================
+Deprecated name    Identical to  NumPy scalar type names
+=================  ============  ==================================================================
+``numpy.bool``     ``bool``      `numpy.bool_`
+``numpy.int``      ``int``       `numpy.int_` (default), ``numpy.int64``, or ``numpy.int32``
+``numpy.float``    ``float``     `numpy.float64`, `numpy.float_`, `numpy.double` (equivalent)
+``numpy.complex``  ``complex``   `numpy.complex128`, `numpy.complex_`, `numpy.cdouble` (equivalent)
+``numpy.object``   ``object``    `numpy.object_`
+``numpy.str``      ``str``       `numpy.str_`
+``numpy.long``     ``int``       `numpy.int_` (C ``long``), `numpy.longlong` (largest integer type)
+``numpy.unicode``  ``str``       `numpy.unicode_`
+=================  ============  ==================================================================
+
+To give a clear guideline for the vast majority of cases, for the types
+``bool``, ``object``, ``str`` (and ``unicode``) using the plain version
+is shorter and clear, and generally a good replacement.
+For ``float`` and ``complex`` you can use ``float64`` and ``complex128``
+if you wish to be more explicit about the precision.
+
+For ``np.int`` a direct replacement with ``np.int_`` or ``int`` is also
+good, but the precision depends on the computer and operating system.
+If you want to be more explicit and review the current use, you have the
+following alternatives:
+
+* ``np.int64`` or ``np.int32`` to specify the precision exactly.
+  This ensures that results cannot depend on the computer or operating system.
+* ``np.int_`` or ``int`` (the default), but be aware that it depends on
+  the computer and operating system.
+* The C types: ``np.cint`` (int), ``np.int_`` (long), ``np.longlong``,
+* ``np.intp`` which is 32bit on 32bit machines 64bit on 64bit machines.
+  This can be the best type to use for indexing.
+
+When used with ``np.dtype(...)`` or ``dtype=...`` changing it to the
+NumPy name as mentioned above will have no effect on the output.
+If used as a scalar with::
+
+    np.float(123)
+
+changing it can subtly change the result.  In this case, the Python version
+``float(123)`` or ``int(12.)`` is normally preferable, although the NumPy
+version may be useful for consistency with NumPy arrays. For example, since
+NumPy behaves differently for things like division by zero.
 
 (`gh-14882 <https://github.com/numpy/numpy/pull/14882>`__)
 
diff --git a/numpy/__init__.py b/numpy/__init__.py
index a242bb7df..3fadc7a10 100644
--- a/numpy/__init__.py
+++ b/numpy/__init__.py
@@ -165,33 +165,58 @@ else:
 
     # Deprecations introduced in NumPy 1.20.0, 2020-06-06
     import builtins as _builtins
-    __deprecated_attrs__.update({
-        n: (
-            getattr(_builtins, n),
-            "`np.{n}` is a deprecated alias for the builtin `{n}`. "
-            "Use `{n}` by itself, which is identical in behavior, to silence "
-            "this warning. "
-            "If you specifically wanted the numpy scalar type, use `np.{n}_` "
-            "here."
-            .format(n=n)
-        )
-        for n in ["bool", "int", "float", "complex", "object", "str"]
-    })
-    __deprecated_attrs__.update({
-        n: (
-            getattr(compat, n),
-            "`np.{n}` is a deprecated alias for `np.compat.{n}`. "
-            "Use `np.compat.{n}` by itself, which is identical in behavior, "
-            "to silence this warning. "
-            "In the likely event your code does not need to work on Python 2 "
-            "you can use the builtin ``{n2}`` for which ``np.compat.{n}`` is "
-            "itself an alias. "
-            "If you specifically wanted the numpy scalar type, use `np.{n2}_` "
-            "here."
-            .format(n=n, n2=n2)
-        )
-        for n, n2 in [("long", "int"), ("unicode", "str")]
-    })
+
+    _msg = (
+        "`np.{n}` is a deprecated alias for the builtin `{n}`. "
+        "To silence this warning, use `{n}` by itself. Doing this will not "
+        "modify any behavior and is safe. {extended_msg}\n"
+        "Deprecated in NumPy 1.20; for more details and guidance: "
+        "https://numpy.org/devdocs/release/1.20.0-notes.html#deprecations")
+
+    _specific_msg = (
+        "If you specifically wanted the numpy scalar type, use `np.{}` here.")
+
+    _int_extended_msg = (
+        "When replacing `np.{}`, you may wish to use e.g. `np.int64` "
+        "or `np.int32` to specify the precision. If you wish to review "
+        "your current use check the release note link for "
+        "additional information.")
+
+    _type_info = [
+        ("object", ""),  # The NumPy scalar only exists by name.
+        ("bool", _specific_msg.format("bool_")),
+        ("float", _specific_msg.format("float64")),
+        ("complex", _specific_msg.format("complex128")),
+        ("str", _specific_msg.format("str_")),
+        ("int", _int_extended_msg.format("int"))]
+
+    for n, extended_msg in _type_info:
+        __deprecated_attrs__[n] = (getattr(_builtins, n),
+                                   _msg.format(n=n, extended_msg=extended_msg))
+
+    del n, extended_msg
+
+    _msg = (
+        "`np.{n}` is a deprecated alias for `np.compat.{n}`. "
+        "To silence this warning, use `np.compat.{n}` by itself. "
+        "In the likely event your code does not need to work on Python 2 "
+        "you can use the builtin `{n2}` for which `np.compat.{n}` is itself "
+        "an alias. Doing this will not modify any behaviour and is safe. "
+        "{extended_msg}\n"
+        "Deprecated in NumPy 1.20; for more details and guidance: "
+        "https://numpy.org/devdocs/release/1.20.0-notes.html#deprecations")
+
+    __deprecated_attrs__["long"] = (
+        getattr(compat, "long"),
+        _msg.format(n="long", n2="int",
+                    extended_msg=_int_extended_msg.format("long")))
+
+    __deprecated_attrs__["unicode"] = (
+        getattr(compat, "long"),
+        _msg.format(n="unciode", n2="str",
+                    extended_msg=_specific_msg.format("str_")))
+
+    del _msg, _specific_msg, _int_extended_msg, _type_info, _builtins
 
     from .core import round, abs, max, min
     # now that numpy modules are imported, can initialize limits