Skip to content

Commit d21cb2d

Browse files
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.
1 parent 7d21027 commit d21cb2d

File tree

2 files changed

+15
-24
lines changed

2 files changed

+15
-24
lines changed

Doc/library/stdtypes.rst

Lines changed: 14 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4968,15 +4968,16 @@ Union Type
49684968
pair: union; type
49694969

49704970
A union object holds the value of the ``|`` (bitwise or) operation on
4971-
multiple :ref:`type objects<bltin-type-objects>`. These types are intended
4972-
primarily for type annotations. The union type expression enables cleaner
4973-
type hinting syntax compared to :data:`typing.Union`.
4971+
multiple :ref:`type objects <bltin-type-objects>`. These types are intended
4972+
primarily for :term:`type annotations <annotation>`. The union type expression
4973+
enables cleaner type hinting syntax compared to :data:`typing.Union`.
49744974

49754975
.. describe:: X | Y | ...
49764976

49774977
Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y``
49784978
means either X or Y. It is equivalent to ``typing.Union[X, Y]``.
4979-
Example::
4979+
For example, the following function expects an argument of type
4980+
:class:`int` or :class:`float`::
49804981

49814982
def square(number: int | float) -> int | float:
49824983
return number ** 2
@@ -4985,15 +4986,15 @@ type hinting syntax compared to :data:`typing.Union`.
49854986

49864987
Union objects can be tested for equality with other union objects. Details:
49874988

4988-
* Unions of unions are flattened, e.g.::
4989+
* Unions of unions are flattened::
49894990

49904991
(int | str) | float == int | str | float
49914992

4992-
* Redundant types are removed, e.g.::
4993+
* Redundant types are removed::
49934994

49944995
int | str | int == int | str
49954996

4996-
* When comparing unions, the order is ignored, e.g.::
4997+
* When comparing unions, the order is ignored::
49974998

49984999
int | str == str | int
49995000

@@ -5012,14 +5013,8 @@ type hinting syntax compared to :data:`typing.Union`.
50125013
>>> isinstance("", int | str)
50135014
True
50145015

5015-
..
5016-
At the time of writing this, there is no documentation for parameterized
5017-
generics or PEP 585. Thus the link currently points to PEP 585 itself.
5018-
Please change the link for parameterized generics to reference the correct
5019-
documentation once documentation for PEP 585 becomes available.
5020-
5021-
However, union objects containing `parameterized generics
5022-
<https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
5016+
However, union objects containing :ref:`parameterized generics
5017+
<types-genericalias>` cannot be used::
50235018

50245019
>>> isinstance(1, int | list[int])
50255020
Traceback (most recent call last):
@@ -5033,20 +5028,16 @@ type hinting syntax compared to :data:`typing.Union`.
50335028
>>> issubclass(bool, int | str)
50345029
True
50355030

5036-
..
5037-
Once again, please change the link below for parameterized generics to
5038-
reference the correct documentation once documentation for PEP 585
5039-
becomes available.
5040-
5041-
However, union objects containing `parameterized generics
5042-
<https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
5031+
However, union objects containing :ref:`parameterized generics
5032+
<types-genericalias>` cannot be used::
50435033

50445034
>>> issubclass(bool, bool | list[str])
50455035
Traceback (most recent call last):
50465036
File "<stdin>", line 1, in <module>
50475037
TypeError: issubclass() argument 2 cannot contain a parameterized generic
50485038

5049-
The type of a union object is :data:`types.Union`. An object cannot be
5039+
The user-exposed type for the union object can be accessed from
5040+
:data:`types.Union` and used for :func:`isinstance` checks. An object cannot be
50505041
instantiated from the type::
50515042

50525043
>>> import types

Doc/whatsnew/3.10.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ arguments of multiple types, :data:`typing.Union` was used::
134134
return number ** 2
135135

136136

137-
Now, type hints can be written in a more succinct manner::
137+
Type hints can now be written in a more succinct manner::
138138

139139
def square(number: int | float) -> int | float:
140140
return number ** 2

0 commit comments

Comments
 (0)