python · gvanrossum · Oct 5, 2020 · Oct 3, 2020 · Oct 3, 2020 · Oct 3, 2020
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -4743,6 +4743,105 @@ define these methods must provide them as a normal Python accessible method.
 Compared to the overhead of setting up the runtime context, the overhead of a
 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`.
+
+.. 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, ...]``.
+   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:
+
+   * Unions of unions are flattened, e.g.::
+
+       (int | str) | float == int | str | float
+
+   * Redundant arguments are skipped, e.g.::
+
+       int | str | int == int | str
+
+   * When comparing unions, the argument order is ignored, e.g.::
+
+      int | str == str | int
+
+   * Compatible with :data:`typing.Union`::
+
+      int | str == typing.Union[int, str]
+
+   * Optional values are equivalent to :data:`typing.Optional`::
+
+      str | None == typing.Optional[str]
+
+.. describe:: isinstance(obj, union_object)
+
+   Calls to :func:`isinstance` are also supported with a Union object::
+
+      >>> isinstance("", int | str)
+      True
+
+   Union objects containing parametrized generics cannot be used::
+
+      >>> isinstance(1, int | list[int])
+      TypeError: isinstance() argument 2 cannot contain a parameterized generic
+
+.. describe:: issubclass(obj, union_object)
+
+   Calls to :func:`issubclass` are also supported with a Union Object.::
+
+      >>> issubclass(bool, int | str)
+      True
+
+   Union objects containing parametrized generics cannot be used::
+
+      >>> issubclass(bool, bool | list[str])
+      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.
+
+.. 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
+   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)
+
+.. seealso::
+
+   :pep:`604` -- PEP proposing the Union object and type.
+
+.. versionadded:: 3.10
+
 
 .. _typesother:
 

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
@@ -256,6 +256,11 @@ Standard names are defined for the following types:
 
    .. versionadded:: 3.10
 
+.. data:: Union
+
+   The type of :ref:`builtins.Union<types-union>`.
+
+   .. versionadded:: 3.10
 
 .. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)
 

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -544,6 +544,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn
    .. versionchanged:: 3.7
       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>`.
+
 .. data:: Optional
 
    Optional type.

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -82,6 +82,9 @@ 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`.)
 
 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
@@ -0,0 +1 @@
+Add documentation for :pep:`604` (Allow writing union types as X | Y).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add documentation for :pep:`604` (Allow writing union types as X \| Y).
Fidget-Spinner marked this conversation as resolved. Show resolved Hide resolved