diff options
author | Jelle Zijlstra <jelle.zijlstra@gmail.com> | 2024-04-04 10:39:16 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-04-04 10:39:16 (GMT) |
commit | b32789ccb91bbe43e88193f68b1364a8da6d9866 (patch) | |
tree | 98b0cfb1d7ee15da21c2c68b8f8e00014dd4d475 | |
parent | 3f5bcc86d0764b691087e8412941e947554c93fd (diff) | |
download | cpython-b32789ccb91bbe43e88193f68b1364a8da6d9866.zip cpython-b32789ccb91bbe43e88193f68b1364a8da6d9866.tar.gz cpython-b32789ccb91bbe43e88193f68b1364a8da6d9866.tar.bz2 |
gh-117521: Improve typing.TypeGuard docstring (#117522)
-rw-r--r-- | Lib/typing.py | 25 |
1 files changed, 14 insertions, 11 deletions
diff --git a/Lib/typing.py b/Lib/typing.py index ef532f6..d8e4ee3 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -841,22 +841,25 @@ def TypeGuard(self, parameters): 2. If the return value is ``True``, the type of its argument is the type inside ``TypeGuard``. - For example:: + 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 is_str(val: Union[str, float]): - # "isinstance" type guard - if isinstance(val, str): - # Type of ``val`` is narrowed to ``str`` - ... - else: - # Else, type of ``val`` is narrowed to ``float``. - ... + 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!") 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 type-unsafe results. 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 + 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. ``TypeGuard`` also works with type variables. For more information, see |