Skip to content

Commit 7473c60

Browse files
gh-131933: Document UnionType/Union merger in What's New (#131941)
Co-authored-by: Alex Waygood Co-authored-by: Bénédikt Tran <[email protected]>
1 parent ac3a7bf commit 7473c60

File tree

1 file changed

+53
-0
lines changed

1 file changed

+53
-0
lines changed

Doc/whatsnew/3.14.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1075,6 +1075,54 @@ turtle
10751075
(Contributed by Marie Roald and Yngve Mardal Moe in :gh:`126350`.)
10761076

10771077

1078+
types
1079+
-----
1080+
1081+
* :class:`types.UnionType` is now an alias for :class:`typing.Union`.
1082+
See :ref:`below <whatsnew314-typing-union>` for more details.
1083+
(Contributed by Jelle Zijlstra in :gh:`105499`.)
1084+
1085+
1086+
typing
1087+
------
1088+
1089+
.. _whatsnew314-typing-union:
1090+
1091+
* :class:`types.UnionType` and :class:`typing.Union` are now aliases for each other,
1092+
meaning that both old-style unions (created with ``Union[int, str]``) and new-style
1093+
unions (``int | str``) now create instances of the same runtime type. This unifies
1094+
the behavior between the two syntaxes, but leads to some differences in behavior that
1095+
may affect users who introspect types at runtime:
1096+
1097+
- Both syntaxes for creating a union now produce the same string representation in
1098+
``repr()``. For example, ``repr(Union[int, str])``
1099+
is now ``"int | str"`` instead of ``"typing.Union[int, str]"``.
1100+
- Unions created using the old syntax are no longer cached. Previously, running
1101+
``Union[int, str]`` multiple times would return the same object
1102+
(``Union[int, str] is Union[int, str]`` would be ``True``), but now it will
1103+
return two different objects. Users should use ``==`` to compare unions for equality, not
1104+
``is``. New-style unions have never been cached this way.
1105+
This change could increase memory usage for some programs that use a large number of
1106+
unions created by subscripting ``typing.Union``. However, several factors offset this cost:
1107+
unions used in annotations are no longer evaluated by default in Python 3.14
1108+
because of :pep:`649`; an instance of :class:`types.UnionType` is
1109+
itself much smaller than the object returned by ``Union[]`` was on prior Python
1110+
versions; and removing the cache also saves some space. It is therefore
1111+
unlikely that this change will cause a significant increase in memory usage for most
1112+
users.
1113+
- Previously, old-style unions were implemented using the private class
1114+
``typing._UnionGenericAlias``. This class is no longer needed for the implementation,
1115+
but it has been retained for backward compatibility, with removal scheduled for Python
1116+
3.17. Users should use documented introspection helpers like :func:`typing.get_origin`
1117+
and :func:`typing.get_args` instead of relying on private implementation details.
1118+
- It is now possible to use :class:`typing.Union` itself in :func:`isinstance` checks.
1119+
For example, ``isinstance(int | str, typing.Union)`` will return ``True``; previously
1120+
this raised :exc:`TypeError`.
1121+
- The ``__args__`` attribute of :class:`typing.Union` objects is no longer writable.
1122+
1123+
(Contributed by Jelle Zijlstra in :gh:`105499`.)
1124+
1125+
10781126
unicodedata
10791127
-----------
10801128

@@ -1608,6 +1656,11 @@ Changes in the Python API
16081656
This temporary change affects other threads.
16091657
(Contributed by Serhiy Storchaka in :gh:`69998`.)
16101658

1659+
* :class:`types.UnionType` is now an alias for :class:`typing.Union`,
1660+
causing changes in some behaviors.
1661+
See :ref:`above <whatsnew314-typing-union>` for more details.
1662+
(Contributed by Jelle Zijlstra in :gh:`105499`.)
1663+
16111664

16121665
Build changes
16131666
=============

0 commit comments

Comments
 (0)