Skip to content

provenance

Report the exact code state of the installed Stained Glass Core.

A version number identifies a release; a provenance record identifies a build. Because local_scheme = "no-local-version" strips the commit hash from the PEP 440 version (private package registries reject local version segments), two feature branches forked from the same commit produce identical version strings. Downstream repositories that pin Stained Glass Core to an unmerged branch therefore cannot identify the code from the version alone.

This module answers that question in every deployment shape, degrading gracefully:

  1. "working-tree" -- an editable or source install whose files sit in a git work tree. Live git state wins here, because a stamp baked at install time goes stale the moment a file is edited. This layer reads through GitPython, an optional extra: without stainedglass_core[git] it is skipped and the next layer answers.
  2. "build-stamp" -- stainedglass_core._build_info, generated at build time by scripts/generate_build_info.py. Because it holds only constants, it survives python -OO -m compileall and therefore rides inside bytecode-only wheels and Docker images that contain no .git directory.
  3. "direct-url" -- :pep:610 direct_url.json, which pip writes for pip install git+ssh://...@branch without any cooperation from this package.
  4. "metadata-only" -- the distribution version alone. Degraded, and build_info says so via its source field.

Nothing here raises on missing git, missing metadata, or a missing stamp; every field degrades to None. The source field always states which layer answered, so callers can log how much they trust the answer.

Examples:

Record the code state of a training run::

>>> from stainedglass_core import provenance
>>> info = provenance.build_info()
>>> sorted(info)  # doctest: +ELLIPSIS
['branch', 'build_kind', 'build_time', 'ci', 'commit', ..., 'source', 'version']

Classes:

Name Description
BuildInfo

The code state of an installed Stained Glass Core.

Functions:

Name Description
build_info

Report the code state of the installed Stained Glass Core.

content_digest

Compute a stable digest over the installed package files.

short_commit

Abbreviate a commit SHA for display, such as an experiment-tracker tag or a log line.

BuildInfo

Bases: HeadState

The code state of an installed Stained Glass Core.

Every field except source may be None when the corresponding information is unavailable in a given deployment shape. The git fields are inherited from the HEAD state every source reads.

Attributes:

Name Type Description
branch str | None

The branch name, or None when detached.

build_kind str | None

How the artifact was produced, for example "wheel" or "bytecode-wheel".

build_time str | None

When the artifact was built, ISO 8601.

ci dict[str, str] | None

Allowlisted CI metadata, including run_url, when built in GitHub Actions.

commit str | None

The full 40-character commit SHA.

commit_date str | None

The commit timestamp, ISO 8601.

content_digest str | None

A digest over the installed files. See content_digest.

describe str | None

The output of git describe --tags --match 'v[0-9]*' --always --dirty --long, relative to the

dirty bool | None

Whether the work tree had uncommitted changes. When True, commit does not fully

on_remote bool | None

Whether commit was reachable on origin, and so fetchable by a teammate.

parents list[str] | None

The full SHAs of commit's parents, recorded only by the build stamp.

remote_url str | None

The origin remote URL, needed to identify which fork a commit belongs to.

source ProvenanceSource

Which resolution layer answered, and therefore how much to trust the rest.

version str | None

The PEP 440 distribution version.

branch instance-attribute

branch: str | None

The branch name, or None when detached.

build_kind instance-attribute

build_kind: str | None

How the artifact was produced, for example "wheel" or "bytecode-wheel".

build_time instance-attribute

build_time: str | None

When the artifact was built, ISO 8601.

ci instance-attribute

ci: dict[str, str] | None

Allowlisted CI metadata, including run_url, when built in GitHub Actions.

commit instance-attribute

commit: str | None

The full 40-character commit SHA.

commit_date instance-attribute

commit_date: str | None

The commit timestamp, ISO 8601.

content_digest instance-attribute

content_digest: str | None

A digest over the installed files. See content_digest.

describe instance-attribute

describe: str | None

The output of git describe --tags --match 'v[0-9]*' --always --dirty --long, relative to the nearest release tag.

dirty instance-attribute

dirty: bool | None

Whether the work tree had uncommitted changes. When True, commit does not fully describe the code.

on_remote instance-attribute

on_remote: bool | None

Whether commit was reachable on origin, and so fetchable by a teammate.

Only the build stamp records this: resolving it needs a network round-trip, which build_info must not perform. It is None for every other source.

parents instance-attribute

parents: list[str] | None

The full SHAs of commit's parents, recorded only by the build stamp.

A pull-request build stamps GitHub's synthetic merge, which GitHub can regenerate under a new SHA and which no ref keeps. Merging these two parents recreates its code once that SHA is gone. It is None for every other source, and an empty list for a root commit.

remote_url instance-attribute

remote_url: str | None

The origin remote URL, needed to identify which fork a commit belongs to.

Credentials embedded in the URL are stripped before this field is set: a record built from an authenticated HTTPS checkout would otherwise carry an access token into every wheel, image and experiment-tracker run that receives it. A private repository therefore needs the consumer's own credentials to clone from this value.

source instance-attribute

source: ProvenanceSource

Which resolution layer answered, and therefore how much to trust the rest.

version instance-attribute

version: str | None

The PEP 440 distribution version.

build_info

build_info() -> BuildInfo

Report the code state of the installed Stained Glass Core.

Resolves through the layers described in the module docstring, stopping at the first that answers, and always reports which one did via the source field.

Returns:

Type Description
BuildInfo

The provenance record. Never raises; unavailable fields are None.

Examples:

>>> info = build_info()
>>> info["source"] in {"working-tree", "build-stamp", "direct-url", "metadata-only"}
True

content_digest cached

content_digest() -> str | None

Compute a stable digest over the installed package files.

The digest folds together the per-file SHA-256 entries that the wheel's RECORD already carries, so it costs no extra hashing and needs no cooperation from the build. It identifies the code even when git state is absent or dishonest, which makes it the way to check that two deployments -- a training job and an inference proxy, say -- were installed from the same wheel.

It reports what was installed, not what is on disk now: because it re-reads no files, an edit made after installation leaves the digest unchanged. Detecting that is a different problem, and not one a self-computed hash can solve -- whoever can rewrite an installed .py can rewrite the RECORD beside it -- so it needs a signature over the artifact rather than a digest derived from it.

Returns:

Type Description
str | None

A "sha256:..." string, or None when the package was not installed from a wheel. In

str | None

particular an editable install has a RECORD listing only path-configuration shims, so

str | None

there is nothing meaningful to digest and the working-tree layer applies instead.

Examples:

>>> digest = content_digest()
>>> digest is None or digest.startswith("sha256:")
True

short_commit

short_commit(commit: str | None) -> str

Abbreviate a commit SHA for display, such as an experiment-tracker tag or a log line.

Parameters:

Name Type Description Default

commit

str | None

A full commit SHA, typically build_info()["commit"], or None when unavailable.

required

Returns:

Type Description
str

The first seven characters of commit, or "unknown" when it is None.

Examples:

>>> short_commit("1234567" + "0" * 33)
'1234567'
>>> short_commit(None)
'unknown'