https://github.com/python/cpython/commit/fe18437089e6eccfa09e7c12a4f807fc158274ba
commit: fe18437089e6eccfa09e7c12a4f807fc158274ba
branch: 3.13
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: JelleZijlstra <jelle.zijls...@gmail.com>
date: 2025-05-06T02:13:22Z
summary:
[3.13] gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types
referenced through a type alias are not flattened (GH-130119) (#133488)
gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types
referenced through a type alias are not flattened (GH-130119)
(cherry picked from commit b936ccdb6f6bd11250b4e638b6fa2c239907ca58)
Co-authored-by: Valentin Berlier <berlie...@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijls...@gmail.com>
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 8809ba59aca1d0..a18d6d81261014 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1098,6 +1098,12 @@ These can be used as types in annotations. They all
support subscription using
Union[Union[int, str], float] == Union[int, str, float]
+ However, this does not apply to unions referenced through a type
+ alias, to avoid forcing evaluation of the underlying
:class:`TypeAliasType`::
+
+ type A = Union[int, str]
+ Union[A, float] != Union[int, str, float]
+
* Unions of a single argument vanish, e.g.::
Union[int] == int # The constructor actually returns int
@@ -1222,6 +1228,32 @@ These can be used as types in annotations. They all
support subscription using
is allowed as type argument to ``Literal[...]``, but type checkers may
impose restrictions. See :pep:`586` for more details about literal types.
+ Additional details:
+
+ * The arguments must be literal values and there must be at least one.
+
+ * Nested ``Literal`` types are flattened, e.g.::
+
+ assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3]
+
+ However, this does not apply to ``Literal`` types referenced through a
type
+ alias, to avoid forcing evaluation of the underlying
:class:`TypeAliasType`::
+
+ type A = Literal[1, 2]
+ assert Literal[A, 3] != Literal[1, 2, 3]
+
+ * Redundant arguments are skipped, e.g.::
+
+ assert Literal[1, 2, 1] == Literal[1, 2]
+
+ * When comparing literals, the argument order is ignored, e.g.::
+
+ assert Literal[1, 2] == Literal[2, 1]
+
+ * You cannot subclass or instantiate a ``Literal``.
+
+ * You cannot write ``Literal[X][Y]``.
+
.. versionadded:: 3.8
.. versionchanged:: 3.9.1
@@ -1392,6 +1424,14 @@ These can be used as types in annotations. They all
support subscription using
int, ValueRange(3, 10), ctype("char")
]
+ However, this does not apply to ``Annotated`` types referenced through a
type
+ alias, to avoid forcing evaluation of the underlying
:class:`TypeAliasType`::
+
+ type From3To10[T] = Annotated[T, ValueRange(3, 10)]
+ assert Annotated[From3To10[int], ctype("char")] != Annotated[
+ int, ValueRange(3, 10), ctype("char")
+ ]
+
Duplicated metadata elements are not removed::
assert Annotated[int, ValueRange(3, 10)] != Annotated[
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
