Improve ordering comparisons in operator

stdlib/@tests/test_cases/check_operator.py

@@ -0,0 +1,49 @@
+import operator
+from typing import overload
+
+
+class Result: ...
+
+
+class Operand: ...
+
+
+class LessThan(Operand):
+    def __lt__(self, other: Operand, /) -> Result:
+        return Result()
+
+
+class GreaterEqual:
+    def __ge__(self, other: Operand, /) -> Result:
+        return Result()
+
+
+def check_comparisons(lt: LessThan, ge: GreaterEqual) -> None:
+    operator.lt(lt, lt)
+    operator.gt(lt, lt)
+    operator.ge(ge, lt)
+    operator.le(lt, ge)
+
+
+def check_one_sided_comparisons(lt: LessThan, ge: GreaterEqual, other: Operand) -> None:
+    operator.lt(lt, other)
+    operator.gt(other, lt)
+    operator.ge(ge, other)
+    operator.le(other, ge)
+    operator.lt(1, other)  # type: ignore[misc]
+
+    operators = {"<": operator.lt, "<=": operator.le, ">": operator.gt, ">=": operator.ge, "==": operator.eq, "!=": operator.ne}
+    operators["<"](lt, other)
+
+
+class Overloaded:
+    @overload
+    def __lt__(self, other: int, /) -> int: ...
+    @overload
+    def __lt__(self, other: str, /) -> str: ...
+    def __lt__(self, other: int | str, /) -> int | str:
+        return other
+
+
+def check_overloaded(value: Overloaded, other: int | str) -> None:
+    operator.lt(value, other)

stdlib/_operator.pyi

@@ -3,10 +3,6 @@ from _typeshed import (
     ReadableBuffer,
     SupportsAdd,
     SupportsBool,
-    SupportsDunderGE,
-    SupportsDunderGT,
-    SupportsDunderLE,
-    SupportsDunderLT,
     SupportsGetItem,
     SupportsMul,
     SupportsRAdd,
@@ -27,7 +23,35 @@ _K = TypeVar("_K")
 _V = TypeVar("_V")
 _P = ParamSpec("_P")
 
-_SupportsComparison: TypeAlias = SupportsDunderLE[Any] | SupportsDunderGE[Any] | SupportsDunderGT[Any] | SupportsDunderLT[Any]
+# operator returns the rich comparison result without testing its truth value.
+@type_check_only
+class _SupportsDunderLT(Protocol[_T_contra]):
+    def __lt__(self, other: _T_contra, /) -> object: ...
+
+@type_check_only
+class _SupportsDunderGT(Protocol[_T_contra]):
+    def __gt__(self, other: _T_contra, /) -> object: ...
+
+@type_check_only
+class _SupportsDunderLE(Protocol[_T_contra]):
+    def __le__(self, other: _T_contra, /) -> object: ...
+
+@type_check_only
+class _SupportsDunderGE(Protocol[_T_contra]):
+    def __ge__(self, other: _T_contra, /) -> object: ...
+
+# Some projects use _SupportsComparison without a type argument.
+_OperandT = TypeVar("_OperandT", default=Any)
+_SupportsComparison: TypeAlias = (
+    _SupportsDunderLT[_OperandT] | _SupportsDunderGT[_OperandT] | _SupportsDunderLE[_OperandT] | _SupportsDunderGE[_OperandT]
+)
+
+# _T is the argument type accepted by the other operand's ordering method.
+# _SupportsComparison[Any] preserves the rule that any two operands with
+# ordering methods are accepted. For example, if x.__lt__ has separate int and
+# str overloads and y is int | str, neither overload accepts the whole union.
+# The fallback accepts lt(x, y) because int and str each define an ordering method.
+_ComparisonOperand: TypeAlias = _T | _SupportsComparison[Any]
 
 @type_check_only
 class _SupportsInversion(Protocol[_T_co]):
@@ -178,13 +202,33 @@ class _SupportsIConcat(Protocol[_T_contra, _T_co]):
     def __iadd__(self, value: _T_contra, /) -> _T_co: ...
     def __getitem__(self, key: Any) -> Any: ...  # method needs only exist
 
-# All four comparison functions must have the same signature, or we get false-positive errors
-def lt(a: _SupportsComparison, b: _SupportsComparison, /) -> Any: ...
-def le(a: _SupportsComparison, b: _SupportsComparison, /) -> Any: ...
-def eq(a: object, b: object, /) -> Any: ...
-def ne(a: object, b: object, /) -> Any: ...
-def ge(a: _SupportsComparison, b: _SupportsComparison, /) -> Any: ...
-def gt(a: _SupportsComparison, b: _SupportsComparison, /) -> Any: ...
+# Either operand can implement the comparison. Dispatch tables rely on all four
+# ordering functions having the same signatures (#6462).
+@overload
+def lt(a: _SupportsComparison[_T], b: _ComparisonOperand[_T], /) -> Any: ...
+@overload
+def lt(a: _ComparisonOperand[_T], b: _SupportsComparison[_T], /) -> Any: ...
+
+@overload
+def le(a: _SupportsComparison[_T], b: _ComparisonOperand[_T], /) -> Any: ...
+@overload
+def le(a: _ComparisonOperand[_T], b: _SupportsComparison[_T], /) -> Any: ...
+
+# Equality accepts any operands. Using Any also lets mypy infer a callable
+# for a dispatch table containing both equality and ordering functions.
+def eq(a: Any, b: Any, /) -> Any: ...
+def ne(a: Any, b: Any, /) -> Any: ...
+
+@overload
+def ge(a: _SupportsComparison[_T], b: _ComparisonOperand[_T], /) -> Any: ...
+@overload
+def ge(a: _ComparisonOperand[_T], b: _SupportsComparison[_T], /) -> Any: ...
+
+@overload
+def gt(a: _SupportsComparison[_T], b: _ComparisonOperand[_T], /) -> Any: ...
+@overload
+def gt(a: _ComparisonOperand[_T], b: _SupportsComparison[_T], /) -> Any: ...
+
 def not_(a: SupportsBool, /) -> bool: ...
 def truth(a: SupportsBool, /) -> bool: ...
 def is_(a: object, b: object, /) -> bool: ...