Skip to content

livery.toolroom.store._record

livery.toolroom.store._record

The tool record: one tool, every version tracked, each host's deployment and surface.

A record is inert data, authored in git as one file of JSON lines per tool, records/<tool>.jsonl: the first line is the tool axis, what does not move with a version; a version line is one version's arrival, forward and append-only; and the statement lines under a version line are what its reading changed, one option, one verb's own fields, one withdrawal or one absence per line. A deployment resolves through four layers, most specific winning: the tool's layout, the host's override of it, the version's override, and the version's override for one host. A version's surface, what its command line accepts, is carried one option at a time: a reading names the options and the verb fields the version changed and the tool's description when it changed, and everything else is inherited from the nearest earlier version that has a surface. Resolution is total and checked: loading a record resolves every host of every version and every version's surface, and refuses a host that resolves incomplete, an override that names a host or version the record does not carry, an override, a verb field or an option that restates the value it inherits, a withdrawal of what no earlier version has, a statement under a version that was not read, and a reading below the record's prime, the oldest version its history reaches. A record names a kind, per host an artifact with a mandatory digest, and the layout; it never runs a command. A version with no artifact is tracked for its surface alone: it has no host and nothing installs it.

Reach for livery.toolroom.store.Record.load to read a record, livery.toolroom.store.resolve for one host's deployment at one version, and livery.toolroom.store.surface_at for one version's whole surface; the rest is what a load validates.

Classes:

Name Description
RecordError

A record that breaks a rule; the message names the field.

Layout

One layer's layout fields; a field left None is inherited.

Artifact

One host's artifact for one version.

Deployment

One host's complete deployment of one version: the artifact and the layout.

Surface

One version's reading of the tool's command line, as its record carries it.

Observation

What one version accepted, whole, and who looked: its surface resolved.

Delta

One version's arrival: its artifacts, what it overrides, and its surface.

Record

A tool across every version tracked and every host it has.

Functions:

Name Description
default_mode

The materialisation mode a kind takes unless the record or the project says.

records_in

The record files under directory, by name; empty when it is not one.

resolve

The complete deployment of version on host, through the four layers.

observations

Every version's whole surface, in sequence, resolved through inheritance.

surface_at

The whole surface of version, or None when no reading was taken for it.

validate

Refuse a record that breaks a rule; every host of every version resolves.

artifact_format

What the artifact at url is by its suffix: zip, tar, or file.

class_name

The class a tool's stub declares: ruff_format is RuffFormat.

version_key

How versions order: the numeric run, OpenSSH's patchlevel, then the date.

host_key

The host key for a platform.system() and platform.machine() pair.

schema

The JSON schema of a record file's lines, for editor completion.

export_schema

Write schema() to path as indented JSON with a trailing newline.

Attributes:

Name Type Description
PLATFORMS

The operating systems a record may name.

ARCHES

The CPU architectures a record may name.

HOSTS

The six host keys, <platform>-<arch>. A record carries any subset.

KINDS

The installer kinds. A download is fetched by URL and lands in the

RUNTIMES

What an npm record runs on, and installs through: node, unless the

DOWNLOAD_KINDS

The kinds whose every host needs an artifact.

FORMATS

What a downloaded artifact is: sniffed from its URL's suffix unless

MODES

How a materialised tool reaches PATH: its entry points linked into the

PACKAGE_VAR

The one substitution a deployment's env values may carry: the install root.

VERSION_VAR
RECORD_SUFFIX

A record file's suffix: records/<tool>.jsonl, named by the tool.

LAYOUT_KEYS

The layout fields an override may set, in the record's key order.

SURFACE_PLATFORMS

The platforms a reading of a tool's command line may name.

VERB_KEYS

A verb's fields in a surface, in the record's key order; every one is present.

OPTION_KEYS

An option's fields in a surface, in the record's key order; every one is present.

TAR_SUFFIXES

The suffixes of the tar archives the store unpacks.

ARCHIVE_SUFFIXES

The suffixes of every archive the store unpacks.

PLATFORMS module-attribute

PLATFORMS = ('windows', 'macos', 'linux')

The operating systems a record may name.

ARCHES module-attribute

ARCHES = ('x64', 'arm')

The CPU architectures a record may name.

HOSTS module-attribute

HOSTS = ('macos-arm', 'macos-x64', 'linux-x64', 'linux-arm', 'windows-x64', 'windows-arm')

The six host keys, <platform>-<arch>. A record carries any subset.

KINDS module-attribute

KINDS = ('download', 'pypi', 'python', 'npm', 'dotnet', 'system-check')

The installer kinds. A download is fetched by URL and lands in the store: an archive is unpacked and its root hoisted, a bare file is saved under its file name, and the layout says what reaches the outside, entry points and paths for a program, env alone for a file that is never run (a CMake module, a plugin bundle). pypi installs a package from the index and python an interpreter, both through uv today; npm installs a package from npm through the runtime the record names; dotnet installs a .NET tool package from nuget.org through the dotnet SDK, its runtime; system-check verifies a system tool against min_version, and may carry an artifact for a host that has no system tool. A kind names where a tool comes from; how it is installed or run is a field of its own.

RUNTIMES module-attribute

RUNTIMES = ('node', 'bun', 'dotnet')

What an npm record runs on, and installs through: node, unless the record names bun; and what a dotnet record runs on, the dotnet SDK. The runtime is a tool of its own, locked beside the package and supplied first.

DOWNLOAD_KINDS module-attribute

DOWNLOAD_KINDS = frozenset({'download'})

The kinds whose every host needs an artifact.

FORMATS module-attribute

FORMATS = ('zip', 'tar', 'file')

What a downloaded artifact is: sniffed from its URL's suffix unless the layout's format says, for an artifact whose name lies.

MODES module-attribute

MODES = ('link', 'path', 'none')

How a materialised tool reaches PATH: its entry points linked into the checkout's bin directory, its own directories on PATH, or not at all, for a tool reached only through a typed handle.

PACKAGE_VAR module-attribute

PACKAGE_VAR = '$package'

The one substitution a deployment's env values may carry: the install root.

VERSION_VAR module-attribute

VERSION_VAR = '{version}'

RECORD_SUFFIX module-attribute

RECORD_SUFFIX = '.jsonl'

A record file's suffix: records/<tool>.jsonl, named by the tool.

LAYOUT_KEYS module-attribute

LAYOUT_KEYS = ('root', 'file', 'format', 'entry_points', 'paths', 'env', 'shims', 'exclude')

The layout fields an override may set, in the record's key order.

SURFACE_PLATFORMS module-attribute

SURFACE_PLATFORMS = ('Linux', 'macOS', 'Windows')

The platforms a reading of a tool's command line may name.

VERB_KEYS module-attribute

VERB_KEYS = ('help', 'wraps', 'positional', 'lead', 'options')

A verb's fields in a surface, in the record's key order; every one is present.

OPTION_KEYS module-attribute

OPTION_KEYS = ('flags', 'negation', 'help', 'type', 'default', 'choices')

An option's fields in a surface, in the record's key order; every one is present.

TAR_SUFFIXES module-attribute

TAR_SUFFIXES = ('.tar.gz', '.tgz', '.tar.xz', '.tar.bz2')

The suffixes of the tar archives the store unpacks.

ARCHIVE_SUFFIXES module-attribute

ARCHIVE_SUFFIXES = (*TAR_SUFFIXES, '.zip')

The suffixes of every archive the store unpacks.

RecordError

Bases: ValueError

A record that breaks a rule; the message names the field.

Layout dataclass

Layout(root: str | None = None, file: str | None = None, format: str | None = None, entry_points: tuple[str, ...] | None = None, paths: tuple[str, ...] | None = None, env: Mapping[str, str] | None = None, shims: Mapping[str, str] | None = None, exclude: tuple[str, ...] | None = None)

One layer's layout fields; a field left None is inherited.

Attributes:

Name Type Description
root str | None

The directory inside the archive to hoist to the install root; empty keeps the archive's own top. May carry VERSION_VAR, replaced by the version resolved, for an archive whose top directory is named after its version.

file str | None

The name a bare download (one file, no archive) is saved under, since the artifact carries none of its own.

format str | None

What the artifact is, one of FORMATS, for an artifact whose URL suffix would sniff wrong; empty sniffs.

entry_points tuple[str, ...] | None

Install-relative paths of the executables the deployment puts on PATH, annotated here and never discovered: they are what a bin directory links and what the collected tree marks executable on every platform.

paths tuple[str, ...] | None

Install-relative directories to put on PATH.

env Mapping[str, str] | None

Environment variables to set; a value may carry PACKAGE_VAR, the install root.

shims Mapping[str, str] | None

Link name to an executable the install carries, such as node to bun.

exclude tuple[str, ...] | None

Patterns of archive members left out before import, install-relative and forward-slashed, fnmatch style.

Methods:

Name Description
set_fields

The fields this layer sets, in LAYOUT_KEYS order.

to_json

The set fields as a JSON object, in LAYOUT_KEYS order.

from_json

A layer from its JSON object.

root class-attribute instance-attribute

root: str | None = None

file class-attribute instance-attribute

file: str | None = None

format class-attribute instance-attribute

format: str | None = None

entry_points class-attribute instance-attribute

entry_points: tuple[str, ...] | None = None

paths class-attribute instance-attribute

paths: tuple[str, ...] | None = None

env class-attribute instance-attribute

env: Mapping[str, str] | None = None

shims class-attribute instance-attribute

shims: Mapping[str, str] | None = None

exclude class-attribute instance-attribute

exclude: tuple[str, ...] | None = None

set_fields

set_fields() -> tuple[str, ...]

The fields this layer sets, in LAYOUT_KEYS order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def set_fields(self) -> tuple[str, ...]:
    """The fields this layer sets, in `LAYOUT_KEYS` order."""
    return tuple(key for key in LAYOUT_KEYS if getattr(self, key) is not None)

to_json

to_json() -> dict[str, Any]

The set fields as a JSON object, in LAYOUT_KEYS order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def to_json(self) -> dict[str, Any]:
    """The set fields as a JSON object, in `LAYOUT_KEYS` order."""
    out: dict[str, Any] = {}
    for key in LAYOUT_KEYS:
        value = getattr(self, key)
        if value is None:
            continue
        out[key] = list(value) if isinstance(value, tuple) else _plain(value)
    return out

from_json classmethod

from_json(value: Any, *, where: str) -> Layout

A layer from its JSON object.

Raises:

Type Description
RecordError

when the object is not a layout, naming where.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
@classmethod
def from_json(cls, value: Any, *, where: str) -> Layout:
    """A layer from its JSON object.

    Raises:
        RecordError: when the object is not a layout, naming *where*.
    """
    data = _object(value, LAYOUT_KEYS, where=where)
    return cls(
        _text(data["root"], where=f"{where} root") if "root" in data else None,
        _text(data["file"], where=f"{where} file") if "file" in data else None,
        _text(data["format"], where=f"{where} format")
        if "format" in data
        else None,
        _texts(data["entry_points"], where=f"{where} entry_points")
        if "entry_points" in data
        else None,
        _texts(data["paths"], where=f"{where} paths") if "paths" in data else None,
        _mapping(data["env"], where=f"{where} env") if "env" in data else None,
        _mapping(data["shims"], where=f"{where} shims")
        if "shims" in data
        else None,
        _texts(data["exclude"], where=f"{where} exclude")
        if "exclude" in data
        else None,
    )

Artifact dataclass

Artifact(url: str, sha256: str)

One host's artifact for one version.

Attributes:

Name Type Description
url str

Where the artifact downloads from.

sha256 str

The artifact's lowercase hex sha256, the object's name in the store; mandatory, a record without one is refused.

Methods:

Name Description
__post_init__
to_json

The artifact as a JSON object.

from_json

An artifact from its JSON object.

url instance-attribute

url: str

sha256 instance-attribute

sha256: str

__post_init__

__post_init__() -> None
Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def __post_init__(self) -> None:
    if not _SHA256.match(self.sha256):
        raise RecordError(
            f"artifact sha256 {self.sha256!r} is not 64 lowercase hex digits"
        )
    if not self.url:
        raise RecordError("artifact without a url")

to_json

to_json() -> dict[str, str]

The artifact as a JSON object.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def to_json(self) -> dict[str, str]:
    """The artifact as a JSON object."""
    return {"url": self.url, "sha256": self.sha256}

from_json classmethod

from_json(value: Any, *, where: str) -> Artifact

An artifact from its JSON object.

Raises:

Type Description
RecordError

when the object is not an artifact.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
@classmethod
def from_json(cls, value: Any, *, where: str) -> Artifact:
    """An artifact from its JSON object.

    Raises:
        RecordError: when the object is not an artifact.
    """
    data = _object(value, _ARTIFACT_KEYS, where=where)
    for required in _ARTIFACT_KEYS:
        if required not in data:
            raise RecordError(f"{where}: no {required}")
    try:
        return cls(
            _text(data["url"], where=f"{where} url"),
            _text(data["sha256"], where=f"{where} sha256"),
        )
    except RecordError as error:
        raise RecordError(f"{where}: {error}") from None

Deployment dataclass

Deployment(url: str, sha256: str, root: str, file: str, format: str, entry_points: tuple[str, ...], paths: tuple[str, ...], env: dict[str, str], shims: dict[str, str], exclude: tuple[str, ...])

One host's complete deployment of one version: the artifact and the layout.

Every field carries a value: the layers resolved it, and a load refused any host that would leave one open.

Attributes:

Name Type Description
url str

Where the artifact downloads from.

sha256 str

The artifact's sha256.

root str
file str
format str

See livery.toolroom.store.Layout; empty when the URL suffix decides.

entry_points tuple[str, ...]

See livery.toolroom.store.Layout; empty for a download reached through its env alone.

paths tuple[str, ...]

See livery.toolroom.store.Layout; empty likewise.

env dict[str, str]
shims dict[str, str]
exclude tuple[str, ...]

Methods:

Name Description
to_json

The deployment as a JSON object, every field, lists for the tuples.

from_json

A deployment from its JSON object, as the index carries it.

digest

The deployment's name: the digest of its canonical JSON.

url instance-attribute

url: str

sha256 instance-attribute

sha256: str

root instance-attribute

root: str

file instance-attribute

file: str

format instance-attribute

format: str

entry_points instance-attribute

entry_points: tuple[str, ...]

paths instance-attribute

paths: tuple[str, ...]

env instance-attribute

env: dict[str, str]

shims instance-attribute

shims: dict[str, str]

exclude instance-attribute

exclude: tuple[str, ...]

to_json

to_json() -> dict[str, Any]

The deployment as a JSON object, every field, lists for the tuples.

The canonical encoding of this object is what the index lands for the host and what a receipt's deployment digest names.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def to_json(self) -> dict[str, Any]:
    """The deployment as a JSON object, every field, lists for the tuples.

    The canonical encoding of this object is what the index lands
    for the host and what a receipt's deployment digest names.
    """
    return {
        "url": self.url,
        "sha256": self.sha256,
        "root": self.root,
        "file": self.file,
        "format": self.format,
        "entry_points": list(self.entry_points),
        "paths": list(self.paths),
        "env": dict(self.env),
        "shims": dict(self.shims),
        "exclude": list(self.exclude),
    }

from_json classmethod

from_json(value: Any, *, where: str) -> Deployment

A deployment from its JSON object, as the index carries it.

Raises:

Type Description
RecordError

when the object is not a deployment, naming where.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
@classmethod
def from_json(cls, value: Any, *, where: str) -> Deployment:
    """A deployment from its JSON object, as the index carries it.

    Raises:
        RecordError: when the object is not a deployment, naming *where*.
    """
    data = _object(value, _DEPLOYMENT_KEYS, where=where)
    for required in _DEPLOYMENT_KEYS:
        if required not in data:
            raise RecordError(f"{where}: no {required}")
    return cls(
        _text(data["url"], where=f"{where} url"),
        _text(data["sha256"], where=f"{where} sha256"),
        _text(data["root"], where=f"{where} root"),
        _text(data["file"], where=f"{where} file"),
        _text(data["format"], where=f"{where} format"),
        _texts(data["entry_points"], where=f"{where} entry_points"),
        _texts(data["paths"], where=f"{where} paths"),
        _mapping(data["env"], where=f"{where} env"),
        _mapping(data["shims"], where=f"{where} shims"),
        _texts(data["exclude"], where=f"{where} exclude"),
    )

digest

digest() -> Digest

The deployment's name: the digest of its canonical JSON.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def digest(self) -> Digest:
    """The deployment's name: the digest of its canonical JSON."""
    return digest_of(canonical(self.to_json()))

Surface dataclass

Surface(platforms: tuple[str, ...], extractor: int, help: str | None = None, verbs: Mapping[str, Mapping[str, Any] | None] = dict(), absent: Mapping[str, Mapping[str, tuple[str, ...]]] = dict())

One version's reading of the tool's command line, as its record carries it.

Sparse at the option: the tool's description, each verb's own fields and each option are inherited from the nearest earlier version with a surface unless this version sets them. A verb's first patch carries every field, since there is nothing to inherit; a field or an option set to the value it inherits is refused at load as dead data. The facts about the observation ride beside it and are never inherited.

Attributes:

Name Type Description
platforms tuple[str, ...]

The platforms that read this version, from SURFACE_PLATFORMS; at least one.

extractor int

The generation of the reader that took the reading, a positive integer.

help str | None

The tool's own description, or None to inherit it; the first surface of a record sets it.

verbs Mapping[str, Mapping[str, Any] | None]

Verb name to its patch: an object with any of the verb's own fields (help, wraps, positional, lead) and options, option name to the option whole, with OPTION_KEYS, or None for an option this version withdraws; or None for a verb withdrawn whole. A verb not named is inherited. The tool's own options hang off the verb named "".

absent Mapping[str, Mapping[str, tuple[str, ...]]]

Verb name to option name to the platforms that read the version and did not find that option; the option name "" stands for the verb itself. Every platform named is among platforms, every verb among the resolved verbs and every option among that verb's options.

platforms instance-attribute

platforms: tuple[str, ...]

extractor instance-attribute

extractor: int

help class-attribute instance-attribute

help: str | None = None

verbs class-attribute instance-attribute

verbs: Mapping[str, Mapping[str, Any] | None] = field(default_factory=dict)

absent class-attribute instance-attribute

absent: Mapping[str, Mapping[str, tuple[str, ...]]] = field(default_factory=dict)

Observation dataclass

Observation(version: str, date: str, platforms: tuple[str, ...], extractor: int, help: str, verbs: dict[str, dict[str, Any]], absent: dict[str, dict[str, tuple[str, ...]]])

What one version accepted, whole, and who looked: its surface resolved.

Attributes:

Name Type Description
version str

The version observed.

date str

The version's date, as its delta carries it.

platforms tuple[str, ...]

The platforms that read the version.

extractor int

The generation of the reader that took the reading.

help str

The tool's own description at this version.

verbs dict[str, dict[str, Any]]

Every verb whole, in name order, each in VERB_KEYS shape with its options in name order; treat it as read-only.

absent dict[str, dict[str, tuple[str, ...]]]

version instance-attribute

version: str

date instance-attribute

date: str

platforms instance-attribute

platforms: tuple[str, ...]

extractor instance-attribute

extractor: int

help instance-attribute

help: str

verbs instance-attribute

verbs: dict[str, dict[str, Any]]

absent instance-attribute

absent: dict[str, dict[str, tuple[str, ...]]]

Delta dataclass

Delta(sequence: int, version: str, date: str = '', artifacts: dict[str, Artifact] = dict(), layout: Layout = Layout(), host_layouts: dict[str, Layout] = dict(), surface: Surface | None = None)

One version's arrival: its artifacts, what it overrides, and its surface.

Attributes:

Name Type Description
sequence int

The delta's place in the record, from 1, consecutive: the version line's place in the file.

version str

The version string this delta adds.

date str

When the version arrived, YYYY-MM-DD; empty when the record does not know.

artifacts dict[str, Artifact]

Per host key, the artifact; the keys are the hosts this version has.

layout Layout

The version's override of the tool's layout.

host_layouts dict[str, Layout]

The version's override for one host each.

surface Surface | None

The version's reading of the command line, or None when no reading was taken; a delta carries an artifact, a surface, or both.

sequence instance-attribute

sequence: int

version instance-attribute

version: str

date class-attribute instance-attribute

date: str = ''

artifacts class-attribute instance-attribute

artifacts: dict[str, Artifact] = field(default_factory=dict)

layout class-attribute instance-attribute

layout: Layout = field(default_factory=Layout)

host_layouts class-attribute instance-attribute

host_layouts: dict[str, Layout] = field(default_factory=dict)

surface class-attribute instance-attribute

surface: Surface | None = None

hosts property

hosts: tuple[str, ...]

The hosts this version has, the artifacts' keys.

Record dataclass

Record(name: str, description: str = '', kind: str = 'download', package: str = '', mode: str = '', min_version: str = '', hosts: tuple[str, ...] = (), layout: Layout = Layout(), host_layouts: dict[str, Layout] = dict(), deltas: tuple[Delta, ...] = (), prime: str = '', runtime: str = '')

A tool across every version tracked and every host it has.

Loading a record validates it whole; see the module docstring for what a load refuses.

Attributes:

Name Type Description
name str

The tool's name, the record file's stem and the store's tools/<name>@<version> stem.

description str

One line on what the tool is.

kind str

One of KINDS.

package str

What a delegated kind's installer installs, when it differs from the tool's name: the PyPI or npm package.

runtime str

What an npm tool runs on and installs through, one of RUNTIMES; empty means node. A dotnet tool runs on dotnet, and may say so.

mode str

How the tool reaches PATH once materialised, one of MODES; empty takes the kind's default.

min_version str

The floor a system-check tool must reach.

hosts tuple[str, ...]

The host keys the tool has, from HOSTS.

layout Layout

The tool's layout, the layer every host and version inherits.

host_layouts dict[str, Layout]

The tool's override for one host each.

deltas tuple[Delta, ...]

The versions, in sequence.

prime str

The oldest version the reading history reaches: no version below it is read, so an option present at prime claims no since. Empty when the history reaches as far back as the releases go.

Methods:

Name Description
__post_init__
delta_for

The delta that added version.

hosts_of

The hosts version has.

to_json

The tool axis as a JSON object in the record's key order: the first line.

from_json

A record from the tool axis's JSON object and its deltas.

lines

The record as its file's lines: the axis, each version, its statements.

parse

A record from its file's text, one JSON object per line.

load

The record in the file path, records/<tool>.jsonl.

save

Write the record as <name>.jsonl under directory, one object per line.

name instance-attribute

name: str

description class-attribute instance-attribute

description: str = ''

kind class-attribute instance-attribute

kind: str = 'download'

package class-attribute instance-attribute

package: str = ''

mode class-attribute instance-attribute

mode: str = ''

min_version class-attribute instance-attribute

min_version: str = ''

hosts class-attribute instance-attribute

hosts: tuple[str, ...] = ()

layout class-attribute instance-attribute

layout: Layout = field(default_factory=Layout)

host_layouts class-attribute instance-attribute

host_layouts: dict[str, Layout] = field(default_factory=dict)

deltas class-attribute instance-attribute

deltas: tuple[Delta, ...] = ()

prime class-attribute instance-attribute

prime: str = ''

runtime class-attribute instance-attribute

runtime: str = ''

versions property

versions: tuple[str, ...]

The versions tracked, in sequence.

__post_init__

__post_init__() -> None
Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def __post_init__(self) -> None:
    validate(self)

delta_for

delta_for(version: str) -> Delta

The delta that added version.

Raises:

Type Description
RecordError

when the record does not track it, naming the versions it does.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def delta_for(self, version: str) -> Delta:
    """The delta that added *version*.

    Raises:
        RecordError: when the record does not track it, naming the
            versions it does.
    """
    for delta in self.deltas:
        if delta.version == version:
            return delta
    raise RecordError(
        f"{self.name}: no version {version!r}; the record tracks"
        f" {', '.join(self.versions) or 'none'}"
    )

hosts_of

hosts_of(version: str) -> tuple[str, ...]

The hosts version has.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def hosts_of(self, version: str) -> tuple[str, ...]:
    """The hosts *version* has."""
    return self.delta_for(version).hosts

to_json

to_json() -> dict[str, Any]

The tool axis as a JSON object in the record's key order: the first line.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def to_json(self) -> dict[str, Any]:
    """The tool axis as a JSON object in the record's key order: the first line."""
    out: dict[str, Any] = {
        "name": self.name,
        "description": self.description,
        "kind": self.kind,
    }
    if self.package:
        out["package"] = self.package
    if self.runtime:
        out["runtime"] = self.runtime
    if self.mode:
        out["mode"] = self.mode
    out["min_version"] = self.min_version
    if self.prime:
        out["prime"] = self.prime
    out["hosts"] = list(self.hosts)
    if self.layout.set_fields():
        out["layout"] = self.layout.to_json()
    if self.host_layouts:
        out["host_layouts"] = {k: v.to_json() for k, v in self.host_layouts.items()}
    return out

from_json classmethod

from_json(value: Any, deltas: tuple[Delta, ...] = (), *, where: str = 'line 1') -> Record

A record from the tool axis's JSON object and its deltas.

Raises:

Type Description
RecordError

when the object is not a tool axis, or the record does not validate.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
@classmethod
def from_json(
    cls, value: Any, deltas: tuple[Delta, ...] = (), *, where: str = "line 1"
) -> Record:
    """A record from the tool axis's JSON object and its *deltas*.

    Raises:
        RecordError: when the object is not a tool axis, or the
            record does not validate.
    """
    data = _object(value, _TOOL_KEYS, where=where)
    if "name" not in data:
        raise RecordError(f"{where}: no name")
    raw_hosts = data.get("host_layouts", {})
    if not isinstance(raw_hosts, dict):
        raise RecordError(f"{where}: host_layouts is not an object")
    return cls(
        _text(data["name"], where=f"{where} name"),
        _text(data.get("description", ""), where=f"{where} description"),
        _text(data.get("kind", "download"), where=f"{where} kind"),
        _text(data.get("package", ""), where=f"{where} package"),
        _text(data.get("mode", ""), where=f"{where} mode"),
        _text(data.get("min_version", ""), where=f"{where} min_version"),
        _texts(data.get("hosts", []), where=f"{where} hosts"),
        Layout.from_json(data.get("layout", {}), where=f"{where} layout"),
        {
            str(k): Layout.from_json(v, where=f"{where} host_layouts[{k}]")
            for k, v in raw_hosts.items()
        },
        deltas,
        _text(data.get("prime", ""), where=f"{where} prime"),
        runtime=_text(data.get("runtime", ""), where=f"{where} runtime"),
    )

lines

lines() -> list[dict[str, Any]]

The record as its file's lines: the axis, each version, its statements.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def lines(self) -> list[dict[str, Any]]:
    """The record as its file's lines: the axis, each version, its statements."""
    out: list[dict[str, Any]] = [self.to_json()]
    for delta in self.deltas:
        out.append(_version_line(delta))
        if delta.surface is not None:
            out.extend(_statements(delta.surface))
    return out

parse classmethod

parse(text: str, *, where: str) -> Record

A record from its file's text, one JSON object per line.

Raises:

Type Description
RecordError

naming where and the line, for a line that is not JSON, a statement before any version line or under a version that was not read, an option stated twice, or a record that does not validate.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
@classmethod
def parse(cls, text: str, *, where: str) -> Record:
    """A record from its file's text, one JSON object per line.

    Raises:
        RecordError: naming *where* and the line, for a line that is
            not JSON, a statement before any version line or under
            a version that was not read, an option stated twice,
            or a record that does not validate.
    """
    lines = [line for line in text.splitlines() if line.strip()]
    if not lines:
        raise RecordError(f"{where}: empty")
    objects: list[Any] = []
    for number, line in enumerate(lines, start=1):
        try:
            objects.append(json.loads(line))
        except json.JSONDecodeError as error:
            raise RecordError(
                f"{where} line {number}: not JSON ({error})"
            ) from None
    deltas: list[Delta] = []
    pending: _Pending | None = None
    for number, obj in enumerate(objects[1:], start=2):
        at = f"{where} line {number}"
        if not isinstance(obj, dict):
            raise RecordError(f"{at}: not a JSON object")
        if "version" in obj:
            if pending is not None:
                deltas.append(pending.delta(len(deltas) + 1))
            pending = _Pending.from_json(obj, where=at)
            continue
        if "verb" not in obj:
            raise RecordError(f"{at}: neither a version line nor a statement")
        if pending is None:
            raise RecordError(f"{at}: a statement before any version line")
        pending.statement(obj, where=at)
    if pending is not None:
        deltas.append(pending.delta(len(deltas) + 1))
    return cls.from_json(objects[0], tuple(deltas), where=f"{where} line 1")

load classmethod

load(path: Path) -> Record

The record in the file path, records/<tool>.jsonl.

Raises:

Type Description
RecordError

naming the file, for a directory, a file that is not a record, a record named other than its file, or one that does not validate.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
@classmethod
def load(cls, path: Path) -> Record:
    """The record in the file *path*, `records/<tool>.jsonl`.

    Raises:
        RecordError: naming the file, for a directory, a file that
            is not a record, a record named other than its file, or
            one that does not validate.
    """
    if path.is_dir():
        raise RecordError(
            f"{path}: a directory, not a record file; a record is"
            f" `<tool>{RECORD_SUFFIX}`"
        )
    if not path.is_file():
        raise RecordError(f"{path}: no such record")
    record = cls.parse(path.read_text("utf-8"), where=path.name)
    stem = path.name.removesuffix(RECORD_SUFFIX)
    if record.name != stem:
        raise RecordError(
            f"{path.name}: the record is named {record.name!r}, its file {stem!r}"
        )
    return record

save

save(directory: Path) -> None

Write the record as <name>.jsonl under directory, one object per line.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def save(self, directory: Path) -> None:
    """Write the record as `<name>.jsonl` under *directory*, one object per line."""
    directory.mkdir(parents=True, exist_ok=True)
    text = "".join(_line(obj) for obj in self.lines())
    (directory / f"{self.name}{RECORD_SUFFIX}").write_text(text, encoding="utf-8")

default_mode

default_mode(kind: str, paths: tuple[str, ...] = ()) -> str

The materialisation mode a kind takes unless the record or the project says.

A download with paths puts them on PATH, since a tool finds its own data by its real path; one with none is reached through its env alone and takes none; a system tool is on PATH already; an installer's tool puts its directories on PATH.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def default_mode(kind: str, paths: tuple[str, ...] = ()) -> str:
    """The materialisation mode a kind takes unless the record or the project says.

    A download with *paths* puts them on PATH, since a tool finds its
    own data by its real path; one with none is reached through its
    env alone and takes `none`; a system tool is on PATH already; an
    installer's tool puts its directories on PATH.
    """
    if kind == "download":
        return "path" if paths else "none"
    if kind == "system-check":
        return "none"
    return "path"

records_in

records_in(directory: Path) -> list[Path]

The record files under directory, by name; empty when it is not one.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def records_in(directory: Path) -> list[Path]:
    """The record files under *directory*, by name; empty when it is not one."""
    if not directory.is_dir():
        return []
    return sorted(
        path
        for path in directory.iterdir()
        if path.suffix == RECORD_SUFFIX and path.is_file()
    )

resolve

resolve(record: Record, version: str, host: str) -> Deployment

The complete deployment of version on host, through the four layers.

Raises:

Type Description
RecordError

when the record does not track version, or version has no host, naming what it does have.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def resolve(record: Record, version: str, host: str) -> Deployment:
    """The complete deployment of *version* on *host*, through the four layers.

    Raises:
        RecordError: when the record does not track *version*, or
            *version* has no *host*, naming what it does have.
    """
    delta = record.delta_for(version)
    if host not in delta.artifacts:
        raise RecordError(
            f"{record.name} {version}: no host {host}; the version has"
            f" {', '.join(delta.hosts) or 'none'}"
        )
    values, _ = _resolve_fields(record, delta, host)
    artifact = delta.artifacts[host]
    return Deployment(
        artifact.url,
        artifact.sha256,
        str(values["root"]).replace(VERSION_VAR, version),
        str(values["file"]),
        str(values["format"]),
        tuple(values["entry_points"]),
        tuple(values["paths"]),
        dict(values["env"]),
        dict(values["shims"]),
        tuple(values["exclude"]),
    )

observations

observations(record: Record) -> tuple[Observation, ...]

Every version's whole surface, in sequence, resolved through inheritance.

A version whose delta carries no surface is left out: nothing was read for it, and inheriting a reading would claim one.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def observations(record: Record) -> tuple[Observation, ...]:
    """Every version's whole surface, in sequence, resolved through inheritance.

    A version whose delta carries no surface is left out: nothing was
    read for it, and inheriting a reading would claim one.
    """
    out: list[Observation] = []
    help_ = ""
    verbs: dict[str, dict[str, Any]] = {}
    for delta in record.deltas:
        surface = delta.surface
        if surface is None:
            continue
        if surface.help is not None:
            help_ = surface.help
        for name, patch in surface.verbs.items():
            if patch is None:
                verbs.pop(name, None)
            else:
                verbs[name] = _canonical_verb(_applied(verbs.get(name), patch))
        out.append(
            Observation(
                delta.version,
                delta.date,
                surface.platforms,
                surface.extractor,
                help_,
                {name: verbs[name] for name in sorted(verbs)},
                {
                    verb: {option: tuple(who) for option, who in options.items()}
                    for verb, options in surface.absent.items()
                },
            )
        )
    return tuple(out)

surface_at

surface_at(record: Record, version: str) -> Observation | None

The whole surface of version, or None when no reading was taken for it.

Raises:

Type Description
RecordError

when the record does not track version, naming the versions it does.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def surface_at(record: Record, version: str) -> Observation | None:
    """The whole surface of *version*, or `None` when no reading was taken for it.

    Raises:
        RecordError: when the record does not track *version*, naming
            the versions it does.
    """
    record.delta_for(version)
    for observation in observations(record):
        if observation.version == version:
            return observation
    return None

validate

validate(record: Record) -> None

Refuse a record that breaks a rule; every host of every version resolves.

Raises:

Type Description
RecordError

naming the first rule broken.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def validate(record: Record) -> None:
    """Refuse a record that breaks a rule; every host of every version resolves.

    Raises:
        RecordError: naming the first rule broken.
    """
    where = record.name
    if not record.name:
        raise RecordError("a record needs a name")
    if record.kind not in KINDS:
        raise RecordError(
            f"{where}: kind {record.kind!r} is not one of {', '.join(KINDS)}"
        )
    if record.mode and record.mode not in MODES:
        raise RecordError(
            f"{where}: mode {record.mode!r} is not one of {', '.join(MODES)}"
        )
    if record.runtime and record.runtime not in RUNTIMES:
        raise RecordError(
            f"{where}: runtime {record.runtime!r} is not one of {', '.join(RUNTIMES)}"
        )
    if record.runtime and record.kind not in ("npm", "dotnet"):
        raise RecordError(
            f"{where}: a runtime is named by an npm or a dotnet record; this one is"
            f" {record.kind!r}"
        )
    if record.kind == "npm" and record.runtime == "dotnet":
        raise RecordError(f"{where}: an npm record runs on node or bun, not dotnet")
    if record.kind == "dotnet" and record.runtime not in ("", "dotnet"):
        raise RecordError(
            f"{where}: a dotnet record runs on dotnet, not {record.runtime!r}"
        )
    for host in record.hosts:
        if host not in HOSTS:
            raise RecordError(
                f"{where}: host {host!r} is not one of {', '.join(HOSTS)}"
            )
    if len(set(record.hosts)) != len(record.hosts):
        raise RecordError(f"{where}: a host is listed twice")
    for host in record.host_layouts:
        if host not in record.hosts:
            raise RecordError(
                f"{where}: the tool's {host} layout names a host the record"
                f" lacks; it has {', '.join(record.hosts) or 'none'}. List {host}"
                " in the record's `hosts` first, and `toolroom.artifacts` records"
                " its artifact"
            )
    seen: set[str] = set()
    help_: str | None = None
    verbs: dict[str, dict[str, Any]] = {}
    for index, delta in enumerate(record.deltas, start=1):
        at = f"{where} version {delta.version}"
        if delta.sequence != index:
            raise RecordError(
                f"{at}: out of sequence; expected {index}, the versions run"
                " consecutively from 1"
            )
        if delta.version in seen:
            raise RecordError(f"{at}: version {delta.version} was added before")
        seen.add(delta.version)
        for host in delta.artifacts:
            if host not in record.hosts:
                raise RecordError(
                    f"{at}: an artifact for {host}, a host the record lacks; it"
                    f" has {', '.join(record.hosts) or 'none'}"
                )
        for host in delta.host_layouts:
            if host not in delta.artifacts:
                raise RecordError(
                    f"{at}: a {host} layout for a host the version lacks; it has"
                    f" {', '.join(delta.hosts) or 'none'}"
                )
        if delta.layout.set_fields() and not delta.artifacts:
            raise RecordError(f"{at}: a layout for a version with no host")
        if not delta.artifacts and delta.surface is None:
            raise RecordError(f"{at}: a version with neither an artifact nor a surface")
        for host in delta.hosts:
            values, restated = _resolve_fields(record, delta, host)
            if restated:
                raise RecordError(f"{at} {host}: {restated[0]}")
            missing = _incomplete(record, values, delta.artifacts[host].url)
            if missing:
                raise RecordError(
                    f"{at} {host}: resolves incomplete, {missing}; every host of"
                    " every version must resolve to a whole deployment"
                )
        if delta.surface is not None:
            if record.prime and version_key(delta.version) < version_key(record.prime):
                raise RecordError(
                    f"{at}: read below prime {record.prime}; the history reaches"
                    " no further back"
                )
            help_ = _validate_surface(delta.surface, help_, verbs, at=f"{at} read")
    # A tool-level layout that no version and host ever reads is not a
    # restatement, so a tool with no version is validated on its own.
    if not record.deltas:
        _, restated = _resolve_fields(
            record, Delta(1, "-"), record.hosts[0] if record.hosts else "-"
        )
        if restated:
            raise RecordError(f"{where}: {restated[0]}")

artifact_format

artifact_format(url: str) -> str

What the artifact at url is by its suffix: zip, tar, or file.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def artifact_format(url: str) -> str:
    """What the artifact at *url* is by its suffix: `zip`, `tar`, or `file`."""
    name = url.rsplit("/", 1)[-1].lower()
    if name.endswith(".zip"):
        return "zip"
    if name.endswith(TAR_SUFFIXES):
        return "tar"
    return "file"

class_name

class_name(name: str) -> str

The class a tool's stub declares: ruff_format is RuffFormat.

Each part of the name, split on _ and -, is title-cased and the parts are joined. The workshop composes a typing package's index from this rule, and the bench renders the stub's class with it, so the two agree without either reading the other's output.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def class_name(name: str) -> str:
    """The class a tool's stub declares: `ruff_format` is `RuffFormat`.

    Each part of the name, split on `_` and `-`, is title-cased and the
    parts are joined. The workshop composes a typing package's index
    from this rule, and the bench renders the stub's class with it, so
    the two agree without either reading the other's output.
    """
    return "".join(part.title() for part in name.replace("-", "_").split("_"))

version_key

version_key(version: str, date: str = '') -> tuple[tuple[int, ...], int, str]

How versions order: the numeric run, OpenSSH's patchlevel, then the date.

version_tuple reads two builds of one base as equal and leaves the tie to the caller; the patchlevel places 9.9p2 after 9.9p1, and the date breaks what remains. A record's deltas run in this order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def version_key(version: str, date: str = "") -> tuple[tuple[int, ...], int, str]:
    """How versions order: the numeric run, OpenSSH's patchlevel, then the date.

    `version_tuple` reads two builds of one base as equal and leaves the
    tie to the caller; the patchlevel places `9.9p2` after `9.9p1`, and
    the date breaks what remains. A record's deltas run in this order.
    """
    match = _PATCHLEVEL.search(version)
    return version_tuple(version), int(match[1]) if match else 0, date

host_key

host_key(system: str, machine: str) -> str

The host key for a platform.system() and platform.machine() pair.

Raises:

Type Description
RecordError

for a platform or architecture no record can name.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def host_key(system: str, machine: str) -> str:
    """The host key for a `platform.system()` and `platform.machine()` pair.

    Raises:
        RecordError: for a platform or architecture no record can name.
    """
    systems = {"Windows": "windows", "Darwin": "macos", "Linux": "linux"}
    machines = {
        "amd64": "x64",
        "x86_64": "x64",
        "x64": "x64",
        "arm64": "arm",
        "aarch64": "arm",
    }
    platform = systems.get(system)
    arch = machines.get(machine.lower())
    if platform is None or arch is None:
        raise RecordError(f"no record names the host {system}/{machine}")
    return f"{platform}-{arch}"

schema

schema() -> dict[str, Any]

The JSON schema of a record file's lines, for editor completion.

One schema, three shapes under $defs: Tool for the first line, Version for a version line and Statement for a line under it; a line is one of the three. Every object is closed to unknown keys.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def schema() -> dict[str, Any]:
    """The JSON schema of a record file's lines, for editor completion.

    One schema, three shapes under `$defs`: `Tool` for the first line,
    `Version` for a version line and `Statement` for a line under it;
    a line is one of the three. Every object is closed to unknown keys.
    """
    layout = {
        "type": "object",
        "additionalProperties": False,
        "properties": {
            "root": {"type": "string"},
            "file": {"type": "string"},
            "format": {"type": "string", "enum": list(FORMATS)},
            "entry_points": {"type": "array", "items": {"type": "string"}},
            "paths": {"type": "array", "items": {"type": "string"}},
            "env": {"type": "object", "additionalProperties": {"type": "string"}},
            "shims": {"type": "object", "additionalProperties": {"type": "string"}},
            "exclude": {"type": "array", "items": {"type": "string"}},
        },
    }
    artifact = {
        "type": "object",
        "additionalProperties": False,
        "required": ["url", "sha256"],
        "properties": {
            "url": {"type": "string", "minLength": 1},
            "sha256": {"type": "string", "pattern": _SHA256.pattern},
        },
    }
    host_layouts = {
        "type": "object",
        "propertyNames": {"enum": list(HOSTS)},
        "additionalProperties": {"$ref": "#/$defs/Layout"},
    }
    tool = {
        "type": "object",
        "additionalProperties": False,
        "required": ["name", "hosts"],
        "properties": {
            "name": {"type": "string", "minLength": 1},
            "description": {"type": "string", "default": ""},
            "kind": {"type": "string", "enum": list(KINDS), "default": "download"},
            "package": {"type": "string", "default": ""},
            "runtime": {"type": "string", "enum": list(RUNTIMES)},
            "mode": {"type": "string", "enum": list(MODES)},
            "min_version": {"type": "string", "default": ""},
            "prime": {"type": "string", "default": ""},
            "hosts": {
                "type": "array",
                "items": {"type": "string", "enum": list(HOSTS)},
                "uniqueItems": True,
            },
            "layout": {"$ref": "#/$defs/Layout"},
            "host_layouts": host_layouts,
        },
    }
    option = {
        "flags": {"type": "array", "items": {"type": "string"}},
        "negation": {"type": "string"},
        "help": {"type": "string"},
        "type": {"type": "string"},
        "default": {},
        "choices": {"type": "array", "items": {"type": "string"}},
    }
    platforms = {
        "type": "array",
        "items": {"type": "string", "enum": list(SURFACE_PLATFORMS)},
        "minItems": 1,
        "uniqueItems": True,
    }
    version = {
        "type": "object",
        "additionalProperties": False,
        "required": ["version"],
        "properties": {
            "version": {"type": "string", "minLength": 1},
            "date": {"type": "string", "default": ""},
            "artifacts": {
                "type": "object",
                "propertyNames": {"enum": list(HOSTS)},
                "additionalProperties": {"$ref": "#/$defs/Artifact"},
            },
            "layout": {"$ref": "#/$defs/Layout"},
            "host_layouts": host_layouts,
            "read": {
                "type": "object",
                "additionalProperties": False,
                "required": ["platforms", "extractor"],
                "properties": {
                    "platforms": platforms,
                    "extractor": {"type": "integer", "minimum": 1},
                    "help": {"type": "string"},
                },
            },
        },
    }
    statement = {
        "type": "object",
        "additionalProperties": False,
        "required": ["verb"],
        "properties": {
            "verb": {"type": "string"},
            "option": {"type": "string"},
            "gone": {"const": True},
            "absent": platforms,
            "wraps": {"type": "boolean"},
            "positional": {"type": "string"},
            "lead": {"type": "string"},
            **option,
        },
    }
    return {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Record",
        "oneOf": [
            {"$ref": "#/$defs/Tool"},
            {"$ref": "#/$defs/Version"},
            {"$ref": "#/$defs/Statement"},
        ],
        "$defs": {
            "Layout": layout,
            "Artifact": artifact,
            "Tool": tool,
            "Version": version,
            "Statement": statement,
        },
    }

export_schema

export_schema(path: Path) -> None

Write schema() to path as indented JSON with a trailing newline.

Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
def export_schema(path: Path) -> None:
    """Write `schema()` to *path* as indented JSON with a trailing newline."""
    path.write_text(json.dumps(schema(), indent=2) + "\n", encoding="utf-8")