[3.12] gh-113255: Clarify docs for typing.reveal_type (GH-113286) (#113323)

gh-113255: Clarify docs for `typing.reveal_type` (GH-113286)
(cherry picked from commit 11ee912)

Co-authored-by: Kir <[email protected]>
Co-authored-by: AlexWaygood <[email protected]>

Author: 3 people

Doc/library/typing.rst

@@ -2581,33 +2581,32 @@ 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"
 
    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, \

Lib/typing.py

@@ -3280,7 +3280,7 @@ class re(metaclass=_DeprecatedType):
 
 
 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::
@@ -3292,7 +3292,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