https://github.com/python/cpython/commit/b5e12aa9ff581dd677d9b5f7adeb672cfb52068e
commit: b5e12aa9ff581dd677d9b5f7adeb672cfb52068e
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
committer: JelleZijlstra <jelle.zijlstra@gmail.com>
date: 2024-04-04T11:04:16Z
summary:
[3.12] gh-117521: Improve typing.TypeGuard docstring (GH-117522) (#117538)
(cherry picked from commit b32789ccb91bbe43e88193f68b1364a8da6d9866)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
files:
M Lib/typing.py
diff --git a/Lib/typing.py b/Lib/typing.py
index c9962b9c9bccad..b58c2d3064098b 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -846,22 +846,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
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-leave@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: list-python-checkins@lists.gossamer-threads.com
commit: b5e12aa9ff581dd677d9b5f7adeb672cfb52068e
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
committer: JelleZijlstra <jelle.zijlstra@gmail.com>
date: 2024-04-04T11:04:16Z
summary:
[3.12] gh-117521: Improve typing.TypeGuard docstring (GH-117522) (#117538)
(cherry picked from commit b32789ccb91bbe43e88193f68b1364a8da6d9866)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
files:
M Lib/typing.py
diff --git a/Lib/typing.py b/Lib/typing.py
index c9962b9c9bccad..b58c2d3064098b 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -846,22 +846,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
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-leave@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: list-python-checkins@lists.gossamer-threads.com