iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 647: Incorporated feedback from Guido about terminology and type relationship between bool and TypeGuard (#1765)

This commit is contained in:
Eric Traut 2021-01-15 21:55:07 -07:00 committed by GitHub
parent a59cc3121c
commit 28fc05c35a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
pep-0647.rst
View File

@ -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