Add type annotations to assertions, compat, run, and other modules

Remove testtools.assertions, testtools.compat, testtools.run,
testtools.matchers.*, testtools.monkey, and testtools.runtest
from mypy strict override list as they now have full type annotations.

Author: jelmer

pyproject.toml

@@ -79,12 +79,6 @@ ignore_missing_imports = true
 module = [
     # FIXME(stephenfin): We would like to remove all modules from this list
     # except tests (we're not sadists)
-    "testtools.assertions",
-    "testtools.compat",
-    "testtools.matchers.*",
-    "testtools.monkey",
-    "testtools.run",
-    "testtools.runtest",
     "testtools.twistedsupport.*",
     "tests.*",
 ]

testtools/assertions.py

@@ -2,13 +2,20 @@
 
 """Assertion helpers."""
 
+from typing import TypeVar
+
 from testtools.matchers import (
     Annotate,
+    Matcher,
     MismatchError,
 )
 
+T = TypeVar("T")
+
 
-def assert_that(matchee, matcher, message="", verbose=False):
+def assert_that(
+    matchee: T, matcher: Matcher[T], message: str = "", verbose: bool = False
+) -> None:
     """Assert that matchee is matched by matcher.
 
     This should only be used when you need to use a function based

testtools/compat.py

@@ -14,9 +14,10 @@
 import sys
 import unicodedata
 from io import BytesIO, StringIO  # for backwards-compat
+from typing import IO
 
 
-def _slow_escape(text):
+def _slow_escape(text: str) -> str:
     """Escape unicode ``text`` leaving printable characters unmodified
 
     The behaviour emulates the Python 3 implementation of repr, see
@@ -26,7 +27,7 @@ def _slow_escape(text):
     does not handle astral characters correctly on Python builds with 16 bit
     rather than 32 bit unicode type.
     """
-    output = []
+    output: list[str | bytes] = []
     for c in text:
         o = ord(c)
         if o < 256:
@@ -43,14 +44,14 @@ def _slow_escape(text):
                 output.append(c.encode("unicode-escape"))
             else:
                 output.append(c)
-    return "".join(output)
+    return "".join(output)  # type: ignore[arg-type]
 
 
-def text_repr(text, multiline=None):
+def text_repr(text: str | bytes, multiline: bool | None = None) -> str:
     """Rich repr for ``text`` returning unicode, triple quoted if ``multiline``."""
     nl = (isinstance(text, bytes) and bytes((0xA,))) or "\n"
     if multiline is None:
-        multiline = nl in text
+        multiline = nl in text  # type: ignore[operator]
     if not multiline:
         # Use normal repr for single line of unicode
         return repr(text)
@@ -60,7 +61,7 @@ def text_repr(text, multiline=None):
         # making sure that quotes are not escaped.
         offset = len(prefix) + 1
         lines = []
-        for line in text.split(nl):
+        for line in text.split(nl):  # type: ignore[arg-type]
             r = repr(line)
             q = r[-1]
             lines.append(r[offset:-1].replace("\\" + q, q))
@@ -87,7 +88,7 @@ def text_repr(text, multiline=None):
     return "".join([prefix, quote, escaped_text, quote])
 
 
-def unicode_output_stream(stream):
+def unicode_output_stream(stream: IO[str]) -> IO[str]:
     """Get wrapper for given stream that writes any unicode without exception
 
     Characters that can't be coerced to the encoding of the stream, or 'ascii'
@@ -103,21 +104,21 @@ def unicode_output_stream(stream):
         # attribute).
         return stream
     try:
-        writer = codecs.getwriter(stream.encoding or "")
+        writer = codecs.getwriter(stream.encoding or "")  # type: ignore[attr-defined]
     except (AttributeError, LookupError):
-        return codecs.getwriter("ascii")(stream, "replace")
+        return codecs.getwriter("ascii")(stream, "replace")  # type: ignore[arg-type, return-value]
     if writer.__module__.rsplit(".", 1)[1].startswith("utf"):
         # The current stream has a unicode encoding so no error handler is needed
         return stream
     # Python 3 doesn't seem to make this easy, handle a common case
     try:
-        return stream.__class__(
-            stream.buffer,
-            stream.encoding,
+        return stream.__class__(  # type: ignore[call-arg, return-value]
+            stream.buffer,  # type: ignore[attr-defined]
+            stream.encoding,  # type: ignore[attr-defined]
             "replace",
-            stream.newlines,
-            stream.line_buffering,
+            stream.newlines,  # type: ignore[attr-defined]
+            stream.line_buffering,  # type: ignore[attr-defined]
         )
     except AttributeError:
         pass
-    return writer(stream, "replace")
+    return writer(stream, "replace")  # type: ignore[arg-type, return-value]

testtools/matchers/_basic.py

@@ -135,7 +135,7 @@ def _describe_set_difference(self) -> str:
         return "\n".join(lines)
 
 
-class Equals(_BinaryComparison):
+class Equals(_BinaryComparison[T]):
     """Matches if the items are equal."""
 
     comparator = operator.eq
@@ -165,7 +165,7 @@ def match(self, other: T) -> Mismatch | None:
         return _BinaryMismatch(other, "!=", self._expected, False)
 
 
-class NotEquals(_BinaryComparison):
+class NotEquals(_BinaryComparison[T]):
     """Matches if the items are not equal.
 
     In most cases, this is equivalent to ``Not(Equals(foo))``. The difference
@@ -176,38 +176,38 @@ class NotEquals(_BinaryComparison):
     mismatch_string = "=="
 
 
-class Is(_BinaryComparison):
+class Is(_BinaryComparison[T]):
     """Matches if the items are identical."""
 
     comparator = operator.is_
     mismatch_string = "is not"
 
 
-class LessThan(_BinaryComparison):
+class LessThan(_BinaryComparison[T]):
     """Matches if the item is less than the matchers reference object."""
 
     comparator = operator.lt
     mismatch_string = ">="
 
 
-class GreaterThan(_BinaryComparison):
+class GreaterThan(_BinaryComparison[T]):
     """Matches if the item is greater than the matchers reference object."""
 
     comparator = operator.gt
     mismatch_string = "<="
 
 
-class _NotNearlyEqual(Mismatch):
+class _NotNearlyEqual(Mismatch, Generic[T]):
     """Mismatch for Nearly matcher."""
 
-    def __init__(self, actual, expected, delta):
+    def __init__(self, actual: T, expected: T, delta: Any) -> None:
         self.actual = actual
         self.expected = expected
         self.delta = delta
 
-    def describe(self):
+    def describe(self) -> str:
         try:
-            diff = abs(self.actual - self.expected)
+            diff = abs(self.actual - self.expected)  # type: ignore[operator]
             return (
                 f"{self.actual!r} is not nearly equal to {self.expected!r}: "
                 f"difference {diff!r} exceeds tolerance {self.delta!r}"
@@ -219,7 +219,7 @@ def describe(self):
             )
 
 
-class Nearly(Matcher):
+class Nearly(Matcher[T]):
     """Matches if a value is nearly equal to the expected value.
 
     This matcher is useful for comparing floating point values where exact
@@ -232,7 +232,7 @@ class Nearly(Matcher):
     operations (e.g., integers, floats, Decimal, etc.).
     """
 
-    def __init__(self, expected, delta=0.001):
+    def __init__(self, expected: T, delta: Any = 0.001) -> None:
         """Create a Nearly matcher.
 
         :param expected: The expected value to compare against.
@@ -242,12 +242,12 @@ def __init__(self, expected, delta=0.001):
         self.expected = expected
         self.delta = delta
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"Nearly({self.expected!r}, delta={self.delta!r})"
 
-    def match(self, actual):
+    def match(self, actual: T) -> Mismatch | None:
         try:
-            diff = abs(actual - self.expected)
+            diff = abs(actual - self.expected)  # type: ignore[operator]
             if diff <= self.delta:
                 return None
         except (TypeError, AttributeError):
@@ -256,25 +256,25 @@ def match(self, actual):
         return _NotNearlyEqual(actual, self.expected, self.delta)
 
 
-class SameMembers(Matcher):
+class SameMembers(Matcher[list[T]]):
     """Matches if two iterators have the same members.
 
     This is not the same as set equivalence.  The two iterators must be of the
     same length and have the same repetitions.
     """
 
-    def __init__(self, expected):
+    def __init__(self, expected: list[T]) -> None:
         super().__init__()
         self.expected = expected
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.__class__.__name__}({self.expected!r})"
 
-    def match(self, observed):
+    def match(self, observed: list[T]) -> Mismatch | None:
         expected_only = list_subtract(self.expected, observed)
         observed_only = list_subtract(observed, self.expected)
         if expected_only == observed_only == []:
-            return
+            return None
         return PostfixedMismatch(
             (
                 f"\nmissing:    {_format(expected_only)}\n"
@@ -285,7 +285,7 @@ def match(self, observed):
 
 
 class DoesNotStartWith(Mismatch):
-    def __init__(self, matchee, expected):
+    def __init__(self, matchee: str | bytes, expected: str | bytes) -> None:
         """Create a DoesNotStartWith Mismatch.
 
         :param matchee: the string that did not match.
@@ -294,33 +294,33 @@ def __init__(self, matchee, expected):
         self.matchee = matchee
         self.expected = expected
 
-    def describe(self):
+    def describe(self) -> str:
         return (
             f"{text_repr(self.matchee)} does not start with {text_repr(self.expected)}."
         )
 
 
-class StartsWith(Matcher):
+class StartsWith(Matcher[str | bytes]):
     """Checks whether one string starts with another."""
 
-    def __init__(self, expected):
+    def __init__(self, expected: str | bytes) -> None:
         """Create a StartsWith Matcher.
 
         :param expected: the string that matchees should start with.
         """
         self.expected = expected
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"StartsWith({self.expected!r})"
 
-    def match(self, matchee):
-        if not matchee.startswith(self.expected):
+    def match(self, matchee: str | bytes) -> Mismatch | None:
+        if not matchee.startswith(self.expected):  # type: ignore[arg-type]
             return DoesNotStartWith(matchee, self.expected)
         return None
 
 
 class DoesNotEndWith(Mismatch):
-    def __init__(self, matchee, expected):
+    def __init__(self, matchee: str | bytes, expected: str | bytes) -> None:
         """Create a DoesNotEndWith Mismatch.
 
         :param matchee: the string that did not match.
@@ -329,27 +329,27 @@ def __init__(self, matchee, expected):
         self.matchee = matchee
         self.expected = expected
 
-    def describe(self):
+    def describe(self) -> str:
         return (
             f"{text_repr(self.matchee)} does not end with {text_repr(self.expected)}."
         )
 
 
-class EndsWith(Matcher):
+class EndsWith(Matcher[str | bytes]):
     """Checks whether one string ends with another."""
 
-    def __init__(self, expected):
+    def __init__(self, expected: str | bytes) -> None:
         """Create a EndsWith Matcher.
 
         :param expected: the string that matchees should end with.
         """
         self.expected = expected
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"EndsWith({self.expected!r})"
 
-    def match(self, matchee):
-        if not matchee.endswith(self.expected):
+    def match(self, matchee: str | bytes) -> Mismatch | None:
+        if not matchee.endswith(self.expected):  # type: ignore[arg-type]
             return DoesNotEndWith(matchee, self.expected)
         return None
 
@@ -459,7 +459,7 @@ def match(self, value: str) -> Mismatch | None:
         return None
 
 
-def has_len(x, y):
+def has_len(x: Any, y: int) -> bool:
     return len(x) == y
 
 

testtools/matchers/_const.py

@@ -5,20 +5,21 @@
     "Never",
 ]
 
-from ._impl import Mismatch
 
+from ._impl import Matcher, Mismatch
 
-class _Always:
+
+class _Always(Matcher[object]):
     """Always matches."""
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "Always()"
 
-    def match(self, value):
+    def match(self, value: object) -> None:
         return None
 
 
-def Always():
+def Always() -> _Always:
     """Always match.
 
     That is::
@@ -32,17 +33,17 @@ def Always():
     return _Always()
 
 
-class _Never:
+class _Never(Matcher[object]):
     """Never matches."""
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "Never()"
 
-    def match(self, value):
+    def match(self, value: object) -> Mismatch:
         return Mismatch(f"Inevitable mismatch on {value!r}")
 
 
-def Never():
+def Never() -> _Never:
     """Never match.
 
     That is::