Implement suggestions by gvanrossum and pablosgal

python · gvanrossum · Oct 5, 2020 · Oct 3, 2020 · Oct 3, 2020 · Oct 3, 2020
commit a2167db4eef6ee782437f5180afdc6cffdaee92f
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -4746,21 +4746,21 @@ single class dictionary lookup is negligible.
 .. _types-union:
 
 Union Type
-====================
+==========
 
 .. index::
    object: Union
    pair: union; type
 
 A union object holds the value of the ``|`` (bitwise or) operation on
-multiple :ref:`type objects<bltin-type-objects>`. This enables cleaner type
-hinting syntax compared to :data:`typing.Union`.
+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`.
 
 .. describe:: X | Y | ...
 
-   Defines a union object which holds types *X*, *Y*, and so forth. X | Y
-   means either X or Y. It is syntactically equivalent to
-   ``typing.Union[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::
 
       def square(number: int | float) -> int | float:
@@ -4774,19 +4774,19 @@ hinting syntax compared to :data:`typing.Union`.
 
        (int | str) | float == int | str | float
 
-   * Redundant arguments are skipped, e.g.::
+   * Redundant types are removed, e.g.::
 
        int | str | int == int | str
 
-   * When comparing unions, the argument order is ignored, e.g.::
+   * When comparing unions, the order is ignored, e.g.::
 
       int | str == str | int
 
-   * Compatible with :data:`typing.Union`::
+   * It is compatible with :data:`typing.Union`::
 
       int | str == typing.Union[int, str]
 
-   * Optional values are equivalent to :data:`typing.Optional`::
+   * Optional types can be spelled as a union with None::
 
       str | None == typing.Optional[str]
 
@@ -4797,7 +4797,7 @@ hinting syntax compared to :data:`typing.Union`.
       >>> isinstance("", int | str)
       True
 
-   Union objects containing parametrized generics cannot be used::
+   However, union objects containing parameterized generics cannot be used::
 
       >>> isinstance(1, int | list[int])
       TypeError: isinstance() argument 2 cannot contain a parameterized generic
@@ -4809,7 +4809,8 @@ hinting syntax compared to :data:`typing.Union`.
       >>> issubclass(bool, int | str)
       True
 
-   Union objects containing parametrized generics cannot be used::
+   However, union objects containing parameterized :ref:`generics<generics>`
+   cannot be used::
 
       >>> issubclass(bool, bool | list[str])
       TypeError: issubclass() argument 2 cannot contain a parameterized generic
@@ -4826,21 +4827,20 @@ cannot be instantiated from the type::
 
 .. note::
    The :meth:`__or__` method for type objects was added to support the syntax
-   X | Y. If a metaclass implements :meth:`__or__`, the Union may
+   ``X | Y``. If a metaclass implements :meth:`__or__`, the Union may
    override it::
 
-      class M(type):
-          def __or__(self, other):
-              return "Hello"
-
-      class C(metaclass=M):
-          pass
-
-      # 'Hello'
-      print(C | int)
-
-      # 'int | __main__.C'
-      print(int | C)
+      >>> class M(type):
+      ...     def __or__(self, other):
+      ...     return "Hello"
+      ...
+      >>> class C(metaclass=M):
+      ...     pass
+      ...
+      >>> C | int
+      'Hello'
+      >>> int | C
+      int | __main__.C
 
 .. seealso::
 

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
@@ -258,7 +258,7 @@ Standard names are defined for the following types:
 
 .. data:: Union
 
-   The type of :ref:`builtins.Union<types-union>`.
+   The type of :ref:`union type expressions<types-union>`.
 
    .. versionadded:: 3.10
 

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -545,8 +545,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
       Don't remove explicit subclasses from unions at runtime.
 
    .. versionchanged:: 3.10
-      Unions can now be written as X | Y. See :ref:`builtins.Union
-      <types-union>`.
+      Unions can now be written as ``X | Y``. See
+      :ref:`union type expressions<types-union>`.
 
 .. data:: Optional
 

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -82,9 +82,24 @@ New Features
 * :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used
   to require that all the iterables have an equal length.
 
-* :pep:`604`: Builtin Union type to allow writing X | Y in place of
-  ``typing.Union[X, Y]``.
-  (Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)
+PEP604: New Type Operators
+--------------------------
+There is a new syntax ``X | Y`` that allows for type union expressions. This
+provides a cleaner way of writing 'either type X or type Y' instead of
+using :data:`typing.Union`.
+
+For example::
+
+   def square(number: int | float) -> int | float:
+       return number ** 2
+
+Which is equivalent to, but more readable than using ``typing.Union``::
+
+   def square(number: Union[int, float]) -> Union[int, float]:
+       return number ** 2
+
+See :pep:`604` more details.
+(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)
 
 Other Language Changes
 ======================

diff --git a/Misc/NEWS.d/next/Documentation/2020-10-03-18-20-46.bpo-41428._ju1NE.rst b/Misc/NEWS.d/next/Documentation/2020-10-03-18-20-46.bpo-41428._ju1NE.rst
@@ -1 +1 @@
-Add documentation for :pep:`604` (Allow writing union types as X | Y).
+Add documentation for :pep:`604` (Allow writing union types as ``X | Y``).
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		Add documentation for :pep:`604` (Allow writing union types as X \| Y).
		Add documentation for :pep:`604` (Allow writing union types as ``X \| Y``).