gh-117492: Clarify documentation of `typing.Never` (#117678)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index d816e63..573318b 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -852,14 +852,25 @@
.. 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
@@ -872,31 +883,18 @@
case str():
print("It's a str")
case _:
- never_call_me(arg) # OK, arg is of type Never
+ never_call_me(arg) # OK, arg is of type Never (or NoReturn)
+
+ :data:`!Never` and :data:`!NoReturn` have the same meaning in the type system
+ and static type checkers treat both equivalently.
+
+ .. versionadded:: 3.6.2
+
+ Added :data:`NoReturn`.
.. 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.
-
-.. data:: NoReturn
-
- Special type indicating that a function never returns.
-
- For example::
-
- from typing import 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.6.2
+ Added :data:`Never`.
.. data:: Self
