https://github.com/python/cpython/commit/852263e1086748492602a90347ecc0a3925e1dda commit: 852263e1086748492602a90347ecc0a3925e1dda branch: main author: Nice Zombies <[email protected]> committer: JelleZijlstra <[email protected]> date: 2024-05-03T06:02:11-07:00 summary:
gh-117492: Clarify documentation of `typing.Never` (#117678) Co-authored-by: Jelle Zijlstra <[email protected]> Co-authored-by: Erlend E. Aasland <[email protected]> files: M Doc/library/typing.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d816e6368f40d2..573318bd76576b 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -852,14 +852,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 @@ -872,31 +883,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 _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
