`k4bench.provenance.stack`¶

k4bench.provenance.stack ¶

Read a Key4hep release's git provenance off CVMFS.

Spack records the exact upstream commit of every package it builds from git, in three independent places that this module reads in order of preference:

{release}/.spack-db/index.json — the install database, one file for the whole stack (spec.parameters.commit).
the install directory name, {release}/{pkg}/{commit}_{version}-{hash} — used when the database is unreadable or its schema moved. Coarser (no dependency info) but essentially immune to schema churn.
{install}/.spack/repos/**/packages/{pkg}/package.py — the recipe Spack ships beside each install, whose git = attribute is the upstream URL. Every git-built package in the stack carries one, including the ones from Spack's own builtin repo (those nest one level deeper, under repos/spack_repo/builtin/).

Nothing here raises: provenance is metadata about a benchmark, and a stack this module cannot parse must degrade to an empty record rather than fail the benchmark that produced the measurements.

RepoRef `dataclass` ¶

RepoRef(forge: str, host: str, slug: str)

A package's upstream repository, parsed far enough to build links.

url `property` ¶

url: str

The repository's landing page.

find_release_root ¶

find_release_root(stack_setup: str | Path) -> Path | None

Return the release root for a $KEY4HEP_STACK path, or None.

$KEY4HEP_STACK points at the stack's own setup.sh, several levels below the release root::

/cvmfs/sw-nightlies.hsf.org/key4hep/releases/{date}/{platform}
    └── key4hep-stack/{version}/setup.sh   ← $KEY4HEP_STACK

We walk up looking for the .spack-db the caller actually needs, rather than matching the releases/{date}/{platform} layout with a regex: the walk tests for the artifact itself, so it keeps working if upstream renests the tree, and it fails loudly (None) instead of silently returning a plausible-looking wrong directory.

Source code in k4bench/provenance/stack.py

def find_release_root(stack_setup: str | Path) -> Path | None:
    """Return the release root for a ``$KEY4HEP_STACK`` path, or ``None``.

    ``$KEY4HEP_STACK`` points at the stack's own ``setup.sh``, several levels
    below the release root::

        /cvmfs/sw-nightlies.hsf.org/key4hep/releases/{date}/{platform}
            └── key4hep-stack/{version}/setup.sh   ← $KEY4HEP_STACK

    We walk up looking for the ``.spack-db`` the caller actually needs, rather
    than matching the ``releases/{date}/{platform}`` layout with a regex: the
    walk tests for the artifact itself, so it keeps working if upstream renests
    the tree, and it fails loudly (``None``) instead of silently returning a
    plausible-looking wrong directory.
    """
    path = Path(stack_setup)
    start = path if path.is_dir() else path.parent
    for candidate in (start, *start.parents)[:_MAX_WALK_UP]:
        if (candidate / ".spack-db" / "index.json").is_file():
            return candidate
    _log.warning("find_release_root: no .spack-db above '%s'", stack_setup)
    return None

parse_repo ¶

parse_repo(url: str | None) -> RepoRef | None

Parse a recipe's git URL, or None if we cannot build links for it.

Recognizes GitHub and GitLab (including the self-hosted gitlab.cern.ch and gitlab.desy.de instances two Key4hep packages live on). An unrecognized forge returns None: the package keeps its commit, but guessing a URL layout would produce links that quietly 404.

Source code in k4bench/provenance/stack.py

def parse_repo(url: str | None) -> RepoRef | None:
    """Parse a recipe's ``git`` URL, or ``None`` if we cannot build links for it.

    Recognizes GitHub and GitLab (including the self-hosted ``gitlab.cern.ch``
    and ``gitlab.desy.de`` instances two Key4hep packages live on). An
    unrecognized forge returns ``None``: the package keeps its commit, but
    guessing a URL layout would produce links that quietly 404.
    """
    if not url:
        return None
    match = _URL_RE.match(url.strip())
    if not match:
        return None
    host, slug = match.group("host"), match.group("slug")
    if host == "github.com":
        forge = "github"
        # GitHub repos are exactly owner/repo; anything deeper is not a repo
        # root, so a compare link built from it would not resolve.
        if slug.count("/") != 1:
            return None
    elif "gitlab" in host:
        forge = "gitlab"  # nested groups are allowed, so no depth check
    else:
        return None
    return RepoRef(forge=forge, host=host, slug=slug)

read_stack_packages ¶

read_stack_packages(release_root: str | Path) -> dict[str, dict]

Return {package: {"commit", "version", "repo_url"}} for a release.

Only packages Spack built from git are included — a release-tarball install has no upstream commit, so it can never be the subject of a blame window. repo_url is the recipe's URL verbatim (None when the recipe is missing); use :func:github_slug to normalize it.

Returns {} rather than raising when release_root cannot be read at all, so a caller can record "no provenance" and carry on.

Source code in k4bench/provenance/stack.py

def read_stack_packages(release_root: str | Path) -> dict[str, dict]:
    """Return ``{package: {"commit", "version", "repo_url"}}`` for a release.

    Only packages Spack built from git are included — a release-tarball install
    has no upstream commit, so it can never be the subject of a blame window.
    ``repo_url`` is the recipe's URL verbatim (``None`` when the recipe is
    missing); use :func:`github_slug` to normalize it.

    Returns ``{}`` rather than raising when *release_root* cannot be read at
    all, so a caller can record "no provenance" and carry on.
    """
    root = Path(release_root)
    packages = _from_database(root)
    if packages:
        return packages
    _log.info("read_stack_packages: falling back to install-dir scan of '%s'", root)
    return _from_install_dirs(root)

k4bench.provenance.stack¶