[Python-checkins] bpo-46480: add typing.assert_type (GH-30843)
JelleZijlstra
webhook-mailer at python.org
Wed Mar 16 23:02:40 EDT 2022
https://github.com/python/cpython/commit/96568e995d840c66edb25b6b9d85e4dcccf5a936
commit: 96568e995d840c66edb25b6b9d85e4dcccf5a936
branch: main
author: Jelle Zijlstra <jelle.zijlstra at gmail.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-03-16T20:02:26-07:00
summary:
bpo-46480: add typing.assert_type (GH-30843)
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
Co-authored-by: David Foster <david at dafoster.net>
files:
A Misc/NEWS.d/next/Library/2022-01-23-16-33-07.bpo-46480.E4jHlh.rst
M Doc/library/typing.rst
M Lib/test/test_typing.py
M Lib/typing.py
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index c7c2cd6866b70..57979cbb08e69 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -2148,6 +2148,31 @@ 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 *val* has an inferred type of *typ*.
+
+ 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, inferred type of `name` is `str`
+ assert_type(name, int) # type checker error
+
+ At runtime this returns the first argument unchanged with no side effects.
+
+ This function is useful for ensuring the type checker's understanding of a
+ script is in line with the developer's intentions::
+
+ def complex_function(arg: object):
+ # Do some complex type-narrowing logic,
+ # after which we hope the inferred type will be `int`
+ ...
+ # Test whether the type checker correctly understands our function
+ assert_type(arg, int)
+
+ .. versionadded:: 3.11
+
.. function:: assert_never(arg, /)
Assert to the type checker that a line of code is unreachable.
diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py
index b212b52304880..e88f7322b2fa8 100644
--- a/Lib/test/test_typing.py
+++ b/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
@@ -3302,6 +3302,22 @@ 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.
+ arg = 42
+ self.assertIs(assert_type(arg, 42), arg)
+ self.assertIs(assert_type(arg, 'hello'), arg)
+
+
# We need this to make sure that `@no_type_check` respects `__module__` attr:
from test import ann_module8
diff --git a/Lib/typing.py b/Lib/typing.py
index dd68e71db1558..6930f5ddac42a 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -118,6 +118,7 @@ def _idfunc(_, x):
# One-off things.
'AnyStr',
+ 'assert_type',
'assert_never',
'cast',
'final',
@@ -2093,6 +2094,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 and otherwise
+ does nothing.
+ """
+ return val
+
+
_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
types.MethodType, types.ModuleType,
WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
diff --git a/Misc/NEWS.d/next/Library/2022-01-23-16-33-07.bpo-46480.E4jHlh.rst b/Misc/NEWS.d/next/Library/2022-01-23-16-33-07.bpo-46480.E4jHlh.rst
new file mode 100644
index 0000000000000..fd18a8198edea
--- /dev/null
+++ b/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.
More information about the Python-checkins
mailing list