Registry

registry.VersionInfo

One registered artifact version.

Usage

Source

registry.VersionInfo(
    name,
    version,
    path,
    metadata,
)

Attributes

name: str

The artifact family (the experiment or model name).

version: str

The version directory name, v<NNN>-<YYYYMMDD>-<digest12>.

path: Path

The version directory holding the artifact files and metadata.

metadata: dict[str, object]

The parsed metadata.json.

registry.versions()

Every registered version of an artifact family under root, oldest first.

Usage

Source

registry.versions(name, *, root)

registry.current()

The promoted version the current symlink names, or None when nothing is promoted.

Usage

Source

registry.current(name, *, root)

registry.register()

Writes a new immutable version directory under root; never flips current.

Usage

Source

registry.register(name, files, metadata, *, root)

The registry owns what it registers: every path source is copied into the version directory, so the registered artifact is the registry’s own and no later writer to the source can mutate it. The copies land read-only. The directory name embeds the next version number, today’s date, and a 12-hex content digest over the stored artifact files, and metadata.json is the caller’s metadata stamped with name, version, and created_at.

The version is staged under a temporary name and renamed into place, so a reader never sees a half-copied version directory.

Parameters

files: Mapping[str, bytes | Path]

Artifact entry name to content — raw bytes, a file to copy, or a directory to copy as a tree (its files are digested under <entry>/<relative path>).

metadata: Mapping[str, object]

The version’s provenance: dataset digest, config, metrics.

root: Path

The registry root the family lives under.

Returns

VersionInfo

The freshly registered VersionInfo.

registry.promote()

Atomically flips current to the named version (full name or v<NNN> prefix).

Usage

Source

registry.promote(name, version, *, root)

The flip writes a staging symlink under a unique per-promotion name and renames it over current, so a reader never sees a missing or half-written link. The family lock serialises it against register(), rollback(), prune(), and concurrent promotions, so no prune can delete the version being promoted.

registry.rollback()

Repoints current to the version registered just before the current promotion.

Usage

Source

registry.rollback(name, *, root)

Serialised against register(), prune(), and concurrent rollbacks by the family lock, the repoint itself reusing promote()’s atomic symlink swap.

Parameters

name: str

The artifact family to roll back.

root: Path

The registry root the family lives under.

Returns

VersionInfo

The now-promoted prior VersionInfo.

Raises

RegistryError

Nothing is promoted, or the current version is already the earliest.

registry.prune()

Deletes all but the newest keep versions of name, never the one current points to.

Usage

Source

registry.prune(name, *, keep=3, root)

The promoted version is always retained, even when it falls outside the newest-keep window. Doomed versions are renamed out of discovery and then removed under the family lock, so a prune never races a register(), promote(), or rollback() on the same family, and a reader never sees a half-deleted version.

Parameters

name: str

The artifact family to prune.

keep: int = 3

How many of the newest versions to retain.

root: Path

The registry root the family lives under.

Returns

tuple[VersionInfo, …]

The removed versions, oldest first.

Raises

RegistryError

keep is negative.

registry.components()

Every artifact family with at least one registered version under root, sorted.

Usage

Source

registry.components(root)

A family directory exists from the moment a registration stages its first version, so a registration that dies before its commit leaves the directory behind. Such a family has registered nothing and is not listed.

registry.RegistryError

The registry cannot satisfy the request: an unknown version, or an empty registration.

Usage

Source

registry.RegistryError()

Subclasses ~athome.errors.ResearchError — the registry grew out of the research harness, and an except ResearchError around a registry call predates its promotion to athome.registry, so it must keep catching. Outside research, catch this or ~athome.errors.AthomeError.