mirror of https://github.com/python/cpython
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:
parent
f201628073
commit
852263e108
|
@ -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
|
||||
|
||||
|
|
Loading…
Reference in New Issue