diff --git a/pep-0647.rst b/pep-0647.rst index a986b791b..dff217f87 100644 --- a/pep-0647.rst +++ b/pep-0647.rst @@ -134,14 +134,18 @@ TypeGuard Type -------------- This PEP introduces the symbol ``TypeGuard`` exported from the ``typing`` -module. ``TypeGuard`` is a type alias for the built-in `bool` type, but it -allows for a single type argument. It is meant to be used to annotate the -return type of a function or method. When it is used in other contexts, it -is treated as a ``bool``. +module. ``TypeGuard`` is a special form that accepts a single type argument. +It is used to annotate the return type of a user-defined type guard function. +Return statements within a type guard function should return bool values, +and type checkers should verify that all return paths return a bool. + +In all other respects, TypeGuard is a distinct type from bool. It is not a +subtype of bool. Therefore, ``Callable[..., TypeGuard[int]]`` is not assignable +to ``Callable[..., bool]``. When ``TypeGuard`` is used to annotate the return type of a function or method that accepts at least one parameter, that function or method is -assumed by type checkers to be a user-defined type guard. The type argument +treated by type checkers as a user-defined type guard. The type argument provided for ``TypeGuard`` indicates the type that has been validated by the function. @@ -162,12 +166,13 @@ User-defined type guards can be generic functions, as shown in this example: Type checkers should assume that type narrowing should be applied to the -expression that is passed as the first explicit argument to a user-defined +expression that is passed as the first positional argument to a user-defined type guard. If the type guard function accepts more than one argument, no type narrowing is applied to those additional argument expressions. If a type guard function is implemented as an instance method or class method, -the first explicit argument maps to the second parameter (after "self" or "cls"). +the first positional argument maps to the second parameter (after "self" or +"cls"). Here are some examples of user-defined type guard functions that accept more than one argument: @@ -193,8 +198,8 @@ allows for cases like the example above where ``List[str]`` is not assignable to ``List[object]``. When a conditional statement includes a call to a user-defined type guard -function, the expression passed as the first argument to the type guard -function should be assumed by a static type checker to take on the type +function, the expression passed as the first positional argument to the type +guard function should be assumed by a static type checker to take on the type specified in the TypeGuard return type, unless and until it is further narrowed within the conditional code block. @@ -331,7 +336,7 @@ in PEP 637. Narrowing of Implicit "self" and "cls" Parameters ------------------------------------------------- -The proposal states that the first explicit argument is assumed to be the +The proposal states that the first positional argument is assumed to be the value that is tested for narrowing. If the type guard function is implemented as an instance or class method, an implicit ``self`` or ``cls`` argument will also be passed to the function. A concern was raised that there may be