bpo-46475: Add typing.Never and typing.assert_never

Doc/library/typing.rst

@@ -572,6 +572,32 @@ These can be used as types in annotations and do not support ``[]``.
    * Every type is compatible with :data:`Any`.
    * :data:`Any` is compatible with every type.
 
+.. data:: Never
+
+   Notation for 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::
+
+     from typing import Never
+
+     def never_call_me(arg: Never) -> None:
+         pass
+
+     never_call_me(1)  # type checker error
+
+     def stop() -> Never:
+         return 1  # type checker error
+
+   The :func:`assert_never()` function uses the ``Never`` type to statically
+   assert that code is unreachable.
+
+   .. 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.
@@ -582,6 +608,11 @@ These can be used as types in annotations and do not support ``[]``.
       def stop() -> NoReturn:
           raise RuntimeError('no way')
 
+   ``NoReturn`` can also be used as a general
+   `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_, a type that
+   has no values. The :data:`Never` type provides a more explicit name for
+   the same concept. Type checkers should treat the two equivalently.
+
    .. versionadded:: 3.5.4
    .. versionadded:: 3.6.2
 
@@ -1932,6 +1963,28 @@ Functions and decorators
    runtime we intentionally don't check anything (we want this
    to be as fast as possible).
 
+.. function:: assert_never(arg, /)
+
+   Statically assert that a line of code is unreachable.
+
+   Example::
+
+       def int_or_str(arg: int | str) -> None:
+           match arg:
+               case int():
+                   print("It's an int")
+               case str():
+                   print("It's a str")
+               case _:
+                   assert_never(arg)
+
+   If a type checker finds that a call to ``assert_never()`` is
+   reachable, it will emit an error.
+
+   At runtime, this throws an exception when called.
+
+   .. versionadded:: 3.11
+
 .. decorator:: overload
 
    The ``@overload`` decorator allows describing functions and methods

Lib/test/test_typing.py

@@ -9,7 +9,7 @@
 from unittest import TestCase, main, skipUnless, skip
 from copy import copy, deepcopy
 
-from typing import Any, NoReturn
+from typing import Any, NoReturn, Never, assert_never
 from typing import TypeVar, AnyStr
 from typing import T, KT, VT  # Not in __all__.
 from typing import Union, Optional, Literal
@@ -156,6 +156,46 @@ def test_cannot_instantiate(self):
             type(NoReturn)()
 
 
+class NeverTests(BaseTestCase):
+
+    def test_never_instance_type_error(self):
+        with self.assertRaises(TypeError):
+            isinstance(42, Never)
+
+    def test_never_subclass_type_error(self):
+        with self.assertRaises(TypeError):
+            issubclass(Employee, Never)
+        with self.assertRaises(TypeError):
+            issubclass(Never, Employee)
+
+    def test_repr(self):
+        self.assertEqual(repr(Never), 'typing.Never')
+
+    def test_not_generic(self):
+        with self.assertRaises(TypeError):
+            Never[int]
+
+    def test_cannot_subclass(self):
+        with self.assertRaises(TypeError):
+            class A(Never):
+                pass
+        with self.assertRaises(TypeError):
+            class A(type(Never)):
+                pass
+
+    def test_cannot_instantiate(self):
+        with self.assertRaises(TypeError):
+            Never()
+        with self.assertRaises(TypeError):
+            type(Never)()
+
+
+class AssertNeverTests(BaseTestCase):
+    def test_exception(self):
+        with self.assertRaises(RuntimeError):
+            assert_never(None)
+
+
 class TypeVarTests(BaseTestCase):
 
     def test_basic_plain(self):

Lib/typing.py

@@ -5,7 +5,7 @@
 * Imports and exports, all public names should be explicitly added to __all__.
 * Internal helper functions: these should never be used in code outside this module.
 * _SpecialForm and its instances (special forms):
-  Any, NoReturn, ClassVar, Union, Optional, Concatenate
+  Any, NoReturn, Never, ClassVar, Union, Optional, Concatenate
 * Classes whose instances can be type arguments in addition to types:
   ForwardRef, TypeVar and ParamSpec
 * The core of internal generics API: _GenericAlias and _VariadicGenericAlias, the latter is
@@ -117,12 +117,14 @@ def _idfunc(_, x):
 
     # One-off things.
     'AnyStr',
+    'assert_never',
     'cast',
     'final',
     'get_args',
     'get_origin',
     'get_type_hints',
     'is_typeddict',
+    'Never',
     'NewType',
     'no_type_check',
     'no_type_check_decorator',
@@ -173,7 +175,7 @@ def _type_check(arg, msg, is_argument=True, module=None, *, is_class=False):
     if (isinstance(arg, _GenericAlias) and
             arg.__origin__ in invalid_generic_forms):
         raise TypeError(f"{arg} is not valid as type argument")
-    if arg in (Any, NoReturn, Final):
+    if arg in (Any, NoReturn, Never, Final):
         return arg
     if isinstance(arg, _SpecialForm) or arg in (Generic, Protocol):
         raise TypeError(f"Plain {arg} is not valid as type argument")
@@ -441,8 +443,32 @@ def NoReturn(self, parameters):
       def stop() -> NoReturn:
           raise Exception('no way')
 
-    This type is invalid in other positions, e.g., ``List[NoReturn]``
-    will fail in static type checkers.
+    Static type checkers treat this as a general bottom type,
+    a type with no members. The typing.Never type provides a
+    more explicit name for that concept.
+
+    """
+    raise TypeError(f"{self} is not subscriptable")
+
+@_SpecialForm
+def Never(self, parameters):
+    """Notation for the 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::
+
+      from typing import Never
+
+      def never_call_me(arg: Never) -> None:
+          pass
+
+      never_call_me(1)  # type checker error
+
+      def stop() -> Never:
+          return 1  # type checker error
+
+    The assert_never() function uses the Never type to statically
+    assert that code is unreachable.
     """
     raise TypeError(f"{self} is not subscriptable")
 
@@ -1941,6 +1967,29 @@ class Film(TypedDict):
     return isinstance(tp, _TypedDictMeta)
 
 
+def assert_never(arg: Never, /) -> Never:
+    """Statically assert that a line of code is unreachable.
+
+    Example::
+
+        def int_or_str(arg: int | str) -> None:
+            match arg:
+                case int():
+                    print("It's an int")
+                case str():
+                    print("It's a str")
+                case _:
+                    assert_never(arg)
+
+    If a type checker finds that a call to assert_never() is
+    reachable, it will emit an error.
+
+    At runtime, this throws an exception when called.
+
+    """
+    raise RuntimeError("Unreachable code")
+
+
 def no_type_check(arg):
     """Decorator to indicate that annotations are not type hints.
 

Misc/NEWS.d/next/Library/2022-01-23-15-35-07.bpo-46475.UCe18S.rst

@@ -0,0 +1,2 @@
+Add :data:`typing.Never` and :func:`typing.assert_never`. Patch by Jelle
+Zijlstra.