bpo-46480: add typing.assert_type

Doc/library/typing.rst

@@ -1932,6 +1932,21 @@ Functions and decorators
    runtime we intentionally don't check anything (we want this
    to be as fast as possible).
 
+.. function:: assert_type(val, typ, /)
+
+   Assert (to the type checker) that the value is of the given type.
+
+   When the type checker encounters a call to ``assert_type()``, it
+   emits an error if the value is not of the specified type::
+
+       def greet(name: str) -> None:
+           assert_type(name, str)  # ok
+           assert_type(name, int)  # type checker error
+
+   At runtime this returns the first argument unchanged.
+
+   .. versionadded:: 3.11
+
 .. function:: reveal_type(obj)
 
    Reveal the inferred static type of an expression.

Lib/test/test_typing.py

@@ -16,7 +16,7 @@
 from typing import Tuple, List, Dict, MutableMapping
 from typing import Callable
 from typing import Generic, ClassVar, Final, final, Protocol
-from typing import cast, runtime_checkable
+from typing import assert_type, cast, runtime_checkable
 from typing import get_type_hints
 from typing import get_origin, get_args
 from typing import is_typeddict
@@ -2670,6 +2670,21 @@ def test_errors(self):
         cast('hello', 42)
 
 
+class AssertTypeTests(BaseTestCase):
+
+    def test_basics(self):
+        arg = 42
+        self.assertIs(assert_type(arg, int), arg)
+        self.assertIs(assert_type(arg, str | float), arg)
+        self.assertIs(assert_type(arg, AnyStr), arg)
+        self.assertIs(assert_type(arg, None), arg)
+
+    def test_errors(self):
+        # Bogus calls are not expected to fail.
+        assert_type(42, 42)
+        assert_type(42, 'hello')
+
+
 class ForwardRefTests(BaseTestCase):
 
     def test_basics(self):

Lib/typing.py

@@ -117,6 +117,7 @@ def _idfunc(_, x):
 
     # One-off things.
     'AnyStr',
+    'assert_type',
     'cast',
     'final',
     'get_args',
@@ -1731,6 +1732,22 @@ def cast(typ, val):
     return val
 
 
+def assert_type(val, typ, /):
+    """Assert (to the type checker) that the value is of the given type.
+
+    When the type checker encounters a call to assert_type(), it
+    emits an error if the value is not of the specified type::
+
+        def greet(name: str) -> None:
+            assert_type(name, str)  # ok
+            assert_type(name, int)  # type checker error
+
+    At runtime this returns the first argument unchanged.
+
+    """
+    return val
+
+
 def _get_defaults(func):
     """Internal helper to extract the default arguments, by name."""
     try:

Misc/NEWS.d/next/Library/2022-01-23-16-33-07.bpo-46480.E4jHlh.rst

@@ -0,0 +1 @@
+Add :func:`typing.assert_type`. Patch by Jelle Zijlstra.