PEP12 styling, fix grammar/wording, give full errors

gvanrossum · Oct 5, 2020 · Oct 3, 2020 · Oct 3, 2020 · Oct 3, 2020 · Oct 4, 2020
commit d225dceb7ea403dda530bd03aa873fb0c6c98de8
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -4753,22 +4753,22 @@ 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 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, ...]``.
+   means either X or Y.  It is equivalent to ``typing.Union[X, Y, ...]``.
    Example::
 
       def square(number: int | float) -> int | float:
           return number ** 2
 
 .. describe:: union_object == other
 
-   Union objects can be tested for equality with other union objects. Details:
+   Union objects can be tested for equality with other union objects.  Details:
 
    * Unions of unions are flattened, e.g.::
 
@@ -4786,7 +4786,7 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
 
       int | str == typing.Union[int, str]
 
-   * Optional types can be spelled as a union with None::
+   * Optional types can be spelled as a union with ``None``::
 
       str | None == typing.Optional[str]
 
@@ -4801,6 +4801,8 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
    cannot be used::
 
       >>> isinstance(1, int | list[int])
+      Traceback (most recent call last):
+        File "<stdin>", line 1, in <module>
       TypeError: isinstance() argument 2 cannot contain a parameterized generic
 
 .. describe:: issubclass(obj, union_object)
@@ -4814,21 +4816,24 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
    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 for the Union object is :data:`types.Union`. An object
-cannot be instantiated from the type::
+The type for the Union object is :data:`types.Union`.  An object cannot be
+instantiated from the type::
 
    >>> import types
    >>> isinstance(int | str, types.Union)
    True
    >>> types.Union()
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
    TypeError: cannot create 'types.Union' instances
 
 .. 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):
@@ -4845,7 +4850,7 @@ cannot be instantiated from the type::
 
 .. seealso::
 
-   :pep:`604` -- PEP proposing the Union object and type.
+   :pep:`604` -- PEP proposing the ``X | Y`` syntax and the Union type.
 
 .. versionadded:: 3.10
 

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -82,23 +82,27 @@ 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.
 
-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
+PEP604: New Type Operator
+-------------------------
+A new type union operator was introduced which enables the syntax ``X | Y``.
+This provides a cleaner way of expressing 'either type X or type Y' instead of
 using :data:`typing.Union`.
 
-For example::
+In previous versions of Python, to apply a type hint for functions accepting
+arguments of multiple types, :data:`typing.Union` was used::
 
-   def square(number: int | float) -> int | float:
+   def square(number: Union[int, float]) -> Union[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]:
+Now, type hints can be written in a more succinct manner::
+
+   def square(number: int | float) -> int | float:
        return number ** 2
 
-See :pep:`604` more details.
+
+See :pep:`604` for more details.
+
 (Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)
 
 Other Language Changes