Skip to content

bpo-43766: Fix TypeGuard docs #25660

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gvanrossum merged 2 commits into from
Apr 27, 2021
Merged

bpo-43766: Fix TypeGuard docs #25660

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d50695
Reduce TypeGuard docs' verbosity
Fidget-Spinner Apr 27, 2021
a82cd43
add to ignored.csv
Fidget-Spinner Apr 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 3 additions & 8 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -974,10 +974,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn

def func1(val: List[object]):
if is_str_list(val):
# Type of ``val`` is narrowed to List[str]
# Type of ``val`` is narrowed to ``List[str]``.
print(" ".join(val))
else:
# Type of ``val`` remains as List[object]
# Type of ``val`` remains as ``List[object]``.
print("Not a list of strings!")

If ``is_str_list`` is a class or instance method, then the type in
Expand All @@ -994,12 +994,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
wider form. 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
writing type-safe type guards is left to the user. Even if
the type guard function passes type checks, it may still fail at runtime.
The type guard function may perform erroneous checks and return wrong
booleans. Consequently, the type it promises in ``TypeGuard[TypeB]`` may
not hold.
The responsibility of writing type-safe type guards is left to the user.

``TypeGuard`` also works with type variables. For more information, see
:pep:`647` (User-Defined Type Guards).
Expand Down
4 changes: 4 additions & 0 deletions Doc/tools/susp-ignored.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,3 +370,7 @@ library/importlib.metadata,,:main,"EntryPoint(name='wheel', value='wheel.cli:mai
library/importlib.metadata,,`,loading the metadata for packages for the indicated ``context``.
library/re,,`,"`"
using/configure,84,:db2,=db1:db2:...
library/typing,1004,`,# Type of ``val`` is narrowed to ``str``
library/typing,1004,`,"# Else, type of ``val`` is narrowed to ``float``."
library/typing,1004,`,# Type of ``val`` is narrowed to ``List[str]``.
library/typing,1004,`,# Type of ``val`` remains as ``List[object]``.