add tests, update comments, remove type

Author: KotlinIsland

stdlib/@tests/test_cases/check_types.py

@@ -3,9 +3,11 @@
 import sys
 import types
 from collections import UserDict
-from typing import Union
+from typing import Any, Literal, TypeVar, Union
 from typing_extensions import assert_type
 
+_T = TypeVar("_T")
+
 # test `types.SimpleNamespace`
 
 # Valid:
@@ -58,3 +60,12 @@ def foo(self, value: int) -> None:
     @foo.deleter
     def foo(self) -> None:
         self._value = None
+
+
+if sys.version_info > (3, 10):
+    union_type = int | list[_T]
+
+    # ideally this would be `_SpecialForm` (Union)
+    assert_type(union_type | Literal[1], types.UnionType | Any)
+    # pyright special cases this operation
+    assert_type(union_type[int], object)  # pyright: ignore[reportAssertTypeFailure]

stdlib/types.pyi

@@ -717,12 +717,18 @@ if sys.version_info >= (3, 10):
         def __args__(self) -> tuple[Any, ...]: ...
         @property
         def __parameters__(self) -> tuple[Any, ...]: ...
-        # the `Any` in the return typeis because of underspecified binop semantics, and `value: Any` is clobbering
-        #  `_SpecialForm.__ror__` which would result in a `_SpecialForm` (Union)
-        def __or__(self, value: Any, /) -> UnionType | type | Any: ...
-        def __ror__(self, value: Any, /) -> UnionType | type | Any: ...
+        # `(int | str) | Literal["foo"]` returns a generic alias to an instance of `_SpecialForm` (`Union`).
+        # Normally we'd express this using the return type of `_SpecialForm.__ror__`,
+        # but because `UnionType.__or__` accepts `Any`, type checkers will use
+        # the return type of `UnionType.__or__` to infer the result of this operation
+        # rather than `_SpecialForm.__ror__`. To mitigate this, we use `| Any`
+        # in the return type of `UnionType.__(r)or__`.
+        def __or__(self, value: Any, /) -> UnionType | Any: ...
+        def __ror__(self, value: Any, /) -> UnionType | Any: ...
         def __eq__(self, value: object, /) -> bool: ...
         def __hash__(self) -> int: ...
+        # you can only subscript a `UnionType` instance if at least one of the elements
+        # in the union is a generic alias instance that has a non-empty `__parameters__`
         def __getitem__(self, parameters: Any) -> object: ...
 
 if sys.version_info >= (3, 13):