From 11ee912327ef51100d2a6b990249f25b6b1b435d Mon Sep 17 00:00:00 2001 From: Kir Date: Thu, 21 Dec 2023 02:21:23 +0900 Subject: [PATCH] gh-113255: Clarify docs for `typing.reveal_type` (#113286) Co-authored-by: AlexWaygood --- Doc/library/typing.rst | 27 +++++++++++++-------------- Lib/typing.py | 4 ++-- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index ba2845eb17d..63bd62d1f66 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2604,10 +2604,10 @@ Functions and decorators .. function:: reveal_type(obj, /) - Reveal the inferred static type of an expression. + Ask a static type checker to reveal the inferred type of an expression. When a static type checker encounters a call to this function, - it emits a diagnostic with the type of the argument. For example:: + it emits a diagnostic with the inferred type of the argument. For example:: x: int = 1 reveal_type(x) # Revealed type is "builtins.int" @@ -2615,22 +2615,21 @@ Functions and decorators This can be useful when you want to debug how your type checker handles a particular piece of code. - The function returns its argument unchanged, which allows using - it within an expression:: - - x = reveal_type(1) # Revealed type is "builtins.int" - - Most type checkers support ``reveal_type()`` anywhere, even if the - name is not imported from ``typing``. Importing the name from - ``typing`` allows your code to run without runtime errors and - communicates intent more clearly. - - At runtime, this function prints the runtime type of its argument to stderr - and returns it unchanged:: + At runtime, this function prints the runtime type of its argument to + :data:`sys.stderr` and returns the argument unchanged (allowing the call to + be used within an expression):: x = reveal_type(1) # prints "Runtime type is int" print(x) # prints "1" + Note that the runtime type may be different from (more or less specific + than) the type statically inferred by a type checker. + + Most type checkers support ``reveal_type()`` anywhere, even if the + name is not imported from ``typing``. Importing the name from + ``typing``, however, allows your code to run without runtime errors and + communicates intent more clearly. + .. versionadded:: 3.11 .. decorator:: dataclass_transform(*, eq_default=True, order_default=False, \ diff --git a/Lib/typing.py b/Lib/typing.py index 61b88a560e9..d7d793539b3 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -3301,7 +3301,7 @@ class TextIO(IO[str]): def reveal_type[T](obj: T, /) -> T: - """Reveal the inferred type of a variable. + """Ask a static type checker to reveal the inferred type of an expression. When a static type checker encounters a call to ``reveal_type()``, it will emit the inferred type of the argument:: @@ -3313,7 +3313,7 @@ def reveal_type[T](obj: T, /) -> T: will produce output similar to 'Revealed type is "builtins.int"'. At runtime, the function prints the runtime type of the - argument and returns it unchanged. + argument and returns the argument unchanged. """ print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr) return obj