diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 6b2a0934171a29..217b2d221c6743 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2341,11 +2341,25 @@ Functions and decorators case _ as unreachable: assert_never(unreachable) + Here, the annotations allow the type checker to infer that the + last case can never execute, because ``arg`` is either + an :class:`int` or a :class:`str`, and both options are covered by + earlier cases. If a type checker finds that a call to ``assert_never()`` is - reachable, it will emit an error. + reachable, it will emit an error. For example, if the type annotation + for ``arg`` was instead ``int | str | float``, the type checker would + emit an error pointing out that ``unreachable`` is of type :class:`float`. + For a call to ``assert_never`` to succeed, the inferred type of + the argument passed in must be the bottom type, :data:`Never`, and nothing + else. At runtime, this throws an exception when called. + .. seealso:: + `Unreachable Code and Exhaustiveness Checking + _` has more + information about exhaustiveness checking with static typing. + .. versionadded:: 3.11 .. function:: reveal_type(obj) diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index d4808474e4fcee..f2a62ee213d062 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -211,6 +211,19 @@ def test_exception(self): with self.assertRaises(AssertionError): assert_never(None) + value = "some value" + with self.assertRaisesRegex(AssertionError, value): + assert_never(value) + + # Make sure a huge value doesn't get printed in its entirety + huge_value = "a" * 10000 + with self.assertRaises(AssertionError) as cm: + assert_never(huge_value) + self.assertLess( + len(cm.exception.args[0]), + typing._ASSERT_NEVER_REPR_MAX_LENGTH * 2, + ) + class SelfTests(BaseTestCase): def test_equality(self): diff --git a/Lib/typing.py b/Lib/typing.py index 3e0fbdb9891557..b5c087e1d2c727 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -2369,6 +2369,9 @@ class Film(TypedDict): return isinstance(tp, _TypedDictMeta) +_ASSERT_NEVER_REPR_MAX_LENGTH = 100 + + def assert_never(arg: Never, /) -> Never: """Statically assert that a line of code is unreachable. @@ -2389,7 +2392,10 @@ def int_or_str(arg: int | str) -> None: At runtime, this throws an exception when called. """ - raise AssertionError("Expected code to be unreachable") + value = repr(arg) + if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH: + value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...' + raise AssertionError(f"Expected code to be unreachable, but got: {value}") def no_type_check(arg): diff --git a/Misc/NEWS.d/next/Library/2022-04-19-19-50-10.gh-issue-90633.Youov0.rst b/Misc/NEWS.d/next/Library/2022-04-19-19-50-10.gh-issue-90633.Youov0.rst new file mode 100644 index 00000000000000..d86c2d3ff5de46 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-04-19-19-50-10.gh-issue-90633.Youov0.rst @@ -0,0 +1,2 @@ +Include the passed value in the exception thrown by +:func:`typing.assert_never`. Patch by Jelle Zijlstra.