lab: warn_executed.py

Author: nedbat

lab/warn_executed.py

@@ -0,0 +1,213 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
+
+"""
+$ python warn_executed.py <coverage_data_file> <config_file>
+
+Find lines that were excluded by "warn-executed" regex patterns
+but were actually executed according to coverage data.
+
+The config_file is a TOML file with "warn-executed" and "warn-not-partial"
+patterns like:
+
+    warn-executed = [
+        "pragma: no cover",
+        "# debug",
+        "raise NotImplemented",
+        ]
+
+    warn-not-partial = [
+        "if TYPE_CHECKING:",
+    ]
+
+These should be patterns that you excluded as lines or partial branches.
+
+Warning: this program uses internal undocumented private classes from
+coverage.py.  This is an unsupported proof-of-concept.
+
+I wrote a blog post about this:
+https://nedbatchelder.com/blog/202508/finding_unneeded_pragmas.html
+
+"""
+
+import linecache
+import os
+import sys
+import tomllib
+
+from coverage.parser import PythonParser
+from coverage.sqldata import CoverageData
+from coverage.results import Analysis
+
+
+def read_warn_patterns(config_file: str) -> tuple[list[str], list[str]]:
+    """Read "warn-executed" and "warn-not-partial" patterns from a TOML config file."""
+    with open(config_file, "rb") as f:
+        config = tomllib.load(f)
+
+    warn_executed = []
+    warn_not_partial = []
+
+    if "warn-executed" in config:
+        warn_executed.extend(config["warn-executed"])
+    if "warn-not-partial" in config:
+        warn_not_partial.extend(config["warn-not-partial"])
+
+    return warn_executed, warn_not_partial
+
+
+def find_executed_excluded_lines(
+    source_file: str,
+    coverage_data: CoverageData,
+    warn_patterns: list[str],
+) -> set[int]:
+    """
+    Find lines that match warn-executed patterns but were actually executed.
+
+    Args:
+        source_file: Path to the Python source file to analyze
+        coverage_data: The coverage data object
+        warn_patterns: List of regex patterns that should warn if executed
+
+    Returns:
+        Set of executed line numbers that matched any pattern
+    """
+    executed_lines = coverage_data.lines(source_file)
+    if executed_lines is None:
+        return set()
+
+    executed_lines = set(executed_lines)
+
+    try:
+        with open(source_file, "r", encoding="utf-8") as f:
+            source_text = f.read()
+    except Exception:
+        return set()
+
+    parser = PythonParser(text=source_text, filename=source_file)
+    parser.parse_source()
+
+    all_executed_excluded = set()
+    for pattern in warn_patterns:
+        matched_lines = parser.lines_matching(pattern)
+        all_executed_excluded.update(matched_lines & executed_lines)
+
+    return all_executed_excluded
+
+
+def find_not_partial_lines(
+    source_file: str,
+    coverage_data: CoverageData,
+    warn_patterns: list[str],
+) -> set[int]:
+    """
+    Find lines that match warn-not-partial patterns but had both code paths executed.
+
+    Args:
+        source_file: Path to the Python source file to analyze
+        coverage_data: The coverage data object
+        warn_patterns: List of regex patterns for lines expected to be partial
+
+    Returns:
+        Set of line numbers that matched patterns but weren't partial
+    """
+    if not coverage_data.has_arcs():
+        return set()
+
+    all_arcs = coverage_data.arcs(source_file)
+    if all_arcs is None:
+        return set()
+
+    try:
+        with open(source_file, "r", encoding="utf-8") as f:
+            source_text = f.read()
+    except Exception:
+        return set()
+
+    parser = PythonParser(text=source_text, filename=source_file)
+    parser.parse_source()
+
+    all_possible_arcs = set(parser.arcs())
+    executed_arcs = set(all_arcs)
+
+    # Lines with some missing arcs are partial branches
+    partial_lines = set()
+    for start_line in {arc[0] for arc in all_possible_arcs if arc[0] > 0}:
+        possible_from_line = {arc for arc in all_possible_arcs if arc[0] == start_line}
+        executed_from_line = {arc for arc in executed_arcs if arc[0] == start_line}
+        if executed_from_line and possible_from_line != executed_from_line:
+            partial_lines.add(start_line)
+
+    all_not_partial = set()
+    for pattern in warn_patterns:
+        matched_lines = parser.lines_matching(pattern)
+        not_partial = matched_lines - partial_lines
+        all_not_partial.update(not_partial)
+
+    return all_not_partial
+
+
+def analyze_warnings(coverage_file: str, config_file: str) -> dict[str, set[int]]:
+    """
+    Find lines that match warn-executed or warn-not-partial patterns.
+
+    Args:
+        coverage_file: Path to the coverage data file (.coverage)
+        config_file: Path to TOML config file with warning patterns
+
+    Returns:
+        Dictionary mapping filenames to sets of problematic line numbers
+    """
+    warn_executed_patterns, warn_not_partial_patterns = read_warn_patterns(config_file)
+
+    if not warn_executed_patterns and not warn_not_partial_patterns:
+        return {}
+
+    coverage_data = CoverageData(coverage_file)
+    coverage_data.read()
+
+    measured_files = sorted(coverage_data.measured_files())
+
+    all_results = {}
+    for source_file in measured_files:
+        problem_lines = set()
+
+        if warn_executed_patterns:
+            executed_excluded = find_executed_excluded_lines(
+                source_file,
+                coverage_data,
+                warn_executed_patterns,
+            )
+            problem_lines.update(executed_excluded)
+
+        if warn_not_partial_patterns:
+            not_partial = find_not_partial_lines(
+                source_file,
+                coverage_data,
+                warn_not_partial_patterns,
+            )
+            problem_lines.update(not_partial)
+
+        if problem_lines:
+            all_results[source_file] = problem_lines
+
+    return all_results
+
+
+def main():
+    if len(sys.argv) != 3:
+        print(__doc__.rstrip())
+        return 1
+
+    coverage_file, config_file = sys.argv[1:]
+    results = analyze_warnings(coverage_file, config_file)
+
+    for source_file in sorted(results.keys()):
+        problem_lines = results[source_file]
+        for line_num in sorted(problem_lines):
+            line_text = linecache.getline(source_file, line_num).rstrip()
+            print(f"{source_file}:{line_num}: {line_text}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lab/warn_executed.toml

@@ -0,0 +1,15 @@
+warn-executed = [
+    "pragma: not covered",
+    "pragma: not testing",
+    "raise AssertionError",
+    "pragma: only failure",
+    "pragma: cant happen",
+    "pragma: never called",
+    "pytest.mark.skipif\\(env.METACOV",
+    ]
+
+warn-not-partial = [
+    "pragma: partial metacov",
+    "if env.METACOV:",
+    "pragma: part covered",
+    ]