bpo-44957: Promote PEP 604 syntax in typing docs (GH-27833)

* Use "X | Y" instead of "Union" where it makes sense.
* Mention that "X | Y" is equivalent to "Union[X, Y]" in Union section.
* Remove "Optional[X]" as shorthand for "Union[X, None]" as the new
  shorthand is now "X | None".
* Mention that "Optional[X]" can be written as "X | None" in section
  about "Optional".

Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>

Doc/library/typing.rst

@@ -321,11 +321,11 @@ not generic but implicitly inherits from ``Iterable[Any]``::
 User defined generic type aliases are also supported. Examples::
 
    from collections.abc import Iterable
-   from typing import TypeVar, Union
+   from typing import TypeVar
    S = TypeVar('S')
-   Response = Union[Iterable[S], int]
+   Response = Iterable[S] | int
 
-   # Return type here is same as Union[Iterable[str], int]
+   # Return type here is same as Iterable[str] | int
    def response(query: str) -> Response[str]:
        ...
 
@@ -588,9 +588,9 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 
 .. data:: Union
 
-   Union type; ``Union[X, Y]`` means either X or Y.
+   Union type; ``Union[X, Y]`` is equivalent to ``X | Y`` and means either X or Y.
 
-   To define a union, use e.g. ``Union[int, str]``.  Details:
+   To define a union, use e.g. ``Union[int, str]`` or the shorthand ``int | str``.  Details:
 
    * The arguments must be types and there must be at least one.
 
@@ -604,18 +604,16 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 
    * Redundant arguments are skipped, e.g.::
 
-       Union[int, str, int] == Union[int, str]
+       Union[int, str, int] == Union[int, str] == int | str
 
    * When comparing unions, the argument order is ignored, e.g.::
 
        Union[int, str] == Union[str, int]
 
-   * You cannot subclass or instantiate a union.
+   * You cannot subclass or instantiate a ``Union``.
 
    * You cannot write ``Union[X][Y]``.
 
-   * You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``.
-
    .. versionchanged:: 3.7
       Don't remove explicit subclasses from unions at runtime.
 
@@ -627,7 +625,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 
    Optional type.
 
-   ``Optional[X]`` is equivalent to ``Union[X, None]``.
+   ``Optional[X]`` is equivalent to ``X | None`` (or ``Union[X, None]``).
 
    Note that this is not the same concept as an optional argument,
    which is one that has a default.  An optional argument with a
@@ -644,6 +642,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn
       def foo(arg: Optional[int] = None) -> None:
           ...
 
+   .. versionchanged:: 3.10
+      Optional can now be written as ``X | None``. See
+      :ref:`union type expressions<types-union>`.
+
 .. data:: Callable
 
    Callable type; ``Callable[[int], str]`` is a function of (int) -> str.
@@ -770,7 +772,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
    :ref:`type variables <generics>`, and unions of any of these types.
    For example::
 
-      def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...
+      def new_non_team_user(user_class: Type[BasicUser | ProUser]): ...
 
    ``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
    to ``type``, which is the root of Python's metaclass hierarchy.
@@ -951,7 +953,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
    conditional code flow and applying the narrowing to a block of code.  The
    conditional expression here is sometimes referred to as a "type guard"::
 
-      def is_str(val: Union[str, float]):
+      def is_str(val: str | float):
           # "isinstance" type guard
           if isinstance(val, str):
               # Type of ``val`` is narrowed to ``str``
@@ -2031,7 +2033,7 @@ Introspection helpers
    For a typing object of the form ``X[Y, Z, ...]`` these functions return
    ``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
    :mod:`collections` class, it gets normalized to the original class.
-   If ``X`` is a :class:`Union` or :class:`Literal` contained in another
+   If ``X`` is a union or :class:`Literal` contained in another
    generic type, the order of ``(Y, Z, ...)`` may be different from the order
    of the original arguments ``[Y, Z, ...]`` due to type caching.
    For unsupported objects return ``None`` and ``()`` correspondingly.
@@ -2056,7 +2058,7 @@ Introspection helpers
           year: int
 
       is_typeddict(Film)  # => True
-      is_typeddict(Union[list, str])  # => False
+      is_typeddict(list | str)  # => False
 
    .. versionadded:: 3.10
 

Misc/NEWS.d/next/Documentation/2021-08-19-15-53-08.bpo-44957.imqrh3.rst

@@ -0,0 +1,3 @@
+Promote PEP 604 union syntax by using it where possible. Also, mention ``X |
+Y`` more prominently in section about ``Union`` and mention ``X | None`` at
+all in section about ``Optional``.