8000 [3.12] gh-117492: Clarify documentation of `typing.Never` (GH-117678) by miss-islington · Pull Request #118547 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 3, 2024
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 22 additions & 24 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
`bot 6295 tom 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

Expand Down
Loading
0