gh-113255: Clarify docs for `typing.reveal_type` (#113286)

Co-authored-by: AlexWaygood <alex.waygood@gmail.com>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index ba2845eb17ddccc8bf1cba3fb70575517e7dc7bc..63bd62d1f6679b74df0e1682cbe74e44478b66bf 100644 (file)
--- 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::
+   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 61b88a560e9dc56383ab546717e2d8ceb791fe81..d7d793539b35b191c1aafbf31d9a9e1e38fc624d 100644 (file)
--- 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