debug: re-organize Matchers to show more of what they do

Author: nedbat

coverage/files.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import abc
 import hashlib
 import ntpath
 import os
@@ -16,8 +17,7 @@
 
 from coverage import env
 from coverage.exceptions import ConfigError
-from coverage.misc import human_sorted, isolate_module, join_regex
-from coverage.types import TMatcher
+from coverage.misc import human_sorted, isolate_module, join_regex, plural
 
 os = isolate_module(os)
 
@@ -215,26 +215,59 @@ def prep_patterns(patterns: Iterable[str]) -> list[str]:
     return prepped
 
 
-class TreeMatcher(TMatcher):
-    """A matcher for files in a tree.
+DebugFn = Callable[[str], None] | None
 
-    Construct with a list of paths, either files or directories. Paths match
-    with the `match` method if they are one of the files, or if they are
-    somewhere in a subtree rooted at one of the directories.
 
-    """
+class Matcher(abc.ABC):
+    """Common behavior for matchers."""
 
-    def __init__(self, paths: Iterable[str], name: str = "unknown") -> None:
-        self.original_paths: list[str] = human_sorted(paths)
-        self.paths = [os.path.normcase(p) for p in paths]
+    def __init__(self, strs: list[str], name: str, caption: str, debug: DebugFn) -> None:
+        self.strs = strs
         self.name = name
+        if debug:
+            debug(f"{caption} matching {self}")
+            for inf in self.info():
+                debug(f"    {inf}")
+
+    def __str__(self) -> str:
+        n = len(self.strs)
+        return f"{self.__class__.__name__} {self.name!r} {n} {plural(n, 'item')}"
 
     def __repr__(self) -> str:
-        return f"<TreeMatcher {self.name} {self.original_paths!r}>"
+        return f"<{self.__class__.__name__} {self.name} {self.strs!r}>"
+
+    @abc.abstractmethod
+    def match(self, s: str) -> bool:
+        """Does this string match?"""
 
     def info(self) -> list[str]:
         """A list of strings for displaying when dumping state."""
-        return self.original_paths
+        return self.strs
+
+
+class TreeMatcher(Matcher):
+    """A matcher for files in a tree.
+
+    Construct with a list of paths, either files or directories. Paths match
+    with the `match` method if they are one of the files, or if they are
+    somewhere in a subtree rooted at one of the directories.
+    """
+
+    def __init__(
+        self,
+        paths: Iterable[str],
+        name: str = "unknown",
+        caption: str = "",
+        debug: DebugFn = None,
+    ) -> None:
+        self.original_paths = human_sorted(paths)
+        super().__init__(self.original_paths, name=name, caption=caption, debug=debug)
+        self.paths = []
+        for p in paths:
+            ap = os.path.normcase(p)
+            if ap != p and debug:
+                debug(f"        Normalized {p!r} to {ap!r}")
+            self.paths.append(ap)
 
     def match(self, fpath: str) -> bool:  # pylint: disable=arguments-renamed
         """Does `fpath` indicate a file in one of our trees?"""
@@ -250,19 +283,18 @@ def match(self, fpath: str) -> bool:  # pylint: disable=arguments-renamed
         return False
 
 
-class ModuleMatcher(TMatcher):
+class ModuleMatcher(Matcher):
     """A matcher for modules in a tree."""
 
-    def __init__(self, module_names: Iterable[str], name: str = "unknown") -> None:
+    def __init__(
+        self,
+        module_names: Iterable[str],
+        name: str = "unknown",
+        caption: str = "",
+        debug: DebugFn = None,
+    ) -> None:
         self.modules = list(module_names)
-        self.name = name
-
-    def __repr__(self) -> str:
-        return f"<ModuleMatcher {self.name} {self.modules!r}>"
-
-    def info(self) -> list[str]:
-        """A list of strings for displaying when dumping state."""
-        return self.modules
+        super().__init__(self.modules, name=name, caption=caption, debug=debug)
 
     def match(self, module_name: str) -> bool:  # pylint: disable=arguments-renamed
         """Does `module_name` indicate a module in one of our packages?"""
@@ -280,20 +312,19 @@ def match(self, module_name: str) -> bool:  # pylint: disable=arguments-renamed
         return False
 
 
-class GlobMatcher(TMatcher):
+class GlobMatcher(Matcher):
     """A matcher for files by file name pattern."""
 
-    def __init__(self, pats: Iterable[str], name: str = "unknown") -> None:
+    def __init__(
+        self,
+        pats: Iterable[str],
+        name: str = "unknown",
+        caption: str = "",
+        debug: DebugFn = None,
+    ) -> None:
         self.pats = list(pats)
+        super().__init__(self.pats, name=name, caption=caption, debug=debug)
         self.re = globs_to_regex(self.pats, case_insensitive=env.WINDOWS)
-        self.name = name
-
-    def __repr__(self) -> str:
-        return f"<GlobMatcher {self.name} {self.pats!r}>"
-
-    def info(self) -> list[str]:
-        """A list of strings for displaying when dumping state."""
-        return self.pats
 
     def match(self, fpath: str) -> bool:  # pylint: disable=arguments-renamed
         """Does `fpath` match one of our file name patterns?"""

coverage/inorout.py

@@ -206,46 +206,42 @@ def _debug(msg: str) -> None:
                 self.debug.write(msg)
 
         # Generally useful information
-        _debug("sys.path:" + "".join(f"\n    {p}" for p in sys.path))
+        _debug("sys.path:" + "".join(f"\n    {p!r}" for p in sys.path))
 
         if self.debug:
             _debug("sysconfig paths:")
             for scheme in sorted(sysconfig.get_scheme_names()):
                 _debug(f"    {scheme}:")
                 for k, v in sysconfig.get_paths(scheme).items():
-                    _debug(f"        {k}: {v}")
+                    _debug(f"        {k}: {v!r}")
 
         # Create the matchers we need for should_trace
         self.source_match = None
         self.source_pkgs_match = None
         self.pylib_match = None
-        self.include_match = self.omit_match = None
+        self.include_match = None
+        self.omit_match = None
 
         if self.source_dirs or self.source_pkgs:
-            against = []
             if self.source_dirs:
-                self.source_match = TreeMatcher(self.source_dirs, "source")
-                against.append(f"trees {self.source_match!r}")
+                self.source_match = TreeMatcher(
+                    self.source_dirs, "source", "Source directory", _debug
+                )
             if self.source_pkgs:
-                self.source_pkgs_match = ModuleMatcher(self.source_pkgs, "source_pkgs")
-                against.append(f"modules {self.source_pkgs_match!r}")
-            _debug("Source matching against " + " and ".join(against))
+                self.source_pkgs_match = ModuleMatcher(
+                    self.source_pkgs, "source_pkgs", "Source imports", _debug
+                )
         else:
             if self.pylib_paths:
-                self.pylib_match = TreeMatcher(self.pylib_paths, "pylib")
-                _debug(f"Python stdlib matching: {self.pylib_match!r}")
+                self.pylib_match = TreeMatcher(self.pylib_paths, "pylib", "Python stdlib", _debug)
         if self.include:
-            self.include_match = GlobMatcher(self.include, "include")
-            _debug(f"Include matching: {self.include_match!r}")
+            self.include_match = GlobMatcher(self.include, "include", "Include", _debug)
         if self.omit:
-            self.omit_match = GlobMatcher(self.omit, "omit")
-            _debug(f"Omit matching: {self.omit_match!r}")
+            self.omit_match = GlobMatcher(self.omit, "omit", "Omit", _debug)
 
-        self.cover_match = TreeMatcher(self.cover_paths, "coverage")
-        _debug(f"Coverage code matching: {self.cover_match!r}")
+        self.cover_match = TreeMatcher(self.cover_paths, "coverage", "Coverage code", _debug)
 
-        self.third_match = TreeMatcher(self.third_paths, "third")
-        _debug(f"Third-party lib matching: {self.third_match!r}")
+        self.third_match = TreeMatcher(self.third_paths, "third", "Third-party lib", _debug)
 
         # Check if the source we want to measure has been installed as a
         # third-party package.
@@ -277,8 +273,9 @@ def _debug(msg: str) -> None:
             if self.third_match.match(src):
                 _debug(f"Source in third-party: source directory {src!r}")
                 self.source_in_third_paths.add(src)
-        self.source_in_third_match = TreeMatcher(self.source_in_third_paths, "source_in_third")
-        _debug(f"Source in third-party matching: {self.source_in_third_match}")
+        self.source_in_third_match = TreeMatcher(
+            self.source_in_third_paths, "source_in_third", "Source in third-party", _debug
+        )
 
         self.plugins: Plugins
         self.disp_class: type[TFileDisposition] = FileDisposition

coverage/types.py

@@ -65,13 +65,6 @@ class TFileDisposition(Protocol):
     has_dynamic_filename: bool
 
 
-class TMatcher(Protocol):
-    """The shape all Matchers have."""
-
-    def match(self, s: str) -> bool:
-        """Does this string match?"""
-
-
 # When collecting data, we use a dictionary with a few possible shapes. The
 # keys are always file names.
 # - If measuring line coverage, the values are sets of line numbers.

tests/test_files.py

@@ -20,6 +20,7 @@
 from coverage.exceptions import ConfigError
 from coverage.files import (
     GlobMatcher,
+    Matcher,
     ModuleMatcher,
     PathAliases,
     TreeMatcher,
@@ -29,7 +30,6 @@
     flat_rootname,
     globs_to_regex,
 )
-from coverage.types import TMatcher
 
 from tests.coveragetest import CoverageTest
 from tests.helpers import os_sep
@@ -369,7 +369,7 @@ def setUp(self) -> None:
         super().setUp()
         files.set_relative_directory()
 
-    def assertMatches(self, matcher: TMatcher, filepath: str, matches: bool) -> None:
+    def assertMatches(self, matcher: Matcher, filepath: str, matches: bool) -> None:
         """The `matcher` should agree with `matches` about `filepath`."""
         canonical = files.canonical_filename(filepath)
         msg = f"File {filepath} should have matched as {matches}"