gvanrossum · Apr 27, 2021 · Apr 8, 2021 · Apr 8, 2021 · Apr 8, 2021 · Apr 11, 2021
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -933,6 +933,55 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 
    .. versionadded:: 3.9
 
+
+.. data:: TypeGuard
+
+   Special typing form used to annotate the return type of a user-defined
+   type guard function.  ``TypeGuard`` only accepts a single type argument.
+
+   ``TypeGuard`` aims to benefit *type narrowing* - a technique used by static
+   type checkers to determine a more precise type of an expression within a
+   program's code flow.  Usually type narrowing is done by analyzing
+   conditional code flow and applying the narrowing to a block of code.  The
+   conditional expression here is sometimes referred to as a "type guard".
+
+   Sometimes, a type guard can be a complex checking function.
+   These type guard functions require ``TypeGuard`` to narrow their input types
+   as the static type checker usually does not have enough information to
+   statically infer them.
+
+   A ``TypeGuard`` tells the static type checker that for a given function:
+      1. The return value is a boolean.
+      2. If the return value was "truthy", the type of the input to the
+         function is specified by the type inside ``TypeGuard``.
+
+      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 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!")
+
+   In short, the form ``def foo(arg: TypeA) -> TypeGuard[TypeB]: ...``,
+   Means that if ``foo(arg)`` returned true, then ``arg`` narrows from
+   ``TypeA`` to ``TypeB``.
+
+   Return statements within a type guard function should return ``bool``
+   values.
+
+   ``TypeGuard`` also works with type variables.  For more information, see
+   :pep:`647` (User-Defined Type Guards).
+
+   .. versionadded:: 3.10
+
+
 Building generic types
 """"""""""""""""""""""
 

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -576,6 +576,15 @@ See :pep:`613` for more details.
 
 (Contributed by Mikhail Golubev in :issue:`41923`.)
 
+PEP 647: User-Defined Type Guards
+---------------------------------
+
+:data:`TypeGuard` has been added to the :mod:`typing` module to annotate
+type guard functions and improve information provided to static type checkers
+during type narrowing.  For more information, please see :data:`TypeGuard`\ 's
+documentation, and :pep:`647`.
+
+(Contributed by Ken Jin in :issue:`43766`. PEP written by Eric Traut.)
 
 Other Language Changes
 ======================

diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py
@@ -26,6 +26,7 @@
 from typing import Annotated, ForwardRef
 from typing import TypeAlias
 from typing import ParamSpec, Concatenate
+from typing import TypeGuard
 import abc
 import typing
 import weakref
@@ -4346,6 +4347,54 @@ def test_valid_uses(self):
         self.assertEqual(C4.__parameters__, (T, P))
 
 
+class TypeGuardTests(BaseTestCase):
+    def test_basics(self):
+        TypeGuard[int]  # OK
+
+        def foo(arg) -> TypeGuard[int]: ...
+        self.assertEqual(gth(foo), {'return': TypeGuard[int]})
+
+        with self.assertRaises(TypeError):
+            TypeGuard[1]
+        with self.assertRaises(TypeError):
+            TypeGuard[int, str]
+
+    def test_repr(self):
+        self.assertEqual(repr(TypeGuard), 'typing.TypeGuard')
+        cv = TypeGuard[int]
+        self.assertEqual(repr(cv), 'typing.TypeGuard[int]')
+        cv = TypeGuard[Employee]
+        self.assertEqual(repr(cv), 'typing.TypeGuard[%s.Employee]' % __name__)
+        cv = TypeGuard[tuple[int]]
+        self.assertEqual(repr(cv), 'typing.TypeGuard[tuple[int]]')
+
+    def test_cannot_subclass(self):
+        with self.assertRaises(TypeError):
+            class C(type(TypeGuard)):
+                pass
+        with self.assertRaises(TypeError):
+            class C(type(TypeGuard[int])):
+                pass
+
+    def test_cannot_init(self):
+        with self.assertRaises(TypeError):
+            TypeGuard()
+        with self.assertRaises(TypeError):
+            type(TypeGuard)()
+        with self.assertRaises(TypeError):
+            type(TypeGuard[Optional[int]])()
+
+    def test_no_isinstance(self):
+        with self.assertRaises(TypeError):
+            isinstance(1, TypeGuard[int])
+        with self.assertRaises(TypeError):
+            issubclass(int, TypeGuard)
+
+    def test_final_unmodified(self):
+        def func(x): ...
+        self.assertIs(func, final(func))
+
+
 class AllTests(BaseTestCase):
     """Tests for __all__."""
 

diff --git a/Lib/typing.py b/Lib/typing.py
@@ -118,6 +118,7 @@
     'Text',
     'TYPE_CHECKING',
     'TypeAlias',
+    'TypeGuard',
 ]
 
 # The pseudo-submodules 're' and 'io' are part of the public
@@ -566,6 +567,48 @@ def Concatenate(self, parameters):
     return _ConcatenateGenericAlias(self, parameters)
 
 
+@_SpecialForm
+def TypeGuard(self, parameters):
+    """Special typing form used to annotate the return type of a user-defined
+    type guard function.  ``TypeGuard`` only accepts a single type argument.
+
+    ``TypeGuard`` aims to benefit *type narrowing* - a technique used by static
+    type checkers to determine a more precise type of an expression within a
+    program's code flow.
+
+    A ``TypeGuard`` tells the static type checker that for a given function:
+       1. The return value is a boolean.
+       2. If the return value was "truthy", the type of the input to the
+          function is specified by the type inside ``TypeGuard``.
+
+       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 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!")
+
+    In short, the form ``def foo(arg: TypeA) -> TypeGuard[TypeB]: ...``,
+    Means that if ``foo(arg)`` returned true, then ``arg`` narrows from
+    ``TypeA`` to ``TypeB``.
+
+    Return statements within a type guard function should return ``bool``
+    values.
+
+    ``TypeGuard`` also works with type variables.  For more information, see
+    :pep:`647` (User-Defined Type Guards).
+    """
+    item = _type_check(parameters, f'{self} accepts only single type.')
+    return _GenericAlias(self, (item,))
+
+
 class ForwardRef(_Final, _root=True):
     """Internal wrapper to hold a forward reference."""
 

diff --git a/Misc/NEWS.d/next/Library/2021-04-09-00-16-22.bpo-43766.nYNQP0.rst b/Misc/NEWS.d/next/Library/2021-04-09-00-16-22.bpo-43766.nYNQP0.rst
@@ -0,0 +1,2 @@
+Implement :pep:`647` in the :mod:`typing` module by adding
+:data:`TypeGuard`.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Implement :pep:`647` in the :mod:`typing` module by adding
		:data:`TypeGuard`.