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>
This commit is contained in:
Nice Zombies 2024-05-03 15:02:11 +02:00 committed by GitHub
parent f201628073
commit 852263e108
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 24 additions and 26 deletions

View File

@ -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
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