From 080cc2147d2cf8aa574d047cd44a36d207e18af4 Mon Sep 17 00:00:00 2001 From: nineteendo Date: Tue, 9 Apr 2024 16:35:40 +0200 Subject: [PATCH 01/11] Clarify documentation of `typing.NoReturn` & `typing.Never` --- Doc/library/typing.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 19dbd376c80d511..982476d40ee7cbc 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -857,7 +857,7 @@ using ``[]``. 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:: + called, as there are no valid arguments:: from typing import Never @@ -874,10 +874,15 @@ using ``[]``. case _: never_call_me(arg) # OK, arg is of type Never + ``Never`` can also be used to indicate that a function never returns, + but ``NoReturn`` is more explicit. + .. 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. + On older Python versions, :data:`NoReturn` may be used as a + replacement for ``Never``, which was added to make the use as a + `bottom type `_ more + explicit. Type checkers should treat the two equivalently. .. data:: NoReturn @@ -893,8 +898,8 @@ using ``[]``. ``NoReturn`` can also be used as a `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. + be used for this instead, and ``Never`` should only be used as return + annotation. Type checkers should treat the two equivalently. .. versionadded:: 3.6.2 From fc5e49c45045bba888f8f2df722c5b7fac9c098b Mon Sep 17 00:00:00 2001 From: Nice Zombies Date: Tue, 9 Apr 2024 16:41:43 +0200 Subject: [PATCH 02/11] Update Doc/library/typing.rst Co-authored-by: Jelle Zijlstra --- Doc/library/typing.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 982476d40ee7cbc..3348f206710b0b6 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -898,8 +898,7 @@ using ``[]``. ``NoReturn`` can also be used as a `bottom type `_, a type that has no values. Starting in Python 3.11, the :data:`Never` type should - be used for this instead, and ``Never`` should only be used as return - annotation. Type checkers should treat the two equivalently. + be used for this instead. Type checkers should treat the two equivalently. .. versionadded:: 3.6.2 From ca9a4fe38cc6829f37c7bb831abea24b01de0a58 Mon Sep 17 00:00:00 2001 From: nineteendo Date: Fri, 12 Apr 2024 09:05:38 +0200 Subject: [PATCH 03/11] Revert minor change --- Doc/library/typing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 3348f206710b0b6..a4538d8b4e77272 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -898,7 +898,8 @@ using ``[]``. ``NoReturn`` can also be used as a `bottom type `_, a type that has no values. Starting in Python 3.11, the :data:`Never` type should - be used for this instead. Type checkers should treat the two equivalently. + be used for this concept instead. Type checkers should treat the two + equivalently. .. versionadded:: 3.6.2 From 1b3c55cff24181ca09b8bbc1e546edef6b4b1098 Mon Sep 17 00:00:00 2001 From: Nice Zombies Date: Sat, 13 Apr 2024 12:01:09 +0200 Subject: [PATCH 04/11] Deprecate `NoReturn` --- Doc/library/typing.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index a4538d8b4e77272..57a46b4b2a8ed2f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1,4 +1,4 @@ -======================================== +========================================https://github.com/nineteendo/cpython/blob/improve-typing.never-docs/Doc/library/typing.rst :mod:`typing` --- Support for type hints ======================================== @@ -874,8 +874,12 @@ using ``[]``. case _: never_call_me(arg) # OK, arg is of type Never - ``Never`` can also be used to indicate that a function never returns, - but ``NoReturn`` is more explicit. + ``Never`` can also be used to indicate that a function never returns:: + + from typing import Never + + def stop() -> Never: + raise RuntimeError('no way') .. versionadded:: 3.11 @@ -903,6 +907,10 @@ using ``[]``. .. versionadded:: 3.6.2 + .. deprecated-removed:: 3.13 3.18 + :data:`NoReturn` is deprecated in favor of the :data:`Never` type. + ``NoReturn`` will be removed from ``typing`` in Python 3.18. + .. data:: Self Special type to represent the current enclosed class. From 61d4d5582b5f58bebb1a7884f7eeacf3911e35a9 Mon Sep 17 00:00:00 2001 From: Nice Zombies Date: Sat, 13 Apr 2024 12:02:01 +0200 Subject: [PATCH 05/11] Remove link --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 57a46b4b2a8ed2f..f1197e68dfe476a 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1,4 +1,4 @@ -========================================https://github.com/nineteendo/cpython/blob/improve-typing.never-docs/Doc/library/typing.rst +======================================== :mod:`typing` --- Support for type hints ======================================== From 48587ba13fb8a1bfd9c34eab9503856d31bc8869 Mon Sep 17 00:00:00 2001 From: nineteendo Date: Sat, 13 Apr 2024 12:30:44 +0200 Subject: [PATCH 06/11] Revert "Deprecate `NoReturn`" This reverts commit 1b3c55cff24181ca09b8bbc1e546edef6b4b1098. --- Doc/library/typing.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index f1197e68dfe476a..a4538d8b4e77272 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -874,12 +874,8 @@ using ``[]``. case _: never_call_me(arg) # OK, arg is of type Never - ``Never`` can also be used to indicate that a function never returns:: - - from typing import Never - - def stop() -> Never: - raise RuntimeError('no way') + ``Never`` can also be used to indicate that a function never returns, + but ``NoReturn`` is more explicit. .. versionadded:: 3.11 @@ -907,10 +903,6 @@ using ``[]``. .. versionadded:: 3.6.2 - .. deprecated-removed:: 3.13 3.18 - :data:`NoReturn` is deprecated in favor of the :data:`Never` type. - ``NoReturn`` will be removed from ``typing`` in Python 3.18. - .. data:: Self Special type to represent the current enclosed class. From b1fd7c28d619a234ca3a85d25ff210659776304d Mon Sep 17 00:00:00 2001 From: nineteendo Date: Sat, 13 Apr 2024 17:59:59 +0200 Subject: [PATCH 07/11] Remove style suggestion --- Doc/library/typing.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index a4538d8b4e77272..cb8863f2bd224a7 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -874,8 +874,15 @@ using ``[]``. case _: never_call_me(arg) # OK, arg is of type Never - ``Never`` can also be used to indicate that a function never returns, - but ``NoReturn`` is more explicit. + ``Never`` can also be used to indicate that a function never returns:: + + from typing import Never + + def stop() -> Never: + raise RuntimeError('no way') + + You can also use :data:`NoReturn` for this purpose. Decide which notation + you prefer. .. versionadded:: 3.11 @@ -895,6 +902,9 @@ using ``[]``. def stop() -> NoReturn: raise RuntimeError('no way') + You can also use :data:`Never` for this purpose. Decide which notation + you prefer. + ``NoReturn`` can also be used as a `bottom type `_, a type that has no values. Starting in Python 3.11, the :data:`Never` type should From ddfc31e97eb146567007e558f1b39904a5b70050 Mon Sep 17 00:00:00 2001 From: nineteendo Date: Thu, 18 Apr 2024 09:27:05 +0200 Subject: [PATCH 08/11] Merge documentation of `Never` & `NoReturn` --- Doc/library/typing.rst | 49 ++++++++++++++---------------------------- 1 file changed, 16 insertions(+), 33 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index cb8863f2bd224a7..d67ace28bf400af 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -852,14 +852,16 @@ using ``[]``. .. versionadded:: 3.11 .. data:: Never +.. data:: NoReturn - The `bottom type `_, - a type that has no members. + ``Never`` and ``NoReturn`` are + `bottom types `_, + types that have no members. - This can be used to define a function that should never be + They can be used to define a function that should never be called, as there are no valid arguments:: - from typing import Never + from typing import Never # or NoReturn def never_call_me(arg: Never) -> None: pass @@ -872,47 +874,28 @@ 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) - ``Never`` can also be used to indicate that a function never returns:: + Or to indicate that a function never returns:: - from typing import Never + from typing import Never # or NoReturn def stop() -> Never: raise RuntimeError('no way') - You can also use :data:`NoReturn` for this purpose. Decide which notation - you prefer. + ``Never`` and ``NoReturn`` have the same meaning in the type system. + Users may make a stylistic choice about which one is preferred in which context. + + .. versionadded:: 3.6.2 + + Added ``NoReturn``. .. versionadded:: 3.11 - On older Python versions, :data:`NoReturn` may be used as a - replacement for ``Never``, which was added to make the use as a + Added ``Never``, to make the use as a `bottom type `_ more explicit. Type checkers should treat the two equivalently. -.. data:: NoReturn - - Special type indicating that a function never returns. - - For example:: - - from typing import NoReturn - - def stop() -> NoReturn: - raise RuntimeError('no way') - - You can also use :data:`Never` for this purpose. Decide which notation - you prefer. - - ``NoReturn`` can also be used as a - `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 - .. data:: Self Special type to represent the current enclosed class. From bd2c7adf0d9c9a1704f1d13bf8570482970b2db4 Mon Sep 17 00:00:00 2001 From: nineteendo Date: Thu, 18 Apr 2024 09:36:44 +0200 Subject: [PATCH 09/11] Remove empty line --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d67ace28bf400af..d5f81fd9d8570ff 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -852,7 +852,7 @@ using ``[]``. .. versionadded:: 3.11 .. data:: Never -.. data:: NoReturn + NoReturn ``Never`` and ``NoReturn`` are `bottom types `_, From 6d693709ec7e0db3d9ba89ec7235e0e6aef0d600 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 28 Apr 2024 15:42:48 -0700 Subject: [PATCH 10/11] Reword --- Doc/library/typing.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d5f81fd9d8570ff..eea8bafa7d6351a 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -854,12 +854,21 @@ using ``[]``. .. data:: Never NoReturn - ``Never`` and ``NoReturn`` are - `bottom types `_, - types that have no members. + ``Never`` and ``NoReturn`` represent the + `bottom type `_, + a type that has no members. - They can be used to define a function that should never be - called, as there are no valid arguments:: + They can be used to indicate that a function never returns, + such as :func:`sys.exit`:: + + 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 @@ -876,15 +885,8 @@ using ``[]``. case _: never_call_me(arg) # OK, arg is of type Never (or NoReturn) - Or to indicate that a function never returns:: - - from typing import Never # or NoReturn - - def stop() -> Never: - raise RuntimeError('no way') - - ``Never`` and ``NoReturn`` have the same meaning in the type system. - Users may make a stylistic choice about which one is preferred in which context. + ``Never`` and ``NoReturn`` have the same meaning in the type system + and static type checkers treat both equivalently. .. versionadded:: 3.6.2 @@ -892,9 +894,7 @@ using ``[]``. .. versionadded:: 3.11 - Added ``Never``, to make the use as a - `bottom type `_ more - explicit. Type checkers should treat the two equivalently. + Added ``Never``. .. data:: Self From acf6196f84df6346d3b1b7f0d10eb5c07c19a4e6 Mon Sep 17 00:00:00 2001 From: Nice Zombies Date: Fri, 3 May 2024 08:34:21 +0200 Subject: [PATCH 11/11] Apply suggestions from code review Co-authored-by: Erlend E. Aasland --- Doc/library/typing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index eea8bafa7d6351a..076eab955bea39b 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -854,7 +854,7 @@ using ``[]``. .. data:: Never NoReturn - ``Never`` and ``NoReturn`` represent the + :data:`!Never` and :data:`!NoReturn` represent the `bottom type `_, a type that has no members. @@ -885,16 +885,16 @@ using ``[]``. case _: never_call_me(arg) # OK, arg is of type Never (or NoReturn) - ``Never`` and ``NoReturn`` have the same meaning in the type system + :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 ``NoReturn``. + Added :data:`NoReturn`. .. versionadded:: 3.11 - Added ``Never``. + Added :data:`Never`. .. data:: Self