https://github.com/python/cpython/commit/b936ccdb6f6bd11250b4e638b6fa2c239907ca58
commit: b936ccdb6f6bd11250b4e638b6fa2c239907ca58
branch: main
author: Valentin Berlier <berlie...@gmail.com>
committer: JelleZijlstra <jelle.zijls...@gmail.com>
date: 2025-05-05T19:05:16-07:00
summary:
gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types
referenced through a type alias are not flattened (#130119)
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 3afcba6e898a63..54cc3ea3311adf 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
@@ -1230,6 +1236,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
@@ -1400,6 +1432,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
