version_info

Documentation for eth_defi.version_info Python module.

Read Docker image git version stamp.

During the Docker image build, the git revision of the source tree is written into GIT_VERSION_TAG.txt, GIT_COMMIT_MESSAGE.txt and GIT_VERSION_HASH.txt files at the install root — see Dockerfile.vault-scanner. This module reads those files back at runtime so long-running services can report which code revision they are running, e.g. the vault scanner embedding its version in the top-vaults JSON export.

Modelled on the trade-executor VersionInfo pattern, based on https://stackoverflow.com/a/74694676/315168

Example:

from eth_defi.version_info import VersionInfo

version = VersionInfo.read_docker_version()
print(version.commit_hash)  # None outside Docker

Module Attributes

`UNSPECIFIED_SENTINEL`	Sentinel written by the Docker build when a version ARG was not passed.
`PARQUET_VERSION_METADATA_KEY`	Custom Parquet key containing the same mapping as JSON export `metadata.version` fields.

Functions

stamp_parquet_schema_metadata(schema[, ...])

Add vault-scanner build provenance to a PyArrow schema.

Classes

VersionInfo

Reflect the git version information embedded in the Docker image during build.

VERSION_FILE_ROOT: pathlib.Path = PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi')

Install root where the Docker build writes the version stamp files.

Resolves to the directory containing the eth_defi package, e.g. /usr/src/web3-ethereum-defi inside the vault scanner image or the repository checkout when running from source.

UNSPECIFIED_SENTINEL = 'unspecified'

Sentinel written by the Docker build when a version ARG was not passed.

Dockerfile.vault-scanner defaults each GIT_* build ARG to unspecified, so an image built without the args (e.g. a plain docker compose build) stamps this literal string into the files. VersionInfo.read_version_file() normalises it to None.

PARQUET_VERSION_METADATA_KEY = b'metadata.version': Custom Parquet key containing the same mapping as JSON export metadata.version fields. The value is a UTF-8 JSON object, because Apache Parquet file metadata is a flat bytes-to-bytes mapping.

class VersionInfo

Bases: object

Reflect the git version information embedded in the Docker image during build.

All fields are None when running outside a stamped Docker image, e.g. from a source checkout. Individual fields can also be None inside a stamped image when the corresponding build ARG was not passed — in particular tag is None for images built from an untagged commit. See Dockerfile.vault-scanner for how the stamp files are written.

tag: Optional[str]

Git tag at build time, e.g. v0.30.

Often None: only set when the image was built with the GIT_VERSION_TAG build ARG, which requires a tagged commit. Use commit_hash as the primary build identifier.

commit_message: Optional[str]: The latest git commit message at build time.

commit_hash: Optional[str]: Git commit SHA hash at build time.

static read_version_file(name, root=PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi'))

Read one version stamp file written by the Docker build.

Parameters

name (str) – Stamp file name, e.g. GIT_VERSION_HASH.txt.
root (pathlib.Path) – Directory holding the stamp files.

Returns

Stripped file content, or None if the file does not exist, is empty, or contains the UNSPECIFIED_SENTINEL placeholder written when the build ARG was not passed.

Return type

Optional[str]

classmethod read_docker_version(root=PosixPath('/home/runner/work/web3-ethereum-defi/web3-ethereum-defi'))

Read version information burnt within the Docker file system during image build.

Parameters: root (pathlib.Path) – Directory holding the stamp files. Defaults to the eth_defi install root.
Returns: Populated version info, or None for every field when the stamp files are absent (e.g. running from a source checkout).
Return type: eth_defi.version_info.VersionInfo

as_dict()

Return a JSON-serialisable dict for embedding in data exports.

Returns: Dict with tag, commit_message and commit_hash keys.
Return type: dict[str, str | None]

as_parquet_metadata()

Serialise this version stamp for Parquet file metadata.

Uses PARQUET_VERSION_METADATA_KEY with the exact mapping returned by as_dict(). This is the Parquet equivalent of the metadata.version object included in vault scanner JSON exports.

Returns: A PyArrow-compatible metadata mapping. The value is UTF-8 JSON so None fields retain their JSON meaning instead of being conflated with empty strings.
Return type: dict[bytes, bytes]

__init__(tag=None, commit_message=None, commit_hash=None)

Parameters

tag (Optional[str]) –
commit_message (Optional[str]) –
commit_hash (Optional[str]) –

Return type

None

stamp_parquet_schema_metadata(schema, version_info=None)

Add vault-scanner build provenance to a PyArrow schema.

Preserves existing schema metadata, such as pandas’ column-index metadata, while replacing the scanner’s version stamp with the version of the code currently writing the file. Use this for every scanner-produced Parquet artefact so raw, cleaned, and sample price data can be traced to the same Docker build as the JSON exports.

Parameters

schema (Any) – PyArrow schema to stamp. Any avoids imposing a runtime PyArrow dependency on the lightweight version-information module.
version_info (Optional[eth_defi.version_info.VersionInfo]) – Optional explicit version for tests or specialised callers. When omitted, reads the Docker image stamp of the current process.

Returns

A copy of schema with metadata.version provenance metadata.

Return type

Any