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

Doc/deprecations/pending-removal-in-future.rst

@@ -127,6 +127,11 @@ although there is currently no date scheduled for their removal.
 
 * :class:`typing.Text` (:gh:`92332`).
 
+* 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 at least Python 3.17. (Contributed by
+ Jelle Zijlstra in :gh:`105499`.)
+
 * :class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a value
  that is not ``None`` from a test case.
 

Doc/library/functools.rst

@@ -518,7 +518,7 @@
  ... 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):
@@ -654,8 +654,8 @@
  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

@@ -5364,7 +5364,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 | ...
 
@@ -5400,9 +5400,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``::
 
@@ -5428,16 +5429,15 @@ 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()
+ >>> typing.Union()
  Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
- TypeError: cannot create 'types.UnionType' instances
+ TypeError: cannot create 'typing.Union' instances
 
 .. note::
  The :meth:`!__or__` method for type objects was added to support the syntax
@@ -5464,6 +5464,11 @@ instantiated from the type::
 
 .. versionadded:: 3.10
 
+.. versionchanged:: 3.14
+
+ Union objects are now instances of :class:`typing.Union`. Previously, they were instances
+ of :class:`types.UnionType`, which remains an alias for :class:`typing.Union`.
+
 
 .. _typesother:
 

Doc/library/types.rst

@@ -314,6 +314,10 @@ Standard names are defined for the following types:
 
  .. versionadded:: 3.10
 
+ .. versionchanged:: 3.14
+
+ 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

@@ -1086,7 +1086,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.
 
@@ -1121,6 +1121,14 @@ 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.14
+ :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)``. For compatibility with earlier versions of
+ Python, use
+ ``get_origin(obj) is typing.Union or get_origin(obj) is types.UnionType``.
+
 .. data:: Optional
 
  ``Optional[X]`` is equivalent to ``X | None`` (or ``Union[X, None]``).

Doc/whatsnew/3.10.rst

@@ -722,10 +722,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

@@ -740,8 +740,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

Include/internal/pycore_unionobject.h

@@ -18,6 +18,7 @@ PyAPI_FUNC(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

@@ -926,16 +926,11 @@ def dispatch(cls):
  dispatch_cache[cls] = impl
  return impl
 
- def _is_union_type(cls):
- from typing import get_origin, Union
- return get_origin(cls) in{Union, 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)))
+ return (isinstance(cls, UnionType) and
+ all(isinstance(arg, type) for arg in cls.__args__))
 
  def register(cls, func=None):
  """generic_func.register(cls, func) -> func
@@ -967,7 +962,7 @@ def register(cls, func=None):
  from annotationlib import Format, ForwardRef
  argname, cls = next(iter(get_type_hints(func, format=Format.FORWARDREF).items()))
  if not _is_valid_dispatch_type(cls):
- if _is_union_type(cls):
+ if isinstance(cls, UnionType):
  raise TypeError(
  f"Invalid annotation for{argname!r}. "
  f"{cls!r} not all arguments are classes."
@@ -983,10 +978,8 @@ def register(cls, func=None):
  f"{cls!r} is not a class."
  )
 
- if _is_union_type(cls):
- from typing import get_args
-
- for arg in get_args(cls):
+ if isinstance(cls, UnionType):
+ for arg in cls.__args__:
  registry[arg] = func
  else:
  registry[cls] = func

Lib/test/test_dataclasses/__init__.py

@@ -2313,7 +2313,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

@@ -3083,7 +3083,7 @@ def _(arg: typing.Union[int, typing.Iterable[str]]):
  "Invalid annotation for 'arg'."
  )
  self.assertEndsWith(str(exc.exception),
- '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

@@ -1750,8 +1750,8 @@ class C(metaclass=M):
 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 TestIsMethodDescriptor(unittest.TestCase):

Lib/test/test_pydoc/test_pydoc.py

@@ -133,7 +133,7 @@ class C(builtins.object)
  c_alias = test.test_pydoc.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
@@ -223,7 +223,7 @@ class C(builtins.object)
  c_alias = test.test_pydoc.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
@@ -1447,17 +1447,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)
  if not MISSING_C_DOCSTRINGS:
  self.assertIn(types.UnionType.__doc__.strip().splitlines()[0], doc)
 

Lib/test/test_types.py

@@ -709,10 +709,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))
@@ -727,17 +723,40 @@ class B(metaclass=UnhashableMeta): ...
 
  self.assertEqual((A | B).__args__, (A, B))
  union1 = A | B
- with self.assertRaises(TypeError):
+ with self.assertRaisesRegex(TypeError, "unhashable type: 'UnhashableMeta'"):
  hash(union1)
 
  union2 = int | B
- with self.assertRaises(TypeError):
+ with self.assertRaisesRegex(TypeError, "unhashable type: 'UnhashableMeta'"):
  hash(union2)
 
  union3 = A | int
- with self.assertRaises(TypeError):
+ with self.assertRaisesRegex(TypeError, "unhashable type: 'UnhashableMeta'"):
  hash(union3)
 
+ def test_unhashable_becomes_hashable(self):
+ is_hashable = False
+ class UnhashableMeta(type):
+ def __hash__(self):
+ if is_hashable:
+ return 1
+ else:
+ raise TypeError("not hashable")
+
+ class A(metaclass=UnhashableMeta): ...
+ class B(metaclass=UnhashableMeta): ...
+
+ union = A | B
+ self.assertEqual(union.__args__, (A, B))
+
+ with self.assertRaisesRegex(TypeError, "not hashable"):
+ hash(union)
+
+ is_hashable = True
+
+ with self.assertRaisesRegex(TypeError, "union contains 2 unhashable elements"):
+ hash(union)
+
  def test_instancecheck_and_subclasscheck(self):
  for x in (int | str, typing.Union[int, str]):
  with self.subTest(x=x):
@@ -921,7 +940,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):
@@ -1015,9 +1034,14 @@ def __eq__(self, other):
  return 1 / 0
 
  bt = BadType('bt', (),{})
+ bt2 = BadType('bt2', (),{})
  # Comparison should fail and errors should propagate out for bad types.
+ union1 = int | bt
+ union2 = int | bt2
+ with self.assertRaises(ZeroDivisionError):
+ union1 == union2
  with self.assertRaises(ZeroDivisionError):
-list[int] | list[bt]
+bt | bt2
 
  union_ga = (list[str] | int, collections.abc.Callable[..., str] | int,
  d | int)
@@ -1060,6 +1084,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