From d21cb2d5ee56b8975d92e2ee094aba81f0801be5 Mon Sep 17 00:00:00 2001 From: kj <28750310+Fidget-Spinner@users.noreply.github.com> Date: Sat, 31 Oct 2020 23:08:17 +0800 Subject: 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. --- Doc/library/stdtypes.rst | 37 ++++++++++++++----------------------- Doc/whatsnew/3.10.rst | 2 +- 2 files changed, 15 insertions(+), 24 deletions(-) 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 @@ Union Type pair: union; type A union object holds the value of the ``|`` (bitwise or) operation on -multiple :ref:`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 `. These types are intended +primarily for :term:`type annotations `. 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 - `_ cannot be used:: + However, union objects containing :ref:`parameterized generics + ` 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 - `_ cannot be used:: + However, union objects containing :ref:`parameterized generics + ` cannot be used:: >>> issubclass(bool, bool | list[str]) Traceback (most recent call last): File "", line 1, in 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 @@ 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 -- cgit v0.12