aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKen Jin <28750310+Fidget-Spinner@users.noreply.github.com>2021-02-09 09:57:11 +0800
committerGitHub <noreply@github.com>2021-02-08 17:57:11 -0800
commit5f77dee0560e923935203dc4c49279ddb19f57ed (patch)
tree26164b724293a038e757fd205aec0371b3c55b3f
parentbpo-43162: [Enum] deprecate enum member.member access (GH-24486) (diff)
downloadcpython-5f77dee0560e923935203dc4c49279ddb19f57ed.tar.gz
cpython-5f77dee0560e923935203dc4c49279ddb19f57ed.tar.bz2
cpython-5f77dee0560e923935203dc4c49279ddb19f57ed.zip
Improve docs of PEP 604 Union (#24301)
-rw-r--r--Doc/library/functions.rst12
-rw-r--r--Doc/library/stdtypes.rst19
-rw-r--r--Doc/whatsnew/3.10.rst8
3 files changed, 20 insertions, 19 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index e36a1695c2a..370decc5108 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -870,19 +870,27 @@ are always available. They are listed here in alphabetical order.
class>`) subclass thereof. If *object* is not
an object of the given type, the function always returns ``False``.
If *classinfo* is a tuple of type objects (or recursively, other such
- tuples), return ``True`` if *object* is an instance of any of the types.
+ tuples) or a :ref:`types-union` of multiple types, return ``True`` if
+ *object* is an instance of any of the types.
If *classinfo* is not a type or tuple of types and such tuples,
a :exc:`TypeError` exception is raised.
+ .. versionchanged:: 3.10
+ *classinfo* can be a :ref:`types-union`.
+
.. function:: issubclass(class, classinfo)
Return ``True`` if *class* is a subclass (direct, indirect or :term:`virtual
<abstract base class>`) of *classinfo*. A
class is considered a subclass of itself. *classinfo* may be a tuple of class
- objects, in which case every entry in *classinfo* will be checked. In any other
+ objects or a :ref:`types-union`, in which case every entry in *classinfo*
+ will be checked. In any other
case, a :exc:`TypeError` exception is raised.
+ .. versionchanged:: 3.10
+ *classinfo* can be a :ref:`types-union`.
+
.. function:: iter(object[, sentinel])
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 2331849c02e..0929f3271e0 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -5022,8 +5022,10 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
str | None == typing.Optional[str]
.. describe:: isinstance(obj, union_object)
+.. describe:: issubclass(obj, union_object)
- Calls to :func:`isinstance` are also supported with a union object::
+ Calls to :func:`isinstance` and :func:`issubclass` are also supported with a
+ union object::
>>> isinstance("", int | str)
True
@@ -5036,21 +5038,6 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot contain a parameterized generic
-.. describe:: issubclass(obj, union_object)
-
- Calls to :func:`issubclass` are also supported with a union object::
-
- >>> issubclass(bool, int | str)
- True
-
- However, union objects containing :ref:`parameterized generics
- <types-genericalias>` cannot be used::
-
- >>> issubclass(bool, bool | list[str])
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- TypeError: issubclass() argument 2 cannot contain a parameterized generic
-
The user-exposed type for the union object can be accessed from
:data:`types.Union` and used for :func:`isinstance` checks. An object cannot be
instantiated from the type::
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index fa8b6aa54fe..96892ba3d37 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -193,7 +193,13 @@ Type hints can now be written in a more succinct manner::
return number ** 2
-See :pep:`604` for more details.
+This new syntax is also accepted as the second argument to :func:`isinstance`
+and :func:`issubclass`::
+
+ >>> isinstance(1, int | str)
+ True
+
+See :ref:`types-union` and :pep:`604` for more details.
(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)