https://github.com/python/cpython/commit/d21cb2d5ee56b8975d92e2ee094aba81f08... commit: d21cb2d5ee56b8975d92e2ee094aba81f0801be5 branch: master author: kj <28750310+Fidget-Spinner@users.noreply.github.com> committer: miss-islington <31488909+miss-islington@users.noreply.github.com> date: 2020-10-31T08:08:17-07:00 summary: 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. files: M Doc/library/stdtypes.rst M Doc/whatsnew/3.10.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 09477e63786c5..8a9cadde7d5dc 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -4968,15 +4968,16 @@ Union Type 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 @@ type hinting syntax compared to :data:`typing.Union`. 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 @@ type hinting syntax compared to :data:`typing.Union`. >>> 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 @@ type hinting syntax compared to :data:`typing.Union`. >>> 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 f4d72908486dd..60dee0c6bd165 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -134,7 +134,7 @@ arguments of multiple types, :data:`typing.Union` was used:: 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