Add typing

.github/workflows/test.yml

@@ -44,6 +44,10 @@ jobs:
         run: |
           python -m ruff format --check .
 
+      - name: Type Check
+        run: |
+          python -m mypy testtools
+
       - name: Tests
         run: |
           python -W once -m testtools.run testtools.tests.test_suite

.gitignore

@@ -24,3 +24,4 @@ ChangeLog
 testtools/_version.py
 man/testtools.1
 man
+.mypy_cache/

MANIFEST.in

@@ -4,4 +4,5 @@ include MANIFEST.in
 include NEWS
 include README.rst
 include .gitignore
+include testtools/py.typed
 prune doc/_build

pyproject.toml

@@ -34,7 +34,7 @@ Homepage = "https://github.com/testing-cabal/testtools"
 [project.optional-dependencies]
 test = ["testscenarios", "testresources"]
 twisted = ["Twisted", "fixtures"]
-dev = ["ruff==0.12.3"]
+dev = ["ruff==0.12.3", "mypy>=1.0.0"]
 
 [tool.hatch.version]
 source = "vcs"

testtools/__init__.py

@@ -41,12 +41,10 @@
     "skip",
     "skipIf",
     "skipUnless",
-    "try_import",
     "unique_text_generator",
     "version",
 ]
 
-from testtools.helpers import try_import
 from testtools.matchers._impl import Matcher  # noqa: F401
 from testtools.runtest import (
     MultipleExceptions,

testtools/_version.pyi

@@ -0,0 +1,5 @@
+# Type stub for auto-generated _version module
+from typing import Union
+
+__version__: tuple[Union[int, str], ...]  # noqa: UP007
+version: str

testtools/content.py

@@ -235,9 +235,9 @@ def filter_stack(stack):
 
 def json_content(json_data):
     """Create a JSON Content object from JSON-encodeable data."""
-    data = json.dumps(json_data)
+    json_str = json.dumps(json_data)
     # The json module perversely returns native str not bytes
-    data = data.encode("utf8")
+    data = json_str.encode("utf8")
     return Content(JSON, lambda: [data])
 
 

testtools/helpers.py

@@ -1,57 +1,14 @@
 # Copyright (c) 2010-2012 testtools developers. See LICENSE for details.
 
-import sys
+from typing import Any, Callable, TypeVar
 
+T = TypeVar("T")
+K = TypeVar("K")
+V = TypeVar("V")
+R = TypeVar("R")
 
-def try_import(name, alternative=None, error_callback=None):
-    """Attempt to import a module, with a fallback.
 
-    Attempt to import ``name``.  If it fails, return ``alternative``.  When
-    supporting multiple versions of Python or optional dependencies, it is
-    useful to be able to try to import a module.
-
-    :param name: The name of the object to import, e.g. ``os.path`` or
-        ``os.path.join``.
-    :param alternative: The value to return if no module can be imported.
-        Defaults to None.
-    :param error_callback: If non-None, a callable that is passed the
-        ImportError when the module cannot be loaded.
-    """
-    module_segments = name.split(".")
-    last_error = None
-    remainder = []
-
-    # module_name will be what successfully imports. We cannot walk from the
-    # __import__ result because in import loops (A imports A.B, which imports
-    # C, which calls try_import("A.B")) A.B will not yet be set.
-    while module_segments:
-        module_name = ".".join(module_segments)
-        try:
-            __import__(module_name)
-        except ImportError:
-            last_error = sys.exc_info()[1]
-            remainder.append(module_segments.pop())
-            continue
-        else:
-            break
-    else:
-        if last_error is not None and error_callback is not None:
-            error_callback(last_error)
-        return alternative
-
-    module = sys.modules[module_name]
-    nonexistent = object()
-    for segment in reversed(remainder):
-        module = getattr(module, segment, nonexistent)
-        if module is nonexistent:
-            if last_error is not None and error_callback is not None:
-                error_callback(last_error)
-            return alternative
-
-    return module
-
-
-def map_values(function, dictionary):
+def map_values(function: Callable[[V], R], dictionary: dict[K, V]) -> dict[K, R]:
     """Map ``function`` across the values of ``dictionary``.
 
     :return: A dict with the same keys as ``dictionary``, where the value
@@ -60,17 +17,17 @@ def map_values(function, dictionary):
     return {k: function(dictionary[k]) for k in dictionary}
 
 
-def filter_values(function, dictionary):
+def filter_values(function: Callable[[V], bool], dictionary: dict[K, V]) -> dict[K, V]:
     """Filter ``dictionary`` by its values using ``function``."""
     return {k: v for k, v in dictionary.items() if function(v)}
 
 
-def dict_subtract(a, b):
+def dict_subtract(a: dict[K, V], b: dict[K, Any]) -> dict[K, V]:
     """Return the part of ``a`` that's not in ``b``."""
     return {k: a[k] for k in set(a) - set(b)}
 
 
-def list_subtract(a, b):
+def list_subtract(a: list[T], b: list[T]) -> list[T]:
     """Return a list ``a`` without the elements of ``b``.
 
     If a particular value is in ``a`` twice and ``b`` once then the returned

testtools/matchers/_basic.py

@@ -18,6 +18,7 @@
 import operator
 import re
 from pprint import pformat
+from typing import Any, Callable
 
 from ..compat import (
     text_repr,
@@ -45,6 +46,10 @@ def _format(thing):
 class _BinaryComparison:
     """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):
         self.expected = expected
 
@@ -56,9 +61,6 @@ def match(self, other):
             return None
         return _BinaryMismatch(other, self.mismatch_string, self.expected)
 
-    def comparator(self, expected, other):
-        raise NotImplementedError(self.comparator)
-
 
 class _BinaryMismatch(Mismatch):
     """Two things did not match."""
@@ -134,14 +136,14 @@ class Is(_BinaryComparison):
 class LessThan(_BinaryComparison):
     """Matches if the item is less than the matchers reference object."""
 
-    comparator = operator.__lt__
+    comparator = operator.lt
     mismatch_string = ">="
 
 
 class GreaterThan(_BinaryComparison):
     """Matches if the item is greater than the matchers reference object."""
 
-    comparator = operator.__gt__
+    comparator = operator.gt
     mismatch_string = "<="
 
 

testtools/matchers/_datastructures.py

@@ -178,7 +178,7 @@ def match(self, observed):
             else:
                 not_matched.append(value)
         if not_matched or remaining_matchers:
-            remaining_matchers = list(remaining_matchers)
+            remaining_matchers_list = list(remaining_matchers)
             # There are various cases that all should be reported somewhat
             # differently.
 
@@ -192,39 +192,40 @@ def match(self, observed):
             # 5) There are more values left over than matchers.
 
             if len(not_matched) == 0:
-                if len(remaining_matchers) > 1:
-                    msg = f"There were {len(remaining_matchers)} matchers left over: "
+                if len(remaining_matchers_list) > 1:
+                    count = len(remaining_matchers_list)
+                    msg = f"There were {count} matchers left over: "
                 else:
                     msg = "There was 1 matcher left over: "
-                msg += ", ".join(map(str, remaining_matchers))
+                msg += ", ".join(map(str, remaining_matchers_list))
                 return Mismatch(msg)
-            elif len(remaining_matchers) == 0:
+            elif len(remaining_matchers_list) == 0:
                 if len(not_matched) > 1:
                     return Mismatch(
                         f"There were {len(not_matched)} values left over: {not_matched}"
                     )
                 else:
                     return Mismatch(f"There was 1 value left over: {not_matched}")
             else:
-                common_length = min(len(remaining_matchers), len(not_matched))
+                common_length = min(len(remaining_matchers_list), len(not_matched))
                 if common_length == 0:
                     raise AssertionError("common_length can't be 0 here")
                 if common_length > 1:
                     msg = f"There were {common_length} mismatches"
                 else:
                     msg = "There was 1 mismatch"
-                if len(remaining_matchers) > len(not_matched):
-                    extra_matchers = remaining_matchers[common_length:]
+                if len(remaining_matchers_list) > len(not_matched):
+                    extra_matchers = remaining_matchers_list[common_length:]
                     msg += f" and {len(extra_matchers)} extra matcher"
                     if len(extra_matchers) > 1:
                         msg += "s"
                     msg += ": " + ", ".join(map(str, extra_matchers))
-                elif len(not_matched) > len(remaining_matchers):
+                elif len(not_matched) > len(remaining_matchers_list):
                     extra_values = not_matched[common_length:]
                     msg += f" and {len(extra_values)} extra value"
                     if len(extra_values) > 1:
                         msg += "s"
                     msg += ": " + str(extra_values)
                 return Annotate(
-                    msg, MatchesListwise(remaining_matchers[:common_length])
+                    msg, MatchesListwise(remaining_matchers_list[:common_length])
                 ).match(not_matched[:common_length])

testtools/matchers/_doctest.py

@@ -39,8 +39,8 @@ def _toAscii(self, s):
     if getattr(doctest, "_encoding", None) is not None:
         from types import FunctionType as __F
 
-        __f = doctest.OutputChecker.output_difference.im_func
-        __g = dict(__f.func_globals)
+        __f = doctest.OutputChecker.output_difference.__func__  # type: ignore[attr-defined]
+        __g = dict(__f.__globals__)
 
         def _indent(s, indent=4, _pattern=re.compile("^(?!$)", re.MULTILINE)):
             """Prepend non-empty lines in ``s`` with ``indent`` number of spaces"""

testtools/matchers/_exception.py

@@ -96,6 +96,9 @@ def __init__(self, exception_matcher=None):
 
     def match(self, matchee):
         try:
+            # Handle staticmethod objects by extracting the underlying function
+            if isinstance(matchee, staticmethod):
+                matchee = matchee.__func__
             result = matchee()
             return Mismatch(f"{matchee!r} returned {result!r}")
         # Catch all exceptions: Raises() should be able to match a

testtools/matchers/_filesystem.py

@@ -130,7 +130,7 @@ def match(self, path):
             f.close()
 
     def __str__(self):
-        return f"File at path exists and contains {self.contents}"
+        return f"File at path exists and contains {self.matcher}"
 
 
 class HasPermissions(Matcher):

testtools/matchers/_higherorder.py

@@ -345,9 +345,9 @@ def __init__(self, predicate, message, name, *args, **kwargs):
         self.kwargs = kwargs
 
     def __str__(self):
-        args = [str(arg) for arg in self.args]
+        args_list = [str(arg) for arg in self.args]
         kwargs = ["{}={}".format(*item) for item in self.kwargs.items()]
-        args = ", ".join(args + kwargs)
+        args = ", ".join(args_list + kwargs)
         if self.name is None:
             name = f"MatchesPredicateWithParams({self.predicate!r}, {self.message!r})"
         else:

testtools/matchers/_warnings.py

@@ -68,6 +68,9 @@ def __init__(self, warnings_matcher=None):
     def match(self, matchee):
         with warnings.catch_warnings(record=True) as w:
             warnings.simplefilter("always")
+            # Handle staticmethod objects by extracting the underlying function
+            if isinstance(matchee, staticmethod):
+                matchee = matchee.__func__
             matchee()
             if self.warnings_matcher is not None:
                 return self.warnings_matcher.match(w)

testtools/run.py

@@ -12,11 +12,15 @@
 import sys
 import unittest
 from functools import partial
+from typing import Any
 
 from testtools import TextTestResult
 from testtools.compat import unicode_output_stream
 from testtools.testsuite import filter_by_ids, iterate_tests, sorted_tests
 
+# unittest.TestProgram has these methods but mypy's stubs don't include them
+# We'll just use unittest.TestProgram directly and ignore the type errors
+
 defaultTestLoader = unittest.defaultTestLoader
 defaultTestLoaderCls = unittest.TestLoader
 have_discover = True
@@ -131,6 +135,7 @@ class TestProgram(unittest.TestProgram):
     verbosity = 1
     failfast = catchbreak = buffer = progName = None
     _discovery_parser = None
+    test: Any  # Set by parent class
 
     def __init__(
         self,
@@ -210,7 +215,7 @@ def __init__(
         del self.testLoader.errors[:]
 
     def _getParentArgParser(self):
-        parser = super()._getParentArgParser()
+        parser = super()._getParentArgParser()  # type: ignore[misc]
         # XXX: Local edit (see http://bugs.python.org/issue22860)
         parser.add_argument(
             "-l",
@@ -230,7 +235,7 @@ def _getParentArgParser(self):
         return parser
 
     def _do_discovery(self, argv, Loader=None):
-        super()._do_discovery(argv, Loader=Loader)
+        super()._do_discovery(argv, Loader=Loader)  # type: ignore[misc]
         # XXX: Local edit (see http://bugs.python.org/issue22860)
         self.test = sorted_tests(self.test)