Improve more typing

Author: jelmer

pyproject.toml

@@ -85,8 +85,6 @@ module = [
     "testtools.monkey",
     "testtools.run",
     "testtools.runtest",
-    "testtools.testcase",
-    "testtools.testresult.*",
     "testtools.twistedsupport.*",
     "tests.*",
 ]

tests/matchers/helpers.py

@@ -21,6 +21,8 @@ class MatcherTestProtocol(Protocol):
 class TestMatchersInterface:
     """Mixin class that provides test methods for matcher interfaces."""
 
+    __test__ = False  # Tell pytest not to collect this as a test class
+
     def test_matches_match(self: MatcherTestProtocol) -> None:
         matcher = self.matches_matcher
         matches = self.matches_matches

tests/test_testresult.py

@@ -146,6 +146,8 @@ def make_exception_info(exceptionFactory, *args, **kwargs):
 class TestControlContract:
     """Stopping test runs."""
 
+    __test__ = False  # Tell pytest not to collect this as a test class
+
     # These are provided by the class that uses this mixin
     makeResult: Any
     assertFalse: Any
@@ -573,6 +575,8 @@ def makeResult(self):
 
 
 class TestStreamResultContract:
+    __test__ = False  # Tell pytest not to collect this as a test class
+
     # These are provided by the class that uses this mixin
     addCleanup: Any
 

testtools/content.py

@@ -197,7 +197,8 @@ class TracebackContent(Content):
 
     def __init__(
         self,
-        err: tuple[type[BaseException], BaseException, types.TracebackType | None],
+        err: tuple[type[BaseException], BaseException, types.TracebackType | None]
+        | tuple[None, None, None],
         test: _TestCase | None,
         capture_locals: bool = False,
     ) -> None:
@@ -211,6 +212,9 @@ def __init__(
             raise ValueError("err may not be None")
 
         exctype, value, tb = err
+        # Ensure we have a real exception, not the (None, None, None) variant
+        assert exctype is not None, "exctype must not be None"
+        assert value is not None, "value must not be None"
         # Skip test runner traceback levels
         if StackLinesContent.HIDE_INTERNAL_STACK:
             while tb and "__unittest" in tb.tb_frame.f_globals:

testtools/matchers/_basic.py

@@ -20,7 +20,7 @@
 import re
 from collections.abc import Callable
 from pprint import pformat
-from typing import Any
+from typing import Any, Generic, TypeVar
 
 from ..compat import (
     text_repr,
@@ -35,52 +35,64 @@
     Mismatch,
 )
 
+T = TypeVar("T")
+U = TypeVar("U")
 
-def _format(thing):
+
+def _format(thing: object) -> str:
     """Blocks of text with newlines are formatted as triple-quote
     strings. Everything else is pretty-printed.
     """
     if isinstance(thing, (str, bytes)):
-        return text_repr(thing)
-    return pformat(thing)
+        result: str = text_repr(thing)
+        return result
+    pformat_result: str = pformat(thing)
+    return pformat_result
 
 
-class _BinaryComparison:
+class _BinaryComparison(Matcher[T]):
     """Matcher that compares an object to another object."""
 
     mismatch_string: str
     # comparator is defined by subclasses - using Any to allow different signatures
     comparator: Callable[..., Any]
 
-    def __init__(self, expected):
+    def __init__(self, expected: T) -> None:
         self.expected = expected
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.__class__.__name__}({self.expected!r})"
 
-    def match(self, other):
+    def match(self, other: T) -> Mismatch | None:
         if self.comparator(other, self.expected):
             return None
         return _BinaryMismatch(other, self.mismatch_string, self.expected)
 
 
-class _BinaryMismatch(Mismatch):
+class _BinaryMismatch(Mismatch, Generic[T]):
     """Two things did not match."""
 
-    def __init__(self, actual, mismatch_string, reference, reference_on_right=True):
+    def __init__(
+        self,
+        actual: T,
+        mismatch_string: str,
+        reference: T,
+        reference_on_right: bool = True,
+    ) -> None:
         self._actual = actual
         self._mismatch_string = mismatch_string
         self._reference = reference
         self._reference_on_right = reference_on_right
 
-    def describe(self):
+    def describe(self) -> str:
         # Special handling for set comparisons
         if (
             self._mismatch_string == "!="
             and isinstance(self._reference, set)
             and isinstance(self._actual, set)
         ):
-            return self._describe_set_difference()
+            result: str = self._describe_set_difference()
+            return result
 
         actual = repr(self._actual)
         reference = repr(self._reference)
@@ -97,8 +109,12 @@ def describe(self):
                 left, right = reference, actual
             return f"{left} {self._mismatch_string} {right}"
 
-    def _describe_set_difference(self):
+    def _describe_set_difference(self) -> str:
         """Describe the difference between two sets in a readable format."""
+        # Type narrowing: we know these are sets from the isinstance check in describe()
+        assert isinstance(self._reference, set)
+        assert isinstance(self._actual, set)
+
         reference_only = sorted(
             self._reference - self._actual, key=lambda x: (type(x).__name__, x)
         )
@@ -126,7 +142,7 @@ class Equals(_BinaryComparison):
     mismatch_string = "!="
 
 
-class _FlippedEquals:
+class _FlippedEquals(Matcher[T]):
     """Matches if the items are equal.
 
     Exactly like ``Equals`` except that the short mismatch message is "
@@ -136,10 +152,13 @@ class _FlippedEquals:
     the assertion.
     """
 
-    def __init__(self, expected):
+    def __init__(self, expected: T) -> None:
         self._expected = expected
 
-    def match(self, other):
+    def __str__(self) -> str:
+        return f"_FlippedEquals({self._expected!r})"
+
+    def match(self, other: T) -> Mismatch | None:
         mismatch = Equals(self._expected).match(other)
         if not mismatch:
             return None
@@ -335,25 +354,25 @@ def match(self, matchee):
         return None
 
 
-class IsInstance:
+class IsInstance(Matcher[T]):
     """Matcher that wraps isinstance."""
 
-    def __init__(self, *types):
+    def __init__(self, *types: type[T]) -> None:
         self.types = tuple(types)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "{}({})".format(
             self.__class__.__name__, ", ".join(type.__name__ for type in self.types)
         )
 
-    def match(self, other):
+    def match(self, other: T) -> Mismatch | None:
         if isinstance(other, self.types):
             return None
         return NotAnInstance(other, self.types)
 
 
-class NotAnInstance(Mismatch):
-    def __init__(self, matchee, types):
+class NotAnInstance(Mismatch, Generic[T]):
+    def __init__(self, matchee: T, types: tuple[type[T], ...]) -> None:
         """Create a NotAnInstance Mismatch.
 
         :param matchee: the thing which is not an instance of any of types.
@@ -362,7 +381,7 @@ def __init__(self, matchee, types):
         self.matchee = matchee
         self.types = types
 
-    def describe(self):
+    def describe(self) -> str:
         if len(self.types) == 1:
             typestr = self.types[0].__name__
         else:
@@ -372,8 +391,8 @@ def describe(self):
         return f"'{self.matchee}' is not an instance of {typestr}"
 
 
-class DoesNotContain(Mismatch):
-    def __init__(self, matchee, needle):
+class DoesNotContain(Mismatch, Generic[T, U]):
+    def __init__(self, matchee: T, needle: U) -> None:
         """Create a DoesNotContain Mismatch.
 
         :param matchee: the object that did not contain needle.
@@ -382,41 +401,41 @@ def __init__(self, matchee, needle):
         self.matchee = matchee
         self.needle = needle
 
-    def describe(self):
+    def describe(self) -> str:
         return f"{self.needle!r} not in {self.matchee!r}"
 
 
-class Contains(Matcher):
+class Contains(Matcher[T], Generic[T, U]):
     """Checks whether something is contained in another thing."""
 
-    def __init__(self, needle):
+    def __init__(self, needle: U) -> None:
         """Create a Contains Matcher.
 
         :param needle: the thing that needs to be contained by matchees.
         """
         self.needle = needle
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"Contains({self.needle!r})"
 
-    def match(self, matchee):
+    def match(self, matchee: T) -> Mismatch | None:
         try:
-            if self.needle not in matchee:
+            if self.needle not in matchee:  # type: ignore[operator]
                 return DoesNotContain(matchee, self.needle)
         except TypeError:
             # e.g. 1 in 2 will raise TypeError
             return DoesNotContain(matchee, self.needle)
         return None
 
 
-class MatchesRegex:
+class MatchesRegex(Matcher[str]):
     """Matches if the matchee is matched by a regular expression."""
 
-    def __init__(self, pattern, flags=0):
+    def __init__(self, pattern: str | bytes, flags: int = 0) -> None:
         self.pattern = pattern
         self.flags = flags
 
-    def __str__(self):
+    def __str__(self) -> str:
         args = [f"{self.pattern!r}"]
         flag_arg = []
         # dir() sorts the attributes for us, so we don't need to do it again.
@@ -428,15 +447,16 @@ def __str__(self):
             args.append("|".join(flag_arg))
         return "{}({})".format(self.__class__.__name__, ", ".join(args))
 
-    def match(self, value):
-        if not re.match(self.pattern, value, self.flags):
+    def match(self, value: str) -> Mismatch | None:
+        if not re.match(self.pattern, value, self.flags):  # type: ignore[arg-type]
             pattern = self.pattern
             if not isinstance(pattern, str):
                 pattern = pattern.decode("latin1")
             pattern = pattern.encode("unicode_escape").decode("ascii")
             return Mismatch(
                 "{!r} does not match /{}/".format(value, pattern.replace("\\\\", "\\"))
             )
+        return None
 
 
 def has_len(x, y):

testtools/matchers/_datastructures.py

@@ -2,13 +2,18 @@
 
 """Matchers that operate with knowledge of Python data structures."""
 
+from collections.abc import Sequence
+from typing import Generic, TypeVar
+
 from ..helpers import map_values
 from ._higherorder import (
     Annotate,
     MatchesAll,
     MismatchesAll,
 )
-from ._impl import Mismatch
+from ._impl import Matcher, Mismatch
+
+T = TypeVar("T")
 
 __all__ = [
     "ContainsAll",
@@ -30,7 +35,7 @@ def ContainsAll(items):
     return MatchesAll(*map(Contains, items), first_only=False)
 
 
-class MatchesListwise:
+class MatchesListwise(Matcher["Sequence[T]"], Generic[T]):
     """Matches if each matcher matches the corresponding value.
 
     More easily explained by example than in words:
@@ -48,7 +53,9 @@ class MatchesListwise:
     3 != 1
     """
 
-    def __init__(self, matchers, first_only=False):
+    def __init__(
+        self, matchers: "Sequence[Matcher[T]]", first_only: bool = False
+    ) -> None:
         """Construct a MatchesListwise matcher.
 
         :param matchers: A list of matcher that the matched values must match.
@@ -58,7 +65,7 @@ def __init__(self, matchers, first_only=False):
         self.matchers = matchers
         self.first_only = first_only
 
-    def match(self, values):
+    def match(self, values: "Sequence[T]") -> Mismatch | None:
         from ._basic import HasLength
 
         mismatches = []
@@ -75,6 +82,7 @@ def match(self, values):
                 mismatches.append(mismatch)
         if mismatches:
             return MismatchesAll(mismatches)
+        return None
 
 
 class MatchesStructure: