Function _run_zccache

ci/fingerprint/core.py:344–387

Run a zccache fingerprint CLI command. Tries the daemon-backed ``zccache fp`` first (<1ms on cache hit). Falls back to standalone ``zccache-fp`` if the daemon is unavailable. Args: args: Arguments after ``fp`` / the binary name. check: If True, raise on non-zero exit.

(
    args: list[str], *, check: bool = False, timeout: float = 60.0
)

def _run_zccache(
    args: list[str], *, check: bool = False, timeout: float = 60.0
) -> subprocess.CompletedProcess[str]:
    """Run a zccache fingerprint CLI command.

    Tries the daemon-backed ``zccache fp`` first (<1ms on cache hit).
    Falls back to standalone ``zccache-fp`` if the daemon is unavailable.

    Args:
        args: Arguments after ``fp`` / the binary name.
        check: If True, raise on non-zero exit.
        timeout: Subprocess timeout in seconds.

    Returns:
        CompletedProcess with captured stdout/stderr.
    """
    # Try daemon-backed path first: ``zccache fp <args>``
    zccache_bin = _find_zccache()
    if zccache_bin:
        cmd = [zccache_bin, "fp"] + args
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            check=False,
            timeout=timeout,
        )
        # exit 0 (run) or 1 (skip) are valid; exit 2+ means daemon error
        if result.returncode in (0, 1):
            if check and result.returncode not in (0, 1):
                raise subprocess.CalledProcessError(
                    result.returncode, cmd, result.stdout, result.stderr
                )
            return result

    # Fallback to standalone: ``zccache-fp <args>``
    cmd = [_find_zccache_fp()] + args
    return subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        check=check,
        timeout=timeout,
    )


# ==============================================================================