Same improvement to the documentation of Union and Literal

Author: vberlier

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,33 @@ 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.
 
+   ``Literal`` is very similar to :class:`Union`, the main difference is that its
+   arguments are literal values instead of types:
+
+   * 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 Union[1, 2, 1] == Union[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

Lib/typing.py

@@ -765,6 +765,13 @@ def Union(self, parameters):
 
         assert 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
+      TypeAliasType::
+
+        type A = Union[int, str]
+        assert Union[A, float] != Union[int, str, float]
+
     - Unions of a single argument vanish, e.g.::
 
         assert Union[int] == int  # The constructor actually returns int
@@ -830,6 +837,33 @@ def open_helper(file: str, mode: MODE) -> str:
     Literal[...] cannot be subclassed. At runtime, an arbitrary value
     is allowed as type argument to Literal[...], but type checkers may
     impose restrictions.
+
+    Literal is very similar to Union, the main difference is that its
+    arguments are literal values instead of types:
+
+    - 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 TypeAliasType::
+
+        type A = Literal[1, 2]
+        assert Literal[A, 3] != Literal[1, 2, 3]
+
+    - Redundant arguments are skipped, e.g.::
+
+        assert Union[1, 2, 1] == Union[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].
     """
     # There is no '_type_check' call because arguments to Literal[...] are
     # values, not types.