[Python-checkins] Improve docs of PEP 604 Union (#24301)

[gvanrossum]

https://github.com/python/cpython/commit/5f77dee0560e923935203dc4c49279ddb19f57ed
commit: 5f77dee0560e923935203dc4c49279ddb19f57ed
branch: master
author: Ken Jin <28750310+Fidget-Spinner at users.noreply.github.com>
committer: gvanrossum <gvanrossum at gmail.com>
date: 2021-02-08T17:57:11-08:00
summary:

Improve docs of PEP 604 Union (#24301)

files:
M Doc/library/functions.rst
M Doc/library/stdtypes.rst
M Doc/whatsnew/3.10.rst

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index e36a1695c2ad5..370decc51087f 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 2331849c02e98..0929f3271e051 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 fa8b6aa54fe90..96892ba3d37e1 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`.)