Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 23:21:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-117521: Improve typing.TypeGuard docstring (#117522)

Browse source
This commit is contained in:
Jelle Zijlstra 2024-04-04 06:39:16 -04:00 • committed by GitHub
parent 3f5bcc86d0
commit b32789ccb9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 14 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

25
Lib/typing.py
View file

@ -841,22 +841,25 @@ def TypeGuard(self, parameters):
2. If the return value is ``True``, the type of its argument 2. If the return value is ``True``, the type of its argument
is the type inside ``TypeGuard``. is the type inside ``TypeGuard``.
For example:: For example::
def is_str(val: Union[str, float]): def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
# "isinstance" type guard '''Determines whether all objects in the list are strings'''
if isinstance(val, str): return all(isinstance(x, str) for x in val)
# Type of ``val`` is narrowed to ``str``
... def func1(val: list[object]):
else: if is_str_list(val):
# Else, type of ``val`` is narrowed to ``float``. # 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 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 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 type-unsafe results. The main reason is to allow for things like
narrowing ``List[object]`` to ``List[str]`` even though the latter is not narrowing ``list[object]`` to ``list[str]`` even though the latter is not
a subtype of the former, since ``List`` is invariant. The responsibility of a subtype of the former, since ``list`` is invariant. The responsibility of
writing type-safe type guards is left to the user. writing type-safe type guards is left to the user.
``TypeGuard`` also works with type variables. For more information, see ``TypeGuard`` also works with type variables. For more information, see