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:
"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: withoutstainedglass_core[git]it is skipped and the next layer answers."build-stamp"--stainedglass_core._build_info, generated at build time byscripts/generate_build_info.py. Because it holds only constants, it survivespython -OO -m compilealland therefore rides inside bytecode-only wheels and Docker images that contain no.gitdirectory."direct-url"-- :pep:610direct_url.json, which pip writes forpip install git+ssh://...@branchwithout any cooperation from this package."metadata-only"-- the distribution version alone. Degraded, andbuild_infosays so via itssourcefield.
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 |
build_kind |
str | None
|
How the artifact was produced, for example |
build_time |
str | None
|
When the artifact was built, ISO 8601. |
ci |
dict[str, str] | None
|
Allowlisted CI metadata, including |
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 |
describe |
str | None
|
The output of |
dirty |
bool | None
|
Whether the work tree had uncommitted changes. When |
on_remote |
bool | None
|
Whether |
parents |
list[str] | None
|
The full SHAs of |
remote_url |
str | None
|
The |
source |
ProvenanceSource
|
Which resolution layer answered, and therefore how much to trust the rest. |
version |
str | None
|
The PEP 440 distribution version. |
build_kind
instance-attribute
¶
build_kind: str | None
How the artifact was produced, for example "wheel" or "bytecode-wheel".
ci
instance-attribute
¶
Allowlisted CI metadata, including run_url, when built in GitHub Actions.
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
¶
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
¶
Which resolution layer answered, and therefore how much to trust the rest.
build_info
¶
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 |
Examples:
content_digest
cached
¶
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 |
str | None
|
particular an editable install has a |
str | None
|
there is nothing meaningful to digest and the working-tree layer applies instead. |
Examples:
short_commit
¶
Abbreviate a commit SHA for display, such as an experiment-tracker tag or a log line.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
str | None
|
A full commit SHA, typically |
required |
Returns:
| Type | Description |
|---|---|
str
|
The first seven characters of |
Examples: