bpo-42198: Improve consistency of Union docs (GH-23029)
No backport is required since union is only in 3.10.
This addresses "3. Consistency nitpicks for Union's docs" in the bpo.
Please skip news. Thank you.
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 09477e6..8a9cadd 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -4968,15 +4968,16 @@
pair: union; type
A union object holds the value of the ``|`` (bitwise or) operation on
-multiple :ref:`type objects<bltin-type-objects>`. These types are intended
-primarily for type annotations. The union type expression enables cleaner
-type hinting syntax compared to :data:`typing.Union`.
+multiple :ref:`type objects <bltin-type-objects>`. These types are intended
+primarily for :term:`type annotations <annotation>`. The union type expression
+enables cleaner type hinting syntax compared to :data:`typing.Union`.
.. describe:: X | Y | ...
Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y``
means either X or Y. It is equivalent to ``typing.Union[X, Y]``.
- Example::
+ For example, the following function expects an argument of type
+ :class:`int` or :class:`float`::
def square(number: int | float) -> int | float:
return number ** 2
@@ -4985,15 +4986,15 @@
Union objects can be tested for equality with other union objects. Details:
- * Unions of unions are flattened, e.g.::
+ * Unions of unions are flattened::
(int | str) | float == int | str | float
- * Redundant types are removed, e.g.::
+ * Redundant types are removed::
int | str | int == int | str
- * When comparing unions, the order is ignored, e.g.::
+ * When comparing unions, the order is ignored::
int | str == str | int
@@ -5012,14 +5013,8 @@
>>> isinstance("", int | str)
True
- ..
- At the time of writing this, there is no documentation for parameterized
- generics or PEP 585. Thus the link currently points to PEP 585 itself.
- Please change the link for parameterized generics to reference the correct
- documentation once documentation for PEP 585 becomes available.
-
- However, union objects containing `parameterized generics
- <https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
+ However, union objects containing :ref:`parameterized generics
+ <types-genericalias>` cannot be used::
>>> isinstance(1, int | list[int])
Traceback (most recent call last):
@@ -5033,20 +5028,16 @@
>>> issubclass(bool, int | str)
True
- ..
- Once again, please change the link below for parameterized generics to
- reference the correct documentation once documentation for PEP 585
- becomes available.
-
- However, union objects containing `parameterized generics
- <https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
+ 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 type of a union object is :data:`types.Union`. An object cannot be
+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::
>>> import types
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index f4d7290..60dee0c 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -134,7 +134,7 @@
return number ** 2
-Now, type hints can be written in a more succinct manner::
+Type hints can now be written in a more succinct manner::
def square(number: int | float) -> int | float:
return number ** 2