python_coverage_gate Namespace Reference

Data Structures
class	PathAwareIgnore

Functions
str	normalize_path (str|Path path)
	Resolve a filesystem path to the canonical string used as a coverage-map key.
argparse.Namespace	parse_args ()
	Parse coverage thresholds, targets, output location, and pytest arguments for this gate.
list[str]	build_trace_ignoredirs ()
	Build trace ignoredirs.
dict[str, dict[int, int]]	collect_counts (trace.CoverageResults results)
	Transform Python trace results into a per-file, per-line execution-count mapping.
tuple[int, int, float]	compute_file_coverage (Path target, dict[str, dict[int, int]] counts_by_file)
	Compute file coverage.
int	main ()
	Entry point for this script.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
list	DEFAULT_TARGETS

Detailed Description

Run pytest under stdlib trace and enforce a line-coverage threshold.

Function Documentation

normalize_path()

str python_coverage_gate.normalize_path

(

str | Path

path

)

Resolve a filesystem path to the canonical string used as a coverage-map key.

Parameters

[in]

path

Filesystem path argument passed to normalize_path().

Returns

Value returned by normalize_path().

Definition at line 41 of file python_coverage_gate.py.

def normalize_path(path: str | Path) -> str:
    """!
    @brief Resolve a filesystem path to the canonical string used as a coverage-map key.
    @param[in] path Filesystem path argument passed to `normalize_path()`.
    @return Value returned by `normalize_path()`.
    """
    return str(Path(path).resolve())
 
 

Here is the caller graph for this function:

parse_args()

argparse.Namespace python_coverage_gate.parse_args

(

)

Parse coverage thresholds, targets, output location, and pytest arguments for this gate.

Returns

Value returned by parse_args().

Definition at line 50 of file python_coverage_gate.py.

def parse_args() -> argparse.Namespace:
    """!
    @brief Parse coverage thresholds, targets, output location, and pytest arguments for this gate.
    @return Value returned by `parse_args()`.
    """
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "Examples:\n"
            "  python3 tests/tooling/python_coverage_gate.py\n"
            "  python3 tests/tooling/python_coverage_gate.py --target picurv_cli/core.py --target generators/grid.gen\n"
            "  python3 tests/tooling/python_coverage_gate.py --pytest-args -- -q tests/test_cli_smoke.py\n"
        ),
    )
    parser.add_argument(
        "--min-line",
        type=float,
        default=70.0,
        help="Minimum required weighted line coverage percent (default: 70.0).",
    )
    parser.add_argument(
        "--target",
        action="append",
        default=[],
        help=(
            "Repository-relative file to include in coverage computation "
            "(repeatable). Defaults to core runtime scripts."
        ),
    )
    parser.add_argument(
        "--output-dir",
        default="coverage/python",
        help="Repository-relative output directory for coverage artifacts (default: coverage/python).",
    )
    parser.add_argument(
        "--pytest-args",
        nargs=argparse.REMAINDER,
        default=["-q"],
        help="Arguments passed to pytest (prefix with --pytest-args -- ...).",
    )
    return parser.parse_args()
 
 

Here is the caller graph for this function:

build_trace_ignoredirs()

list[str] python_coverage_gate.build_trace_ignoredirs

(

)

Build trace ignoredirs.

Returns

Value returned by build_trace_ignoredirs().

Definition at line 94 of file python_coverage_gate.py.

def build_trace_ignoredirs() -> list[str]:
    """!
    @brief Build trace ignoredirs.
    @return Value returned by `build_trace_ignoredirs()`.
    """
    ignoredirs = {
        normalize_path(sys.prefix),
        normalize_path(sys.exec_prefix),
        normalize_path(Path(sys.prefix) / "lib"),
    }
    for raw in list(sys.path):
        if not raw:
            continue
        path = Path(raw)
        if not path.exists():
            continue
        resolved = normalize_path(path)
        if "/site-packages" in resolved or "/dist-packages" in resolved:
            ignoredirs.add(resolved)
    return sorted(ignoredirs)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

collect_counts()

dict[str, dict[int, int]] python_coverage_gate.collect_counts

(

trace.CoverageResults

results

)

Transform Python trace results into a per-file, per-line execution-count mapping.

Parameters

[in]

results

Argument passed to collect_counts().

Returns

Value returned by collect_counts().

Definition at line 116 of file python_coverage_gate.py.

def collect_counts(results: trace.CoverageResults) -> dict[str, dict[int, int]]:
    """!
    @brief Transform Python trace results into a per-file, per-line execution-count mapping.
    @param[in] results Argument passed to `collect_counts()`.
    @return Value returned by `collect_counts()`.
    """
    counts_by_file: dict[str, dict[int, int]] = {}
    for (filename, lineno), count in results.counts.items():
        file_key = normalize_path(filename)
        counts_by_file.setdefault(file_key, {})[lineno] = count
    return counts_by_file
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

compute_file_coverage()

tuple[int, int, float] python_coverage_gate.compute_file_coverage	(	Path	target,
		dict[str, dict[int, int]]	counts_by_file
	)

Compute file coverage.

Parameters

[in]	target	Argument passed to compute_file_coverage().
[in]	counts_by_file	Argument passed to compute_file_coverage().

Returns

Value returned by compute_file_coverage().

Definition at line 129 of file python_coverage_gate.py.

def compute_file_coverage(target: Path, counts_by_file: dict[str, dict[int, int]]) -> tuple[int, int, float]:
    """!
    @brief Compute file coverage.
    @param[in] target Argument passed to `compute_file_coverage()`.
    @param[in] counts_by_file Argument passed to `compute_file_coverage()`.
    @return Value returned by `compute_file_coverage()`.
    """
    finder = getattr(trace, "find_executable_linenos", None)
    if finder is None:
        finder = trace._find_executable_linenos  # type: ignore[attr-defined]
    executable = finder(str(target))
    executable_lines = set(executable.keys())
    total = len(executable_lines)
    if total == 0:
        return 0, 0, 100.0
 
    observed = counts_by_file.get(normalize_path(target), {})
    covered = sum(1 for line in executable_lines if observed.get(line, 0) > 0)
    percent = (100.0 * covered) / total
    return covered, total, percent
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

main()

int python_coverage_gate.main

(

)

Entry point for this script.

Returns

Value returned by main().

Definition at line 151 of file python_coverage_gate.py.

def main() -> int:
    """!
    @brief Entry point for this script.
    @return Value returned by `main()`.
    """
    args = parse_args()
    output_dir = (REPO_ROOT / args.output_dir).resolve()
    output_dir.mkdir(parents=True, exist_ok=True)
 
    targets_raw = args.target if args.target else DEFAULT_TARGETS
    targets = [Path(REPO_ROOT / rel).resolve() for rel in targets_raw]
    for target in targets:
        if not target.exists():
            raise SystemExit(f"[coverage-python] target not found: {target}")
 
    pytest_args = list(args.pytest_args)
    if pytest_args and pytest_args[0] == "--":
        pytest_args = pytest_args[1:]
    if not pytest_args:
        pytest_args = ["-q"]
 
    ignoredirs = build_trace_ignoredirs()
 
    import pytest
 
    tracer = trace.Trace(count=True, trace=False, ignoredirs=ignoredirs)
    # Python 3.8's trace._Ignore caches decisions by file basename, so seeing an
    # ignored dependency named core.py can incorrectly hide this repository's
    # picurv_cli/core.py for the rest of a full-suite run.
    tracer.ignore = PathAwareIgnore(ignoredirs)
    exit_code = tracer.runfunc(pytest.main, pytest_args)
    results = tracer.results()
 
    counts_by_file = collect_counts(results)
 
    print("[coverage-python] per-file line coverage")
    print("[coverage-python] -----------------------------------------------")
 
    total_cov = 0
    total_exec = 0
    for target in targets:
        covered, executable, percent = compute_file_coverage(target, counts_by_file)
        total_cov += covered
        total_exec += executable
        rel = target.relative_to(REPO_ROOT)
        print(f"[coverage-python] {rel}: {covered}/{executable} ({percent:.2f}%)")
 
    overall = 100.0 if total_exec == 0 else (100.0 * total_cov) / total_exec
    print("[coverage-python] -----------------------------------------------")
    print(f"[coverage-python] weighted total: {total_cov}/{total_exec} ({overall:.2f}%)")
    print(f"[coverage-python] minimum required: {args.min_line:.2f}%")
 
    summary_path = output_dir / "summary.txt"
    summary_path.write_text(
        "\n".join(
            [
                f"weighted_total={overall:.4f}",
                f"covered_lines={total_cov}",
                f"executable_lines={total_exec}",
                f"minimum_required={args.min_line:.4f}",
            ]
        )
        + "\n",
        encoding="utf-8",
    )
 
    if int(exit_code) != 0:
        print(f"[coverage-python] pytest failed with exit code {exit_code}.", file=sys.stderr)
        return int(exit_code)
    if overall < args.min_line:
        print(
            f"[coverage-python] FAIL: coverage {overall:.2f}% is below required {args.min_line:.2f}%.",
            file=sys.stderr,
        )
        return 2
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

python_coverage_gate.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 13 of file python_coverage_gate.py.

DEFAULT_TARGETS

list python_coverage_gate.DEFAULT_TARGETS

Initial value:

=  [
    "picurv_cli/core.py",
    "picurv_cli/cli.py",
]

Definition at line 14 of file python_coverage_gate.py.