[3.12] gh-117521: Improve typing.TypeGuard docstring (GH-117522) (#117538)

(cherry picked from commit b32789ccb91bbe43e88193f68b1364a8da6d9866)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

diff --git a/Lib/typing.py b/Lib/typing.py
index c9962b9c9bccadbffa923208868c82c873cf815b..b58c2d3064098bf06e04ee104f33807dba32e565 100644 (file)
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -846,22 +846,25 @@ def TypeGuard(self, parameters):
     2. If the return value is ``True``, the type of its argument
        is the type inside ``TypeGuard``.
 
-       For example::
+    For example::
+
+         def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
+             '''Determines whether all objects in the list are strings'''
+             return all(isinstance(x, str) for x in val)
 
-           def is_str(val: Union[str, float]):
-               # "isinstance" type guard
-               if isinstance(val, str):
-                   # Type of ``val`` is narrowed to ``str``
-                   ...
-               else:
-                   # Else, type of ``val`` is narrowed to ``float``.
-                   ...
+         def func1(val: list[object]):
+             if is_str_list(val):
+                 # Type of ``val`` is narrowed to ``list[str]``.
+                 print(" ".join(val))
+             else:
+                 # Type of ``val`` remains as ``list[object]``.
+                 print("Not a list of strings!")
 
     Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower
     form of ``TypeA`` (it can even be a wider form) and this may lead to
     type-unsafe results.  The main reason is to allow for things like
-    narrowing ``List[object]`` to ``List[str]`` even though the latter is not
-    a subtype of the former, since ``List`` is invariant.  The responsibility of
+    narrowing ``list[object]`` to ``list[str]`` even though the latter is not
+    a subtype of the former, since ``list`` is invariant.  The responsibility of
     writing type-safe type guards is left to the user.
 
     ``TypeGuard`` also works with type variables.  For more information, see