[3.11] gh-113255: Clarify docs for `typing.reveal_type` (#113286) (#113326)

(cherry-picked from commit 11ee912327)

Co-authored-by: Kir <note351@hotmail.com>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 0eda01a323e4908f2ca7f6ae4493eb5dace92764..396115af83d0336f993e92fef3fc691b868f06d5 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -2323,10 +2323,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"
@@ -2334,22 +2334,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::
+   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)  # Revealed type is "builtins.int"
+      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`` allows your code to run without runtime errors and
+   ``typing``, however, 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::
-
-      x = reveal_type(1)  # prints "Runtime type is int"
-      print(x)  # prints "1"
-
    .. versionadded:: 3.11
 
 .. decorator:: dataclass_transform(*, eq_default=True, order_default=False, \

diff --git a/Lib/typing.py b/Lib/typing.py
index 85166dfd9463141d5fe9fb81df5966d1c6774e50..52898189504c78de3f05cdd5148b328c5a0df250 100644 (file)
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -3419,7 +3419,7 @@ sys.modules[re.__name__] = re
 
 
 def reveal_type(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::
@@ -3431,7 +3431,7 @@ def reveal_type(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