gh-105499: Merge typing.Union and types.UnionType

Doc/library/functools.rst

@@ -465,7 +465,7 @@ The :mod:`functools` module defines the following functions:
      ...     for i, elem in enumerate(arg):
      ...         print(i, elem)
 
-   :data:`types.UnionType` and :data:`typing.Union` can also be used::
+   :class:`typing.Union` can also be used::
 
     >>> @fun.register
     ... def _(arg: int | float, verbose=False):
@@ -582,8 +582,8 @@ The :mod:`functools` module defines the following functions:
       The :func:`register` attribute now supports using type annotations.
 
    .. versionchanged:: 3.11
-      The :func:`register` attribute now supports :data:`types.UnionType`
-      and :data:`typing.Union` as type annotations.
+      The :func:`register` attribute now supports
+      :class:`typing.Union` as a type annotation.
 
 
 .. class:: singledispatchmethod(func)

Doc/library/stdtypes.rst

@@ -5157,7 +5157,7 @@ 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 :term:`type annotations <annotation>`. The union type expression
-enables cleaner type hinting syntax compared to :data:`typing.Union`.
+enables cleaner type hinting syntax compared to subscripting :class:`typing.Union`.
 
 .. describe:: X | Y | ...
 
@@ -5193,9 +5193,10 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
 
       int | str == str | int
 
-   * It is compatible with :data:`typing.Union`::
+   * It creates instances of :class:`typing.Union`::
 
       int | str == typing.Union[int, str]
+      type(int | str) is typing.Union
 
    * Optional types can be spelled as a union with ``None``::
 
@@ -5221,16 +5222,11 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
       TypeError: isinstance() argument 2 cannot be a parameterized generic
 
 The user-exposed type for the union object can be accessed from
-:data:`types.UnionType` and used for :func:`isinstance` checks.  An object cannot be
-instantiated from the type::
+:class:`typing.Union` and used for :func:`isinstance` checks::
 
-   >>> import types
-   >>> isinstance(int | str, types.UnionType)
+   >>> import typing
+   >>> isinstance(int | str, typing.Union)
    True
-   >>> types.UnionType()
-   Traceback (most recent call last):
-     File "<stdin>", line 1, in <module>
-   TypeError: cannot create 'types.UnionType' instances
 
 .. note::
    The :meth:`__or__` method for type objects was added to support the syntax

Doc/library/types.rst

@@ -367,6 +367,10 @@ Standard names are defined for the following types:
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: 3.13
+
+      This is now an alias for :class:`typing.Union`.
+
 .. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)
 
    The type of traceback objects such as found in ``sys.exception().__traceback__``.

Doc/library/typing.rst

@@ -1064,7 +1064,7 @@ Special forms
 These can be used as types in annotations. They all support subscription using
 ``[]``, but each has a unique syntax.
 
-.. data:: Union
+.. class:: Union
 
    Union type; ``Union[X, Y]`` is equivalent to ``X | Y`` and means either X or Y.
 
@@ -1099,6 +1099,12 @@ These can be used as types in annotations. They all support subscription using
       Unions can now be written as ``X | Y``. See
       :ref:`union type expressions<types-union>`.
 
+   .. versionchanged:: 3.13
+      :class:`types.UnionType` is now an alias for :class:`Union`, and both
+      ``Union[int, str]`` and ``int | str`` create instances of the same class.
+      To check whether an object is a ``Union`` at runtime, use
+      ``isinstance(obj, Union)``.
+
 .. data:: Optional
 
    ``Optional[X]`` is equivalent to ``X | None`` (or ``Union[X, None]``).

Doc/whatsnew/3.10.rst

@@ -718,10 +718,10 @@ PEP 604: New Type Union 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`, especially in type hints.
+using :class:`typing.Union`, especially in type hints.
 
 In previous versions of Python, to apply a type hint for functions accepting
-arguments of multiple types, :data:`typing.Union` was used::
+arguments of multiple types, :class:`typing.Union` was used::
 
    def square(number: Union[int, float]) -> Union[int, float]:
        return number ** 2

Doc/whatsnew/3.11.rst

@@ -741,8 +741,8 @@ fractions
 functools
 ---------
 
-* :func:`functools.singledispatch` now supports :data:`types.UnionType`
-  and :data:`typing.Union` as annotations to the dispatch argument.::
+* :func:`functools.singledispatch` now supports :class:`types.UnionType`
+  and :class:`typing.Union` as annotations to the dispatch argument.::
 
     >>> from functools import singledispatch
     >>> @singledispatch

Doc/whatsnew/3.13.rst

@@ -298,7 +298,12 @@ Deprecated
   emits :exc:`DeprecationWarning` since 3.13
   and will be removed in Python 3.16.
   Use the ``'w'`` format code instead.
-  (contributed by Hugo van Kemenade in :gh:`80480`)
+  (Contributed by Hugo van Kemenade in :gh:`80480`)
+
+* The internal class ``typing._UnionGenericAlias`` is no longer used to implement
+  :class:`typing.Union`. To preserve compatibility with users using this private
+  class, a compatibility shim will be provided until Python 3.15. (Contributed by
+  Jelle Zijlstra in :gh:`105499`.)
 
 * :mod:`ctypes`: Deprecate undocumented :func:`!ctypes.SetPointerType`
   and :func:`!ctypes.ARRAY` functions.

Include/internal/pycore_unionobject.h

@@ -16,6 +16,7 @@ extern PyObject *_Py_union_type_or(PyObject *, PyObject *);
 extern PyObject *_Py_subs_parameters(PyObject *, PyObject *, PyObject *, PyObject *);
 extern PyObject *_Py_make_parameters(PyObject *);
 extern PyObject *_Py_union_args(PyObject *self);
+extern PyObject *_Py_union_from_tuple(PyObject *args);
 
 #ifdef __cplusplus
 }

Lib/functools.py

@@ -22,6 +22,7 @@
 
 # Avoid importing types, so we can speedup import time
 GenericAlias = type(list[int])
+UnionType = type(int | str)
 
 ################################################################################
 ### update_wrapper() and wraps() decorator
@@ -841,15 +842,13 @@ def dispatch(cls):
         return impl
 
     def _is_union_type(cls):
-        from typing import get_origin, Union
-        return get_origin(cls) in {Union, types.UnionType}
+        return isinstance(cls, UnionType)
 
     def _is_valid_dispatch_type(cls):
         if isinstance(cls, type):
             return True
-        from typing import get_args
         return (_is_union_type(cls) and
-                all(isinstance(arg, type) for arg in get_args(cls)))
+                all(isinstance(arg, type) for arg in cls.__args__))
 
     def register(cls, func=None):
         """generic_func.register(cls, func) -> func
@@ -892,9 +891,7 @@ def register(cls, func=None):
                     )
 
         if _is_union_type(cls):
-            from typing import get_args
-
-            for arg in get_args(cls):
+            for arg in cls.__args__:
                 registry[arg] = func
         else:
             registry[cls] = func

Lib/test/test_dataclasses/__init__.py

@@ -2267,7 +2267,7 @@ def test_docstring_one_field_with_default_none(self):
         class C:
             x: Union[int, type(None)] = None
 
-        self.assertDocStrEqual(C.__doc__, "C(x:Optional[int]=None)")
+        self.assertDocStrEqual(C.__doc__, "C(x:int|None=None)")
 
     def test_docstring_list_field(self):
         @dataclass

Lib/test/test_functools.py

@@ -2840,7 +2840,7 @@ def _(arg: typing.Union[int, typing.Iterable[str]]):
             "Invalid annotation for 'arg'."
         ))
         self.assertTrue(str(exc.exception).endswith(
-            'typing.Union[int, typing.Iterable[str]] not all arguments are classes.'
+            'int | typing.Iterable[str] not all arguments are classes.'
         ))
 
     def test_invalid_positional_argument(self):

Lib/test/test_inspect/test_inspect.py

@@ -1626,8 +1626,8 @@ def wrapper(a, b):
 class TestFormatAnnotation(unittest.TestCase):
     def test_typing_replacement(self):
         from test.typinganndata.ann_module9 import ann, ann1
-        self.assertEqual(inspect.formatannotation(ann), 'Union[List[str], int]')
-        self.assertEqual(inspect.formatannotation(ann1), 'Union[List[testModule.typing.A], int]')
+        self.assertEqual(inspect.formatannotation(ann), 'List[str] | int')
+        self.assertEqual(inspect.formatannotation(ann1), 'List[testModule.typing.A] | int')
 
 
 class TestIsDataDescriptor(unittest.TestCase):

Lib/test/test_pydoc.py

@@ -127,7 +127,7 @@ class C(builtins.object)
     c_alias = test.pydoc_mod.C[int]
     list_alias1 = typing.List[int]
     list_alias2 = list[int]
-    type_union1 = typing.Union[int, str]
+    type_union1 = int | str
     type_union2 = int | str
 
 VERSION
@@ -212,7 +212,7 @@ class C(builtins.object)
     c_alias = test.pydoc_mod.C[int]
     list_alias1 = typing.List[int]
     list_alias2 = list[int]
-    type_union1 = typing.Union[int, str]
+    type_union1 = int | str
     type_union2 = int | str
 
 Author
@@ -1074,17 +1074,17 @@ def test_generic_alias(self):
         self.assertIn(list.__doc__.strip().splitlines()[0], doc)
 
     def test_union_type(self):
-        self.assertEqual(pydoc.describe(typing.Union[int, str]), '_UnionGenericAlias')
+        self.assertEqual(pydoc.describe(typing.Union[int, str]), 'Union')
         doc = pydoc.render_doc(typing.Union[int, str], renderer=pydoc.plaintext)
-        self.assertIn('_UnionGenericAlias in module typing', doc)
-        self.assertIn('Union = typing.Union', doc)
+        self.assertIn('Union in module typing', doc)
+        self.assertIn('class Union(builtins.object)', doc)
         if typing.Union.__doc__:
             self.assertIn(typing.Union.__doc__.strip().splitlines()[0], doc)
 
-        self.assertEqual(pydoc.describe(int | str), 'UnionType')
+        self.assertEqual(pydoc.describe(int | str), 'Union')
         doc = pydoc.render_doc(int | str, renderer=pydoc.plaintext)
-        self.assertIn('UnionType in module types object', doc)
-        self.assertIn('\nclass UnionType(builtins.object)', doc)
+        self.assertIn('Union in module typing', doc)
+        self.assertIn('class Union(builtins.object)', doc)
         self.assertIn(types.UnionType.__doc__.strip().splitlines()[0], doc)
 
     def test_special_form(self):

Lib/test/test_types.py

@@ -702,10 +702,6 @@ def test_or_types_operator(self):
         y = int | bool
         with self.assertRaises(TypeError):
             x < y
-        # Check that we don't crash if typing.Union does not have a tuple in __args__
-        y = typing.Union[str, int]
-        y.__args__ = [str, int]
-        self.assertEqual(x, y)
 
     def test_hash(self):
         self.assertEqual(hash(int | str), hash(str | int))
@@ -894,7 +890,7 @@ def forward_before(x: ForwardBefore[int]) -> None: ...
         self.assertEqual(typing.get_args(typing.get_type_hints(forward_after)['x']),
                          (int, Forward))
         self.assertEqual(typing.get_args(typing.get_type_hints(forward_before)['x']),
-                         (int, Forward))
+                         (Forward, int))
 
     def test_or_type_operator_with_Protocol(self):
         class Proto(typing.Protocol):
@@ -1033,6 +1029,14 @@ def test_or_type_operator_reference_cycle(self):
         self.assertLessEqual(sys.gettotalrefcount() - before, leeway,
                              msg='Check for union reference leak.')
 
+    def test_instantiation(self):
+        with self.assertRaises(TypeError):
+            types.UnionType()
+        self.assertIs(int, types.UnionType[int])
+        self.assertIs(int, types.UnionType[int, int])
+        self.assertEqual(int | str, types.UnionType[int, str])
+        self.assertEqual(int | typing.ForwardRef("str"), types.UnionType[int, "str"])
+
 
 class MappingProxyTests(unittest.TestCase):
     mappingproxy = types.MappingProxyType