Overhaul operator stubs

stdlib/_operator.pyi

@@ -1,5 +1,6 @@
 import sys
 from typing import (
+    AbstractSet,
     Any,
     AnyStr,
     Callable,
@@ -9,6 +10,8 @@ from typing import (
     Mapping,
     MutableMapping,
     MutableSequence,
+    NoReturn,
+    Protocol,
     Sequence,
     SupportsAbs,
     Tuple,
@@ -18,44 +21,193 @@ from typing import (
 from typing_extensions import ParamSpec, SupportsIndex, final
 
 _R = TypeVar("_R")
+_R_co = TypeVar("_R_co", covariant=True)
 _T = TypeVar("_T")
 _T_co = TypeVar("_T_co", covariant=True)
 _K = TypeVar("_K")
 _V = TypeVar("_V")
 _P = ParamSpec("_P")
+_X = TypeVar("_X", contravariant=True)
 
-def lt(__a: Any, __b: Any) -> Any: ...
-def le(__a: Any, __b: Any) -> Any: ...
-def eq(__a: Any, __b: Any) -> Any: ...
-def ne(__a: Any, __b: Any) -> Any: ...
-def ge(__a: Any, __b: Any) -> Any: ...
-def gt(__a: Any, __b: Any) -> Any: ...
-def not_(__a: Any) -> bool: ...
-def truth(__a: Any) -> bool: ...
-def is_(__a: Any, __b: Any) -> bool: ...
-def is_not(__a: Any, __b: Any) -> bool: ...
+class _SupportsLessThanX(Protocol[_X]):
+    def __lt__(self, other: _X) -> bool: ...
+
+class _SupportsGreaterThanX(Protocol[_X]):
+    def __gt__(self, other: _X) -> bool: ...
+
+class _SupportsLessThanOrEqualToX(Protocol[_X]):
+    def __le__(self, other: _X) -> bool: ...
+
+class _SupportsGreaterThanOrEqualToX(Protocol[_X]):
+    def __ge__(self, other: _X) -> bool: ...
+
+class _SupportsAddWithX(Protocol[_X]):
+    def __add__(self, other: _X) -> Any: ...
+
+class _SupportsRAddWithX(Protocol[_X]):
+    def __radd__(self, other: _X) -> Any: ...
+
+class _SupportsAndWithX(Protocol[_X]):
+    def __and__(self, other: _X) -> Any: ...
+
+class _SupportsRAndWithX(Protocol[_X]):
+    def __rand__(self, other: _X) -> Any: ...
+
+class _SupportsTrueDivWithX(Protocol[_X]):
+    def __truediv__(self, other: _X) -> Any: ...
+
+class _SupportsRTrueDivWithX(Protocol[_X]):
+    def __rtruediv__(self, other: _X) -> Any: ...
+
+class _SupportsFloorDivWithX(Protocol[_X]):
+    def __floordiv__(self, other: _X) -> Any: ...
+
+class _SupportsRFloorDivWithX(Protocol[_X]):
+    def __rfloordiv__(self, other: _X) -> Any: ...
+
+class _SupportsLShiftWithX(Protocol[_X]):
+    def __lshift__(self, other: _X) -> Any: ...
+
+class _SupportsRLShiftWithX(Protocol[_X]):
+    def __rlshift__(self, other: _X) -> Any: ...
+
+class _SupportsModWithX(Protocol[_X]):
+    def __mod__(self, other: _X) -> Any: ...
+
+class _SupportsRModWithX(Protocol[_X]):
+    def __rmod__(self, other: _X) -> Any: ...
+
+class _SupportsMulWithX(Protocol[_X]):
+    def __mul__(self, other: _X) -> Any: ...
+
+class _SupportsRMulWithX(Protocol[_X]):
+    def __rmul__(self, other: _X) -> Any: ...
+
+class _SupportsMatMulWithX(Protocol[_X]):
+    def __matmul__(self, other: _X) -> Any: ...
+
+class _SupportsRMatMulWithX(Protocol[_X]):
+    def __rmatmul__(self, other: _X) -> Any: ...
+
+class _SupportsOrWithX(Protocol[_X]):
+    def __or__(self, other: _X) -> Any: ...
+
+class _SupportsROrWithX(Protocol[_X]):
+    def __ror__(self, other: _X) -> Any: ...
+
+class _SupportsRShiftWithX(Protocol[_X]):
+    def __rshift__(self, other: _X) -> Any: ...
+
+class _SupportsRRShiftWithX(Protocol[_X]):
+    def __rrshift__(self, other: _X) -> Any: ...
+
+class _SupportsSubWithX(Protocol[_X]):
+    def __sub__(self, other: _X) -> Any: ...
+
+class _SupportsRSubWithX(Protocol[_X]):
+    def __rsub__(self, other: _X) -> Any: ...
+
+class _SupportsXOrWithX(Protocol[_X]):
+    def __xor__(self, other: _X) -> Any: ...
+
+class _SupportsRXOrWithX(Protocol[_X]):
+    def __rxor__(self, other: _X) -> Any: ...
+
+class _SupportsInv(Protocol[_R_co]):
+    def __inv__(self) -> _R_co: ...
+
+class _SupportsNeg(Protocol[_R_co]):
+    def __neg__(self) -> _R_co: ...
+
+class _SupportsPos(Protocol[_R_co]):
+    def __pos__(self) -> _R_co: ...
+
+class _Unhashable(Protocol):
+    __hash__: None  # type: ignore[assignment]
+
+@overload
+def lt(__a: _SupportsLessThanX[_X], __b: _X) -> bool: ...
+@overload
+def lt(__a: _X, __b: _SupportsGreaterThanX[_X]) -> bool: ...
+@overload
+def le(__a: _SupportsLessThanOrEqualToX[_X], __b: _X) -> bool: ...
+@overload
+def le(__a: _X, __b: _SupportsGreaterThanOrEqualToX[_X]) -> bool: ...
+@overload
+def ge(__a: _SupportsGreaterThanOrEqualToX[_X], __b: _X) -> bool: ...
+@overload
+def ge(__a: _X, __b: _SupportsLessThanOrEqualToX[_X]) -> bool: ...
+@overload
+def gt(__a: _SupportsGreaterThanX[_X], __b: _X) -> bool: ...
+@overload
+def gt(__a: _X, __b: _SupportsGreaterThanX[_X]) -> bool: ...
+def eq(__a: object, __b: object) -> bool: ...
+def ne(__a: object, __b: object) -> bool: ...
+def not_(__a: object) -> bool: ...
+def truth(__a: object) -> bool: ...
+def is_(__a: object, __b: object) -> bool: ...
+def is_not(__a: object, __b: object) -> bool: ...
 def abs(__a: SupportsAbs[_T]) -> _T: ...
-def add(__a: Any, __b: Any) -> Any: ...
-def and_(__a: Any, __b: Any) -> Any: ...
-def floordiv(__a: Any, __b: Any) -> Any: ...
-def index(__a: Any) -> int: ...
-def inv(__a: Any) -> Any: ...
-def invert(__a: Any) -> Any: ...
-def lshift(__a: Any, __b: Any) -> Any: ...
-def mod(__a: Any, __b: Any) -> Any: ...
-def mul(__a: Any, __b: Any) -> Any: ...
-def matmul(__a: Any, __b: Any) -> Any: ...
-def neg(__a: Any) -> Any: ...
-def or_(__a: Any, __b: Any) -> Any: ...
-def pos(__a: Any) -> Any: ...
+@overload
+def add(__a: _SupportsAddWithX[_X], __b: _X) -> Any: ...
+@overload
+def add(__a: _X, __b: _SupportsRAddWithX[_X]) -> Any: ...
+@overload
+def and_(__a: _SupportsAndWithX[_X], __b: _X) -> Any: ...
+@overload
+def and_(__a: _X, __b: _SupportsRAndWithX[_X]) -> Any: ...
+@overload
+def floordiv(__a: _SupportsFloorDivWithX[_X], __b: _X) -> Any: ...
+@overload
+def floordiv(__a: _X, __b: _SupportsRFloorDivWithX[_X]) -> Any: ...
+def index(__a: SupportsIndex) -> int: ...
+def inv(__a: _SupportsInv[_R_co]) -> _R_co: ...
+def invert(__a: _SupportsInv[_R_co]) -> _R_co: ...
+@overload
+def lshift(__a: _SupportsLShiftWithX[_X], __b: _X) -> Any: ...
+@overload
+def lshift(__a: _X, __b: _SupportsRLShiftWithX[_X]) -> Any: ...
+@overload
+def mod(__a: _SupportsModWithX[_X], __b: _X) -> Any: ...
+@overload
+def mod(__a: _X, __b: _SupportsRModWithX[_X]) -> Any: ...
+@overload
+def mul(__a: _SupportsMulWithX[_X], __b: _X) -> Any: ...
+@overload
+def mul(__a: _X, __b: _SupportsRMulWithX[_X]) -> Any: ...
+@overload
+def matmul(__a: _SupportsMatMulWithX[_X], __b: _X) -> Any: ...
+@overload
+def matmul(__a: _X, __b: _SupportsRMatMulWithX[_X]) -> Any: ...
+def neg(__a: _SupportsNeg[_R_co]) -> _R_co: ...
+@overload
+def or_(__a: _SupportsOrWithX[_X], __b: _X) -> Any: ...
+@overload
+def or_(__a: _X, __b: _SupportsROrWithX[_X]) -> Any: ...
+def pos(__a: _SupportsPos[_R_co]) -> _R_co: ...
 def pow(__a: Any, __b: Any) -> Any: ...
-def rshift(__a: Any, __b: Any) -> Any: ...
-def sub(__a: Any, __b: Any) -> Any: ...
-def truediv(__a: Any, __b: Any) -> Any: ...
-def xor(__a: Any, __b: Any) -> Any: ...
+@overload
+def rshift(__a: _SupportsRShiftWithX[_X], __b: _X) -> Any: ...
+@overload
+def rshift(__a: _X, __b: _SupportsRRShiftWithX[_X]) -> Any: ...
+@overload
+def sub(__a: _SupportsSubWithX[_X], __b: _X) -> Any: ...
+@overload
+def sub(__a: _X, __b: _SupportsRSubWithX[_X]) -> Any: ...
+@overload
+def truediv(__a: _SupportsTrueDivWithX[_X], __b: _X) -> Any: ...
+@overload
+def truediv(__a: _X, __b: _SupportsRTrueDivWithX[_X]) -> Any: ...
+@overload
+def xor(__a: _SupportsXOrWithX[_X], __b: _X) -> Any: ...
+@overload
+def xor(__a: _X, __b: _SupportsRXOrWithX[_X]) -> Any: ...
 def concat(__a: Sequence[_T], __b: Sequence[_T]) -> Sequence[_T]: ...
-def contains(__a: Container[Any], __b: Any) -> bool: ...
-def countOf(__a: Iterable[Any], __b: Any) -> int: ...
+@overload
+def contains(__a: AbstractSet[Any] | Mapping[Any, Any], __b: _Unhashable) -> NoReturn: ...
+@overload
+def contains(__a: Container[Any], __b: object) -> bool: ...
+def countOf(__a: Iterable[Any], __b: object) -> int: ...
 @overload
 def delitem(__a: MutableSequence[Any], __b: SupportsIndex) -> None: ...
 @overload