[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 11ee912327ef51100d2a6b990249f25b6b1b435d)

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

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index b00eb93f32ece4acd767b5785d96c84ed88d730f..c8e772996172a67a4ed87d206f8af8d1645ebcb6 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -2581,10 +2581,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"
@@ -2592,22 +2592,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 eb61012e8c9c879976a7713657d757f42c09f678..49d64f80dc178808f8f1761d81c47b66c91ac364 100644 (file)
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -3280,7 +3280,7 @@ sys.modules[re.__name__] = re
 
 
 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