unittest.case: tighter annotations for various assertions (#8077)

stdlib/unittest/case.pyi

@@ -1,7 +1,7 @@
 import logging
 import sys
 import unittest.result
-from _typeshed import Self, SupportsDunderGE, SupportsSub
+from _typeshed import Self, SupportsDunderGE, SupportsDunderGT, SupportsDunderLE, SupportsDunderLT, SupportsSub
 from collections.abc import Callable, Container, Iterable, Mapping, Sequence, Set as AbstractSet
 from contextlib import AbstractContextManager
 from types import TracebackType
@@ -17,14 +17,18 @@ from typing import (
     SupportsAbs,
     SupportsRound,
     TypeVar,
+    Union,
     overload,
 )
-from typing_extensions import ParamSpec
+from typing_extensions import ParamSpec, TypeAlias
 from warnings import WarningMessage
 
 if sys.version_info >= (3, 9):
     from types import GenericAlias
 
+if sys.version_info >= (3, 10):
+    from types import UnionType
+
 _T = TypeVar("_T")
 _S = TypeVar("_S", bound=SupportsSub[Any, Any])
 _E = TypeVar("_E", bound=BaseException)
@@ -75,7 +79,12 @@ def skipUnless(condition: object, reason: str) -> Callable[[_FT], _FT]: ...
 class SkipTest(Exception):
     def __init__(self, reason: str) -> None: ...
 
-class _SupportsAbsAndDunderGE(SupportsDunderGE, SupportsAbs[Any], Protocol): ...
+class _SupportsAbsAndDunderGE(SupportsDunderGE[Any], SupportsAbs[Any], Protocol): ...
+
+if sys.version_info >= (3, 10):
+    _IsInstanceClassInfo: TypeAlias = Union[type, UnionType, tuple[type | UnionType | tuple[Any, ...], ...]]
+else:
+    _IsInstanceClassInfo: TypeAlias = Union[type, tuple[type | tuple[Any, ...], ...]]
 
 class TestCase:
     failureException: type[BaseException]
@@ -105,18 +114,30 @@ class TestCase:
     def assertNotEqual(self, first: Any, second: Any, msg: Any = ...) -> None: ...
     def assertTrue(self, expr: Any, msg: Any = ...) -> None: ...
     def assertFalse(self, expr: Any, msg: Any = ...) -> None: ...
-    def assertIs(self, expr1: Any, expr2: Any, msg: Any = ...) -> None: ...
-    def assertIsNot(self, expr1: Any, expr2: Any, msg: Any = ...) -> None: ...
-    def assertIsNone(self, obj: Any, msg: Any = ...) -> None: ...
-    def assertIsNotNone(self, obj: Any, msg: Any = ...) -> None: ...
+    def assertIs(self, expr1: object, expr2: object, msg: Any = ...) -> None: ...
+    def assertIsNot(self, expr1: object, expr2: object, msg: Any = ...) -> None: ...
+    def assertIsNone(self, obj: object, msg: Any = ...) -> None: ...
+    def assertIsNotNone(self, obj: object, msg: Any = ...) -> None: ...
     def assertIn(self, member: Any, container: Iterable[Any] | Container[Any], msg: Any = ...) -> None: ...
     def assertNotIn(self, member: Any, container: Iterable[Any] | Container[Any], msg: Any = ...) -> None: ...
-    def assertIsInstance(self, obj: Any, cls: type | tuple[type, ...], msg: Any = ...) -> None: ...
-    def assertNotIsInstance(self, obj: Any, cls: type | tuple[type, ...], msg: Any = ...) -> None: ...
-    def assertGreater(self, a: Any, b: Any, msg: Any = ...) -> None: ...
-    def assertGreaterEqual(self, a: Any, b: Any, msg: Any = ...) -> None: ...
-    def assertLess(self, a: Any, b: Any, msg: Any = ...) -> None: ...
-    def assertLessEqual(self, a: Any, b: Any, msg: Any = ...) -> None: ...
+    def assertIsInstance(self, obj: object, cls: _IsInstanceClassInfo, msg: Any = ...) -> None: ...
+    def assertNotIsInstance(self, obj: object, cls: _IsInstanceClassInfo, msg: Any = ...) -> None: ...
+    @overload
+    def assertGreater(self, a: SupportsDunderGT[_T], b: _T, msg: Any = ...) -> None: ...
+    @overload
+    def assertGreater(self, a: _T, b: SupportsDunderLT[_T], msg: Any = ...) -> None: ...
+    @overload
+    def assertGreaterEqual(self, a: SupportsDunderGE[_T], b: _T, msg: Any = ...) -> None: ...
+    @overload
+    def assertGreaterEqual(self, a: _T, b: SupportsDunderLE[_T], msg: Any = ...) -> None: ...
+    @overload
+    def assertLess(self, a: SupportsDunderLT[_T], b: _T, msg: Any = ...) -> None: ...
+    @overload
+    def assertLess(self, a: _T, b: SupportsDunderGT[_T], msg: Any = ...) -> None: ...
+    @overload
+    def assertLessEqual(self, a: SupportsDunderLT[_T], b: _T, msg: Any = ...) -> None: ...
+    @overload
+    def assertLessEqual(self, a: _T, b: SupportsDunderGT[_T], msg: Any = ...) -> None: ...
     # `assertRaises`, `assertRaisesRegex`, and `assertRaisesRegexp`
     # are not using `ParamSpec` intentionally,
     # because they might be used with explicitly wrong arg types to raise some error in tests.
@@ -249,45 +270,21 @@ class TestCase:
     def _formatMessage(self, msg: str | None, standardMsg: str) -> str: ...  # undocumented
     def _getAssertEqualityFunc(self, first: Any, second: Any) -> Callable[..., None]: ...  # undocumented
     if sys.version_info < (3, 12):
-        def failUnlessEqual(self, first: Any, second: Any, msg: Any = ...) -> None: ...
-        def assertEquals(self, first: Any, second: Any, msg: Any = ...) -> None: ...
-        def failIfEqual(self, first: Any, second: Any, msg: Any = ...) -> None: ...
-        def assertNotEquals(self, first: Any, second: Any, msg: Any = ...) -> None: ...
-        def failUnless(self, expr: bool, msg: Any = ...) -> None: ...
-        def assert_(self, expr: bool, msg: Any = ...) -> None: ...
-        def failIf(self, expr: bool, msg: Any = ...) -> None: ...
-        @overload
-        def failUnlessRaises(  # type: ignore[misc]
-            self,
-            exception: type[BaseException] | tuple[type[BaseException], ...],
-            callable: Callable[_P, object] = ...,
-            *args: _P.args,
-            **kwargs: _P.kwargs,
-        ) -> None: ...
-        @overload
-        def failUnlessRaises(self, exception: type[_E] | tuple[type[_E], ...], msg: Any = ...) -> _AssertRaisesContext[_E]: ...
+        failUnlessEqual = assertEqual
+        assertEquals = assertEqual
+        failIfEqual = assertNotEqual
+        assertNotEquals = assertNotEqual
+        failUnless = assertTrue
+        assert_ = assertTrue
+        failIf = assertFalse
+        failUnlessRaises = assertRaises
         failUnlessAlmostEqual = assertAlmostEqual
         assertAlmostEquals = assertAlmostEqual
         failIfAlmostEqual = assertNotAlmostEqual
         assertNotAlmostEquals = assertNotAlmostEqual
-        def assertRegexpMatches(self, text: AnyStr, regex: AnyStr | Pattern[AnyStr], msg: Any = ...) -> None: ...
-        def assertNotRegexpMatches(self, text: AnyStr, regex: AnyStr | Pattern[AnyStr], msg: Any = ...) -> None: ...
-        @overload
-        def assertRaisesRegexp(  # type: ignore[misc]
-            self,
-            exception: type[BaseException] | tuple[type[BaseException], ...],
-            expected_regex: str | bytes | Pattern[str] | Pattern[bytes],
-            callable: Callable[..., object],
-            *args: Any,
-            **kwargs: Any,
-        ) -> None: ...
-        @overload
-        def assertRaisesRegexp(
-            self,
-            exception: type[_E] | tuple[type[_E], ...],
-            expected_regex: str | bytes | Pattern[str] | Pattern[bytes],
-            msg: Any = ...,
-        ) -> _AssertRaisesContext[_E]: ...
+        assertRegexpMatches = assertRegex
+        assertNotRegexpMatches = assertNotRegex
+        assertRaisesRegexp = assertRaisesRegex
         def assertDictContainsSubset(
             self, subset: Mapping[Any, Any], dictionary: Mapping[Any, Any], msg: object = ...
         ) -> None: ...