Run Python coverage tooling in a venv

.github/actions/generate-coverage/README.md

@@ -7,8 +7,9 @@ projects. The action uses `cargo llvm-cov` (with `cargo nextest` by default)
 when a `Cargo.toml` is present and `slipcover` with `pytest` when a
 `pyproject.toml` is present. If the repository root does not contain a Cargo
 manifest, set `cargo-manifest` to point to a nested `Cargo.toml`. It installs
-`slipcover` and `pytest` automatically via `uv` before running the tests,
-leveraging ``uv run --with`` so no system-level Python installs are required.
+`slipcover`, `pytest`, and `coverage` automatically via `uv` into an isolated
+throwaway virtual environment (`.venv-coverage`) before running the tests, so
+no system-level Python installs are required.
 When Rust coverage is required, `cargo-llvm-cov` and `cargo-nextest` are
 installed automatically. If both configuration files are present, coverage is
 run for each language and the Cobertura reports are merged using
@@ -45,6 +46,7 @@ codegen-backend-related variables first, and then merges
 `get_cargo_coverage_env(manifest_path)` on top so workflow-level Cranelift
 exports are not treated as the default coverage behaviour.
 
+<!-- markdownlint-disable MD013 -->
 ```mermaid
 sequenceDiagram
     actor GitHubActions
@@ -78,6 +80,7 @@ sequenceDiagram
         _run_cargo-->>run_rust_py: stdout
     end
 ```
+<!-- markdownlint-enable MD013 -->
 
 ## Cranelift codegen backend support
 
@@ -123,6 +126,7 @@ Known limitations:
 
 ## Inputs
 
+<!-- markdownlint-disable MD013 -->
 | Name | Description | Required | Default |
 | --- | --- | --- | --- |
 | features | Enable Cargo (Rust) features; space- or comma-separated. | no | |
@@ -134,11 +138,11 @@ Known limitations:
 | with-ratchet | Fail if coverage drops below baseline | no | `false` |
 | artefact-name-suffix | Additional suffix appended to the uploaded coverage artefact | no | |
 | baseline-rust-file | Rust baseline path | no | `.coverage-baseline.rust` |
-<!-- markdownlint-disable-next-line MD013 -->
 | baseline-python-file | Python baseline path | no | `.coverage-baseline.python` |
 | with-cucumber-rs | Run cucumber-rs scenarios under coverage | no | `false` |
 | cucumber-rs-features | Path to cucumber feature files | no | |
 | cucumber-rs-args | Extra arguments for cucumber | no | |
+<!-- markdownlint-enable MD013 -->
 
 \* `lcov` is only supported for Rust projects, while `coveragepy` is only
 supported for Python projects. Mixed projects must use `cobertura`.

.github/actions/generate-coverage/scripts/run_python.py

@@ -9,12 +9,14 @@
 
 import collections.abc as cabc  # noqa: TC003 - used at runtime
 import contextlib
+import shutil
 import typing as typ
 from pathlib import Path
 
 import typer
 from cmd_utils_loader import run_cmd
 from coverage_parsers import get_line_coverage_percent_from_cobertura
+from plumbum import local
 from plumbum.cmd import uv
 from plumbum.commands.processes import ProcessExecutionError
 from shared_utils import read_previous_coverage
@@ -27,6 +29,14 @@
 FMT_OPT = typer.Option(..., envvar="DETECTED_FMT")
 GITHUB_OUTPUT_OPT = typer.Option(..., envvar="GITHUB_OUTPUT")
 BASELINE_OPT = typer.Option(None, envvar="BASELINE_PYTHON_FILE")
+COVERAGE_VENV = Path(".venv-coverage")
+TOOLING_PACKAGES: tuple[str, ...] = ("slipcover", "pytest", "coverage")
+# _COVERAGE_PYTHON_CMD is a module-level lazy singleton.  GitHub Actions
+# runners execute action steps sequentially in a single thread, so no
+# synchronisation is required.  The variable is None until the first call
+# to _coverage_python_cmd(), after which it is reused for the lifetime of
+# the process.
+_COVERAGE_PYTHON_CMD: BoundCommand | None = None
 
 SLIPCOVER_ARGS: tuple[str, ...] = (
     "-m",
@@ -40,18 +50,93 @@
 )
 
 
-def _uv_python_cmd() -> BoundCommand:
-    """Return ``uv run`` configured with the required coverage tools."""
-    return uv[
-        "run",
-        "--with",
-        "slipcover",
-        "--with",
-        "pytest",
-        "--with",
-        "coverage",
-        "python",
-    ]
+def _coverage_python_path() -> Path:
+    """Return the Python executable path inside the coverage venv."""
+    candidates = (
+        COVERAGE_VENV / "bin" / "python",
+        COVERAGE_VENV / "Scripts" / "python.exe",
+        COVERAGE_VENV / "Scripts" / "python",
+    )
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    paths = ", ".join(str(candidate) for candidate in candidates)
+    msg = f"Coverage venv Python executable not found; checked: {paths}"
+    raise RuntimeError(msg)
+
+
+def create_venv() -> str:
+    """Create a throwaway venv for coverage tooling.
+
+    If the venv directory already exists but its Python executable cannot be
+    located (broken-cache state), the directory is removed and the venv is
+    recreated before returning the interpreter path.
+
+    Returns
+    -------
+    str
+        Absolute path to the Python executable inside the created venv.
+    """
+    if not COVERAGE_VENV.exists():
+        typer.echo(f"Creating coverage venv at {COVERAGE_VENV}")
+        run_cmd(uv["venv", str(COVERAGE_VENV)])
+    else:
+        typer.echo(f"Reusing existing coverage venv at {COVERAGE_VENV}")
+    try:
+        python = str(_coverage_python_path())
+    except RuntimeError:
+        typer.echo(
+            f"Coverage venv at {COVERAGE_VENV} is missing its Python "
+            "executable; recreating.",
+            err=True,
+        )
+        shutil.rmtree(COVERAGE_VENV)
+        run_cmd(uv["venv", str(COVERAGE_VENV)])
+        python = str(_coverage_python_path())
+    return python
+
+
+def install_coverage_tools(python: str) -> None:
+    """Install coverage tooling into the throwaway venv.
+
+    Parameters
+    ----------
+    python : str
+        Path to the Python executable inside the target venv, as returned by
+        create_venv().
+
+    Raises
+    ------
+    plumbum.commands.processes.ProcessExecutionError
+        Propagated from run_cmd() when uv pip install fails.
+    """
+    typer.echo(f"Installing coverage tooling {TOOLING_PACKAGES} into {COVERAGE_VENV}")
+    run_cmd(uv["pip", "install", "--python", python, *TOOLING_PACKAGES])
+
+
+def _coverage_python_cmd() -> BoundCommand:
+    """Set up the coverage venv on first call and return the cached command.
+
+    Side effects on first call
+    --------------------------
+    * Creates .venv-coverage via create_venv() (recreates on broken cache).
+    * Installs slipcover, pytest, and coverage into the venv.
+    * Caches the resulting BoundCommand in _COVERAGE_PYTHON_CMD.
+
+    Returns
+    -------
+    BoundCommand
+        A plumbum command bound to the venv's Python executable.
+    """
+    global _COVERAGE_PYTHON_CMD
+    if _COVERAGE_PYTHON_CMD is not None:
+        typer.echo("Reusing cached coverage Python command.")
+        return _COVERAGE_PYTHON_CMD
+    typer.echo("Setting up coverage Python environment (first use).")
+    python = create_venv()
+    install_coverage_tools(python)
+    _COVERAGE_PYTHON_CMD = local[python]
+    return _COVERAGE_PYTHON_CMD
 
 
 def _coverage_args(fmt: str, out: Path) -> list[str]:
@@ -66,16 +151,17 @@ def _coverage_args(fmt: str, out: Path) -> list[str]:
 
 def coverage_cmd_for_fmt(fmt: str, out: Path) -> BoundCommand:
     """Return the slipcover command for the requested format."""
-    python_cmd = _uv_python_cmd()
+    python_cmd = _coverage_python_cmd()
     return python_cmd[_coverage_args(fmt, out)]
 
 
 @contextlib.contextmanager
 def tmp_coveragepy_xml(out: Path) -> cabc.Generator[Path]:
     """Generate a cobertura XML from coverage.py and clean up afterwards."""
     xml_tmp = out.with_suffix(".xml")
+    python_cmd = _coverage_python_cmd()
     try:
-        cmd = _uv_python_cmd()["-m", "coverage", "xml", "-o", str(xml_tmp)]
+        cmd = python_cmd["-m", "coverage", "xml", "-o", str(xml_tmp)]
         run_cmd(cmd)
     except ProcessExecutionError as exc:
         typer.echo(