## Registry ## registry.VersionInfo One registered artifact version. Usage ``` python registry.VersionInfo( name, version, path, metadata, ) ``` #### Attributes `name: str` The artifact family (the experiment or model name). `version: str` The version directory name, `v--`. `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 ``` python registry.versions(name, *, root) ``` ## registry.current() The promoted version the [current](registry.md#athome.registry.current) symlink names, or `None` when nothing is promoted. Usage ``` python registry.current(name, *, root) ``` ## registry.register() Writes a new immutable version directory under `root`; never flips [current](registry.md#athome.registry.current). Usage ``` python 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 `/`). `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.md#athome.registry.VersionInfo). ## registry.promote() Atomically flips [current](registry.md#athome.registry.current) to the named version (full name or `v` prefix). Usage ``` python registry.promote(name, version, *, root) ``` The flip writes a staging symlink under a unique per-promotion name and renames it over [current](registry.md#athome.registry.current), so a reader never sees a missing or half-written link. The family lock serialises it against [register()](train.md#athome.train.register), [rollback()](registry.md#athome.registry.rollback), [prune()](registry.md#athome.registry.prune), and concurrent promotions, so no prune can delete the version being promoted. ## registry.rollback() Repoints [current](registry.md#athome.registry.current) to the version registered just before the current promotion. Usage ``` python registry.rollback(name, *, root) ``` Serialised against [register()](train.md#athome.train.register), [prune()](registry.md#athome.registry.prune), and concurrent rollbacks by the family lock, the repoint itself reusing [promote()](registry.md#athome.registry.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](registry.md#athome.registry.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](registry.md#athome.registry.current) points to. Usage ``` python 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()](train.md#athome.train.register), [promote()](registry.md#athome.registry.promote), or [rollback()](registry.md#athome.registry.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 ``` python 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 ``` python 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`.