[unittest] Improve annotations of three_way_cmp (#15003)

Author: donbarbos

stdlib/unittest/util.pyi

@@ -1,9 +1,26 @@
 from collections.abc import MutableSequence, Sequence
-from typing import Any, Final, TypeVar
+from typing import Any, Final, Literal, Protocol, TypeVar, type_check_only
 from typing_extensions import TypeAlias
 
+@type_check_only
+class _SupportsDunderLT(Protocol):
+    def __lt__(self, other: Any, /) -> bool: ...
+
+@type_check_only
+class _SupportsDunderGT(Protocol):
+    def __gt__(self, other: Any, /) -> bool: ...
+
+@type_check_only
+class _SupportsDunderLE(Protocol):
+    def __le__(self, other: Any, /) -> bool: ...
+
+@type_check_only
+class _SupportsDunderGE(Protocol):
+    def __ge__(self, other: Any, /) -> bool: ...
+
 _T = TypeVar("_T")
 _Mismatch: TypeAlias = tuple[_T, _T, int]
+_SupportsComparison: TypeAlias = _SupportsDunderLE | _SupportsDunderGE | _SupportsDunderGT | _SupportsDunderLT
 
 _MAX_LENGTH: Final = 80
 _PLACEHOLDER_LEN: Final = 12
@@ -18,6 +35,6 @@ def safe_repr(obj: object, short: bool = False) -> str: ...
 def strclass(cls: type) -> str: ...
 def sorted_list_difference(expected: Sequence[_T], actual: Sequence[_T]) -> tuple[list[_T], list[_T]]: ...
 def unorderable_list_difference(expected: MutableSequence[_T], actual: MutableSequence[_T]) -> tuple[list[_T], list[_T]]: ...
-def three_way_cmp(x: Any, y: Any) -> int: ...
+def three_way_cmp(x: _SupportsComparison, y: _SupportsComparison) -> Literal[-1, 0, 1]: ...
 def _count_diff_all_purpose(actual: Sequence[_T], expected: Sequence[_T]) -> list[_Mismatch[_T]]: ...
 def _count_diff_hashable(actual: Sequence[_T], expected: Sequence[_T]) -> list[_Mismatch[_T]]: ...