harmonize builtins and typing_extensions, fix various __(r)or__ methods

Author: AlexWaygood

stdlib/builtins.pyi

@@ -33,7 +33,7 @@ from _typeshed import (
 from collections.abc import Awaitable, Callable, Iterable, Iterator, MutableSet, Reversible, Set as AbstractSet, Sized
 from io import BufferedRandom, BufferedReader, BufferedWriter, FileIO, TextIOWrapper
 from os import PathLike
-from types import CellType, CodeType, EllipsisType, GenericAlias, NotImplementedType, TracebackType
+from types import CellType, CodeType, EllipsisType, GenericAlias, NotImplementedType, TracebackType, UnionType
 
 # mypy crashes if any of {ByteString, Sequence, MutableSequence, Mapping, MutableMapping}
 # are imported from collections.abc in builtins.pyi
@@ -2185,11 +2185,13 @@ if sys.version_info >= (3, 15):
     class sentinel:
         __name__: str
         __module__: str
-        def __new__(cls, name: str, /, *, repr: str | None = None) -> Self: ...
-        def __copy__(self, /) -> Self: ...
-        def __deepcopy__(self, memo: Any, /) -> Self: ...
-        def __or__(self, other: Any, /) -> Any: ...
-        def __ror__(self, other: Any, /) -> Any: ...
+        def __new__(cls, name: str, /, *, repr: str | None = None) -> sentinel: ...
+        def __copy__(self, /) -> sentinel: ...
+        def __deepcopy__(self, memo: Any, /) -> sentinel: ...
+        # `other` can be any legal form for unions.
+        # `sentinel("X") | sentinel("X")` creates a `sentinel` instance, not a `UnionType` instance.
+        def __or__(self, other: Any, /) -> UnionType | sentinel: ...
+        def __ror__(self, other: Any, /) -> UnionType | sentinel: ...
 
 @overload
 def sorted(

stdlib/types.pyi

@@ -703,8 +703,10 @@ class GenericAlias:
         @property
         def __typing_unpacked_tuple_args__(self) -> tuple[Any, ...] | None: ...
 
-    def __or__(self, value: Any, /) -> UnionType: ...
-    def __ror__(self, value: Any, /) -> UnionType: ...
+    # `other` can be any legal form for unions.
+    # `list[int] | list[int]` creates a `GenericAlias` instance, not a `UnionType` instance
+    def __or__(self, value: Any, /) -> UnionType | GenericAlias: ...
+    def __ror__(self, value: Any, /) -> UnionType | GenericAlias: ...
 
     # GenericAlias delegates attr access to `__origin__`
     def __getattr__(self, name: str) -> Any: ...

stdlib/typing_extensions.pyi

@@ -687,11 +687,15 @@ else:
     class sentinel:
         def __init__(self, name: str, /, *, repr: str | None = None) -> None: ...
         __name__: str
+        __module__: str
         if sys.version_info >= (3, 14):
-            def __or__(self, other: Any) -> UnionType: ...  # other can be any type form legal for unions
-            def __ror__(self, other: Any) -> UnionType: ...  # other can be any type form legal for unions
+            # `other`` can be any type form legal for unions.
+            # `sentinel("X") | sentinel("X")` creates a `sentinel` instance, not a `UnionType` instance
+            def __or__(self, other: Any) -> UnionType | sentinel: ...
+            def __ror__(self, other: Any) -> UnionType | sentinel: ...
         else:
-            def __or__(self, other: Any) -> _SpecialForm: ...  # other can be any type form legal for unions
-            def __ror__(self, other: Any) -> _SpecialForm: ...  # other can be any type form legal for unions
+            # other can be any type form legal for unions
+            def __or__(self, other: Any) -> _SpecialForm: ...
+            def __ror__(self, other: Any) -> _SpecialForm: ...
 
 Sentinel = sentinel