[3.12] gh-117492: Clarify documentation of typing.Never (GH-117678) (#118547)

(cherry picked from commit 852263e)

Co-authored-by: Jelle Zijlstra <[email protected]>
Co-authored-by: Nice Zombies <[email protected]>
Co-authored-by: Erlend E. Aasland <[email protected]>

Author: 4 people

Doc/library/typing.rst

@@ -842,14 +842,25 @@ using ``[]``.
    .. versionadded:: 3.11
 
 .. data:: Never
+          NoReturn
 
-   The `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_,
+   :data:`!Never` and :data:`!NoReturn` represent the
+   `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_,
    a type that has no members.
 
-   This can be used to define a function that should never be
-   called, or a function that never returns::
+   They can be used to indicate that a function never returns,
+   such as :func:`sys.exit`::
 
-      from typing import Never
+      from typing import Never  # or NoReturn
+
+      def stop() -> Never:
+          raise RuntimeError('no way')
+
+   Or to define a function that should never be
+   called, as there are no valid arguments, such as
+   :func:`assert_never`::
+
+      from typing import Never  # or NoReturn
 
       def never_call_me(arg: Never) -> None:
           pass
@@ -862,31 +873,18 @@ using ``[]``.
               case str():
                   print("It's a str")
               case _:
-                  never_call_me(arg)  # OK, arg is of type Never
-
-   .. versionadded:: 3.11
-
-      On older Python versions, :data:`NoReturn` may be used to express the
-      same concept. ``Never`` was added to make the intended meaning more explicit.
+                  never_call_me(arg)  # OK, arg is of type Never (or NoReturn)
 
-.. data:: NoReturn
+   :data:`!Never` and :data:`!NoReturn` have the same meaning in the type system
+   and static type checkers treat both equivalently.
 
-   Special type indicating that a function never returns.
-
-   For example::
+   .. versionadded:: 3.6.2
 
-      from typing import NoReturn
+      Added :data:`NoReturn`.
 
-      def stop() -> NoReturn:
-          raise RuntimeError('no way')
-
-   ``NoReturn`` can also be used as a
-   `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_, a type that
-   has no values. Starting in Python 3.11, the :data:`Never` type should
-   be used for this concept instead. Type checkers should treat the two
-   equivalently.
+   .. versionadded:: 3.11
 
-   .. versionadded:: 3.6.2
+      Added :data:`Never`.
 
 .. data:: Self