Skip to content

livery.toolroom.store

livery.toolroom.store

The pinned tool store over strongroom.

A record names a tool, every version tracked, and per version and host the artifact's URL and sha256 with the deployment resolved through the record's layers; the store lands the artifact by that digest, extracts it, collects it as a tree, and names the tree under tools/<name>@<version> in a machine-wide strongroom store whose home this package lays out; a checkout's bin directory links the executables, and a delta says what to put on PATH.

Reach for livery.toolroom.store.Record to read a record, livery.toolroom.store.resolve for one host's deployment, livery.toolroom.store.surface_at for one version's command line, livery.toolroom.store.Catalogue for what a consumer resolves against, livery.toolroom.store.resolve_lock for the repository's lock, livery.toolroom.store.read_table for a directory's [toolroom] table, livery.toolroom.store.Home for the store's directories, and livery.toolroom.store.Store to install, link, emit and fetch.

Classes:

Name Description
Catalogue

Every tool a consumer may require, with what each version resolves to.

CatalogueError

An index or a records directory that cannot be read as a catalogue.

Listed

One tool as the catalogue lists it.

DamagedView

A view the disk no longer holds whole: tool, version, the paths missing.

Delta

What a set of installs adds to an environment.

Ensured

A tool version the store supplies.

Event

One step of the engine's work, as it starts or resolves.

Fetched

One artifact fetch landed or found in the mirror.

Store

The tool store: a home's objects, refs and views, driven by specs.

StoreError

A tool the store cannot supply; the message names the tool and the reason.

FetchError

A URL not read after the tries; the message names it and the last cause.

UnpackError

An archive that will not unpack; the message names the archive and why.

Home

The store's directories under one root.

Graph

The resolved graph of a delegated tool's version, as the lock names it.

Lock

The repository's lock: the hosts it locks for and one version per tool.

Locked

One tool as the lock holds it.

LockError

A requirement the catalogue cannot satisfy; the message names why.

Requirement

One site's requirement of a tool: a floor, or any version, on some hosts or all.

Artifact

One host's artifact for one version.

RecordDelta

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

Deployment

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

Layout

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

Observation

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

Record

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

RecordError

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

Surface

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

Scope

The hosts a requirement is limited to, as written after @.

Spec

One requirement as the grammar spells it: name[options]?>=floor@scope.

SpecError

A spelling the requirement grammar does not read; the message names why.

Option

One option of one tool verb, as the tool describes it.

ToolSpec

Everything footman knows about one tool, from the tool itself.

Verb

A subcommand: mkdocs build, ruff check.

NameCollision

A verb would generate a class named like one of the stub's imports.

TableError

A configuration file the table cannot be read from; the message names it.

Functions:

Name Description
build_current

Whether the index at index stands as its build record fingerprints it.

index_source

Where a workspace reads its catalogue, as its [toolroom] index names it.

is_records

Whether source is a directory of records rather than an index.

read_pointer

The pointer document at source, a directory or an HTTP base URL.

bun_global_project

The global project bun installs into under install_root, made empty.

npm_cli

The npm-cli.js node ships beside node, in either layout node publishes.

silent

The default progress: drop the event.

api_headers

The headers a read of url sends: a user agent, and GitHub's token for its API.

fetch_bytes

The bytes at url, read whole; a transient failure is tried tries times.

fetch_file

Download url into into, named by its last path segment; the file.

fetch_json

The JSON at url, whatever shape the endpoint answers with.

unpack

Extract archive, a zip or a tar, whole into into.

tree_fingerprint

The fingerprint of paths, each a file or a directory walked whole.

resolve_lock

The lock for requirements against catalogue, on hosts.

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.

default_mode

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

export_schema

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

host_key

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

observations

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

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.

schema

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

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.

version_key

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

render

The full text of stubs/<tool>.pyi for spec.

render_observation

The stub of name at one observed version, exactly as that version read.

spec_from

The spec a surface describes: the shape the records and the index hold.

read_table

The [toolroom] table of directory; empty when it declares none.

Attributes:

Name Type Description
BUILD_FILE

The build's record beside the pointer: what it fingerprinted, so a gate can ask.

POINTER

The pointer document at an index's root, naming each tool's tree.

LINKS

The manifest a bin directory keeps of the links the engine made there.

Progress

Receives every event; must not raise.

TOOLS

The namespace of installed tools: tools/<name>@<version> names the

URLS

The namespace of URL-keyed downloads, the convention strongroom

GRAPHS

The directory beside the lock holding one resolved graph per delegated tool.

LOCK_FILE

The lock's name at the repository root.

ARCHES

The CPU architectures a record may name.

ARCHIVE_SUFFIXES

The suffixes of every archive the store unpacks.

DOWNLOAD_KINDS

The kinds whose every host needs an artifact.

FORMATS

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

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

LAYOUT_KEYS

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

MODES

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

OPTION_KEYS

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

PACKAGE_VAR

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

PLATFORMS

The operating systems a record may name.

RECORD_SUFFIX

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

RUNTIMES

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

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.

VERSION_VAR
CONFIG_FILES

The files a directory's table is read from; the first one present wins.

SCHEMA_FRAGMENT

The table's schema: its keys in the root, package and extension contracts.

TABLE

The table every contract keeps the tool configuration under.

__version__

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

BUILD_FILE module-attribute

BUILD_FILE = 'build.json'

The build's record beside the pointer: what it fingerprinted, so a gate can ask.

POINTER module-attribute

POINTER = 'pointer.json'

The pointer document at an index's root, naming each tool's tree.

LINKS = '.links.json'

The manifest a bin directory keeps of the links the engine made there.

Progress module-attribute

Progress = Callable[[Event], None]

Receives every event; must not raise.

TOOLS module-attribute

TOOLS = 'tools'

The namespace of installed tools: tools/<name>@<version> names the extracted archive's tree; write-once, so a version never changes under a checkout that pinned it. tools/index/<name> names the tree the catalogue last read for the tool, so a sweep keeps the records, the versions and the surfaces a read fetched.

URLS module-attribute

URLS = 'urls'

The namespace of URL-keyed downloads, the convention strongroom publishes; volatile.

GRAPHS module-attribute

GRAPHS = 'toolroom.graphs'

The directory beside the lock holding one resolved graph per delegated tool.

LOCK_FILE module-attribute

LOCK_FILE = 'toolroom.lock'

The lock's name at the repository root.

ARCHES module-attribute

ARCHES = ('x64', 'arm')

The CPU architectures a record may name.

ARCHIVE_SUFFIXES module-attribute

ARCHIVE_SUFFIXES = (*TAR_SUFFIXES, '.zip')

The suffixes of every archive the store unpacks.

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.

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.

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.

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.

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.

PACKAGE_VAR module-attribute

PACKAGE_VAR = '$package'

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

PLATFORMS module-attribute

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

The operating systems a record may name.

RECORD_SUFFIX module-attribute

RECORD_SUFFIX = '.jsonl'

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

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.

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.

VERSION_VAR module-attribute

VERSION_VAR = '{version}'

CONFIG_FILES module-attribute

CONFIG_FILES = ('workshop.toml', 'toolroom.toml')

The files a directory's table is read from; the first one present wins.

SCHEMA_FRAGMENT module-attribute

SCHEMA_FRAGMENT = Path(__file__).with_name('contract.toml')

The table's schema: its keys in the root, package and extension contracts.

TABLE module-attribute

TABLE = 'toolroom'

The table every contract keeps the tool configuration under.

__all__ module-attribute

__all__ = ['ARCHES', 'ARCHIVE_SUFFIXES', 'BUILD_FILE', 'CONFIG_FILES', 'DOWNLOAD_KINDS', 'FORMATS', 'GRAPHS', 'HOSTS', 'KINDS', 'LAYOUT_KEYS', 'LINKS', 'LOCK_FILE', 'MODES', 'OPTION_KEYS', 'PACKAGE_VAR', 'PLATFORMS', 'POINTER', 'RECORD_SUFFIX', 'RUNTIMES', 'SCHEMA_FRAGMENT', 'SURFACE_PLATFORMS', 'TABLE', 'TOOLS', 'URLS', 'VERB_KEYS', 'VERSION_VAR', 'Artifact', 'Catalogue', 'CatalogueError', 'DamagedView', 'Delta', 'Deployment', 'Ensured', 'Event', 'FetchError', 'Fetched', 'Graph', 'Home', 'Layout', 'Listed', 'Lock', 'LockError', 'Locked', 'NameCollision', 'Observation', 'Option', 'Progress', 'Record', 'RecordDelta', 'RecordError', 'Requirement', 'Scope', 'Spec', 'SpecError', 'Store', 'StoreError', 'Surface', 'TableError', 'ToolSpec', 'UnpackError', 'Verb', '__version__', 'api_headers', 'artifact_format', 'build_current', 'bun_global_project', 'class_name', 'default_mode', 'export_schema', 'fetch_bytes', 'fetch_file', 'fetch_json', 'host_key', 'index_source', 'is_records', 'npm_cli', 'observations', 'read_pointer', 'read_table', 'records_in', 'render', 'render_observation', 'resolve', 'resolve_lock', 'schema', 'silent', 'spec_from', 'surface_at', 'tree_fingerprint', 'unpack', 'validate', 'version_key']

__version__ module-attribute

__version__ = '0.5.0'

Catalogue dataclass

Catalogue(tools: Mapping[str, Listed], _deployments: dict[tuple[str, str, str], Deployment] = dict(), _store: Store | None = None, _records: dict[str, Record] = dict())

Every tool a consumer may require, with what each version resolves to.

Attributes:

Name Type Description
tools Mapping[str, Listed]

Tool name to its listing.

Methods:

Name Description
listed

The listing of name.

deployment

The deployment of name at version on host.

stub

The stub of name at version, rendered from the version's surface.

at

The catalogue at source, whichever it holds: records, or an index.

of_records

The catalogue of the records under directory, the authoring site's.

of_index

The catalogue of the index at source, a directory or an HTTP base URL.

tools instance-attribute

tools: Mapping[str, Listed]

listed

listed(name: str) -> Listed

The listing of name.

Raises:

Type Description
CatalogueError

when the catalogue has no such tool, naming what it has.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def listed(self, name: str) -> Listed:
    """The listing of *name*.

    Raises:
        CatalogueError: when the catalogue has no such tool, naming
            what it has.
    """
    found = self.tools.get(name)
    if found is None:
        known = ", ".join(sorted(self.tools)) or "nothing"
        raise CatalogueError(f"no record of {name}; the catalogue lists {known}")
    return found

deployment

deployment(name: str, version: str, host: str) -> Deployment

The deployment of name at version on host.

From the records it is resolved; from the index it is the blob the tool's tree names, fetched through the sources.

Raises:

Type Description
CatalogueError

when the version has no such host, or the blob cannot be read.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def deployment(self, name: str, version: str, host: str) -> Deployment:
    """The deployment of *name* at *version* on *host*.

    From the records it is resolved; from the index it is the blob
    the tool's tree names, fetched through the sources.

    Raises:
        CatalogueError: when the version has no such host, or the
            blob cannot be read.
    """
    listed = self.listed(name)
    digest = listed.hosts.get(version, {}).get(host)
    if digest is None:
        has = ", ".join(listed.hosts.get(version, {})) or "none"
        raise CatalogueError(
            f"{name} {version}: no host {host}; the version has {has}"
        )
    held = self._deployments.get((name, version, host))
    if held is not None:
        return held
    if self._store is None:  # pragma: no cover - records fill every deployment
        raise CatalogueError(f"{name} {version} {host}: no deployment was read")
    try:
        data = json.loads(self._store.fetch(digest).read_bytes())
    except Exception as error:
        raise CatalogueError(
            f"{name} {version} {host}: the deployment {digest} cannot be read:"
            f" {error}"
        ) from error
    found = Deployment.from_json(data, where=f"{name} {version} {host}")
    self._deployments[(name, version, host)] = found
    return found

stub

stub(name: str, version: str) -> str

The stub of name at version, rendered from the version's surface.

From the records the surface is the version's resolved observation; from the index it is the version's observation and surface blobs. Either way the text is the same rendering, the version's own verbs and options, exactly what a workspace locking that version types against.

Raises:

Type Description
CatalogueError

when the version was never read, or its blobs cannot be read.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def stub(self, name: str, version: str) -> str:
    """The stub of *name* at *version*, rendered from the version's surface.

    From the records the surface is the version's resolved
    observation; from the index it is the version's `observation`
    and `surface` blobs. Either way the text is the same rendering,
    the version's own verbs and options, exactly what a workspace
    locking that version types against.

    Raises:
        CatalogueError: when the version was never read, or its
            blobs cannot be read.
    """
    self.listed(name)
    record = self._records.get(name)
    if record is not None:
        found = surface_at(record, version) if version in record.versions else None
        if found is None:
            read = ", ".join(o.version for o in observations(record)) or "none"
            raise CatalogueError(
                f"{name} {version}: never read; the versions read are {read}"
            )
        return render_observation(name, found)
    tools = self.tools
    if not isinstance(tools, _LazyTools):  # pragma: no cover - records fill it
        raise CatalogueError(f"{name} {version}: no surface was read")
    return render_observation(name, tools.observation(name, version))

at classmethod

at(source: str, *, home: Home, offline: bool = False) -> Catalogue

The catalogue at source, whichever it holds: records, or an index.

A directory with no pointer file and record files in it is the authoring site's records; anything else, a directory with a pointer or an HTTP base, is an index read through home's store. One decision, made here for every reader.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
@classmethod
def at(cls, source: str, *, home: Home, offline: bool = False) -> Catalogue:
    """The catalogue at *source*, whichever it holds: records, or an index.

    A directory with no pointer file and record files in it is the
    authoring site's records; anything else, a directory with a
    pointer or an HTTP base, is an index read through *home*'s
    store. One decision, made here for every reader.
    """
    if is_records(source):
        return cls.of_records(Path(source))
    return cls.of_index(source, home=home, offline=offline)

of_records classmethod

of_records(directory: Path) -> Catalogue

The catalogue of the records under directory, the authoring site's.

Raises:

Type Description
RecordError

for a record that does not validate.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
@classmethod
def of_records(cls, directory: Path) -> Catalogue:
    """The catalogue of the records under *directory*, the authoring site's.

    Raises:
        RecordError: for a record that does not validate.
    """
    tools: dict[str, Listed] = {}
    deployments: dict[tuple[str, str, str], Deployment] = {}
    records: dict[str, Record] = {}
    for path in records_in(directory):
        record = Record.load(path)
        records[record.name] = record
        hosts: dict[str, dict[str, Digest]] = {}
        for delta in record.deltas:
            hosts[delta.version] = {}
            for host in delta.hosts:
                deployment = resolve(record, delta.version, host)
                deployments[(record.name, delta.version, host)] = deployment
                hosts[delta.version][host] = deployment.digest()
        tools[record.name] = Listed(
            record.name,
            record.kind,
            record.description,
            record.versions,
            hosts,
            package=record.package,
            mode=record.mode,
            min_version=record.min_version,
            runtime=record.runtime,
        )
    return cls(tools, deployments, None, records)

of_index classmethod

of_index(source: str, *, home: Home, offline: bool = False) -> Catalogue

The catalogue of the index at source, a directory or an HTTP base URL.

The pointer is read from the source; a tool's tree is fetched into the home's store through the source when the tool is first asked for, and a version's hosts when they are, so a second read answers from the machine and a read touches only what it needs.

Raises:

Type Description
CatalogueError

when the pointer cannot be read or is not one; a tree the pointer names and cannot be fetched refuses when its tool is asked for.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
@classmethod
def of_index(cls, source: str, *, home: Home, offline: bool = False) -> Catalogue:
    """The catalogue of the index at *source*, a directory or an HTTP base URL.

    The pointer is read from the source; a tool's tree is fetched
    into the home's store through the source when the tool is first
    asked for, and a version's hosts when they are, so a second read
    answers from the machine and a read touches only what it needs.

    Raises:
        CatalogueError: when the pointer cannot be read or is not
            one; a tree the pointer names and cannot be fetched
            refuses when its tool is asked for.
    """
    pointer = _read_pointer(source)
    entries: dict[str, dict[str, Any]] = {}
    for name, entry in sorted(pointer["tools"].items()):
        if not isinstance(entry, dict) or not isinstance(entry.get("tree"), str):
            raise CatalogueError(
                f"{source}: the pointer's entry for {name} is not one"
            )
        entries[str(name)] = entry
    store = home.open_store(sources=(_source_of(source),), offline=offline)
    return cls(_LazyTools(store, entries, source), {}, store)

CatalogueError

Bases: ValueError

An index or a records directory that cannot be read as a catalogue.

Listed dataclass

Listed(name: str, kind: str, description: str, versions: tuple[str, ...], hosts: Mapping[str, Mapping[str, Digest]], package: str = '', mode: str = '', min_version: str = '', runtime: str = '')

One tool as the catalogue lists it.

Attributes:

Name Type Description
name str

The tool's name.

kind str

The installer kind, one of the record's kinds.

description str

One line on what the tool is.

package str

What a delegated kind's installer installs, when it differs from the name.

mode str

The record's materialisation mode; empty for the kind's default.

runtime str

What an npm tool runs on; empty for node.

versions tuple[str, ...]

Every version tracked, oldest first, as the record orders them.

hosts Mapping[str, Mapping[str, Digest]]

Per version, the host keys the version has an artifact for, with the digest of each host's deployment.

name instance-attribute

name: str

kind instance-attribute

kind: str

description instance-attribute

description: str

versions instance-attribute

versions: tuple[str, ...]

hosts instance-attribute

package class-attribute instance-attribute

package: str = ''

mode class-attribute instance-attribute

mode: str = ''

min_version class-attribute instance-attribute

min_version: str = ''

runtime class-attribute instance-attribute

runtime: str = ''

DamagedView

Bases: NamedTuple

A view the disk no longer holds whole: tool, version, the paths missing.

Attributes:

Name Type Description
name str
version str
missing tuple[str, ...]

name instance-attribute

name: str

version instance-attribute

version: str

missing instance-attribute

missing: tuple[str, ...]

Delta dataclass

Delta(paths: tuple[Path, ...] = (), env: dict[str, str] = dict())

What a set of installs adds to an environment.

Attributes:

Name Type Description
paths tuple[Path, ...]

Directories to put in front of PATH, first first.

env dict[str, str]

Variables to set, a later install's value winning.

paths class-attribute instance-attribute

paths: tuple[Path, ...] = ()

env class-attribute instance-attribute

env: dict[str, str] = field(default_factory=dict)

Ensured dataclass

Ensured(name: str, version: str, installed: bool, tool_dir: Path, deployment: Deployment, tree: Digest | None, answered: str = '')

A tool version the store supplies.

Attributes:

Name Type Description
name str

The tool.

version str

The version.

installed bool

True when this call installed it, False when it was present already.

tool_dir Path

The view a shell runs from; a delegated kind's own directory under the home, or a system tool's directory.

deployment Deployment

The host's deployment the install followed; for a delegated kind, the entry points its installer wrote under bin, and nothing else.

tree Digest | None

The tree tools/<name>@<version> names; None for a delegated kind, whose bytes never went through the store.

answered str

The version a system tool printed when it was probed on the machine, so a receipt can say what answered; empty for a tool the store installed, and for one that prints no version.

name instance-attribute

name: str

version instance-attribute

version: str

installed instance-attribute

installed: bool

tool_dir instance-attribute

tool_dir: Path

deployment instance-attribute

deployment: Deployment

tree instance-attribute

tree: Digest | None

answered class-attribute instance-attribute

answered: str = ''

paths property

paths: tuple[Path, ...]

The directories the deployment puts on PATH, under the tool directory.

env property

env: dict[str, str]

The deployment's env with PACKAGE_VAR replaced by the tool directory.

Event dataclass

Event(name: str, version: str, action: str, detail: str = '')

One step of the engine's work, as it starts or resolves.

Attributes:

Name Type Description
name str

The tool.

version str

The version.

action str

A short verb: probe, wait, fetch, install, link.

detail str

Free text a renderer may show: a URL, a path, a reason.

name instance-attribute

name: str

version instance-attribute

version: str

action instance-attribute

action: str

detail class-attribute instance-attribute

detail: str = ''

Fetched dataclass

Fetched(name: str, version: str, host: str, digest: Digest, landed: bool)

One artifact fetch landed or found in the mirror.

Attributes:

Name Type Description
name str

The tool.

version str

The version.

host str

The host key.

digest Digest

The artifact's digest.

landed bool

True when the bytes came in on this call.

name instance-attribute

name: str

version instance-attribute

version: str

host instance-attribute

host: str

digest instance-attribute

digest: Digest

landed instance-attribute

landed: bool

Store

Store(home: Home, *, host: str = '', sources: Iterable[Source] = (), offline: bool = False, progress: Progress = silent)

The tool store: a home's objects, refs and views, driven by specs.

Parameters:

Name Type Description Default
home Home

The store's directories.

required
host str

The host key installs follow; the running machine's by default.

''
sources Iterable[Source]

The tiers consulted before the origin, in order: a folder or an HTTP base in strongroom's layout.

()
offline bool

Never reach an origin; a miss fails closed.

False
progress Progress

Receives every event.

silent

Methods:

Name Description
probe

The tool version when it is present here, else None; no source is consulted.

ensure

Supply the tool at version as its record resolves it on this host.

supply

Supply name at version from deployment or through its installer.

stage

Land deployment's artifact and unpack it into into, installing nothing.

audit

The paths of name's view at version the disk lacks; None without a view.

audit_views

Every view under the home that lacks files on disk, by tool and version.

mend_view

Make name's view at version whole again from the tree the store holds.

link

Fill into with one link per executable the installs put on PATH.

delta

The PATH prepend and env the installs contribute.

fetch

Land every version's artifact for hosts into a store at into.

Attributes:

Name Type Description
home Home
host str
offline bool
objects Store

The strongroom store underneath.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def __init__(
    self,
    home: Home,
    *,
    host: str = "",
    sources: Iterable[Source] = (),
    offline: bool = False,
    progress: Progress = silent,
) -> None:
    self.home: Home = home
    self.host: str = host or _default_host()
    if self.host not in HOSTS:
        raise StoreError(f"host {self.host!r} is not one of {', '.join(HOSTS)}")
    self.offline: bool = offline
    self._progress = progress
    self._objects: ObjectStore = home.open_store(sources=sources, offline=offline)

home instance-attribute

home: Home = home

host instance-attribute

host: str = host or _default_host()

offline instance-attribute

offline: bool = offline

objects property

objects: Store

The strongroom store underneath.

probe

probe(record: Record, version: str) -> Ensured | None

The tool version when it is present here, else None; no source is consulted.

Present means the ref names a tree made from this host's deployment and a view of it was made at the tool's directory; for a delegated kind, that its installer's directory holds what it installed. Whether the view's files are all still on disk is audit's question, asked by fm doctor and not on every sync.

Raises:

Type Description
RecordError

for a version the record does not track, or a version without this host.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def probe(self, record: Record, version: str) -> Ensured | None:
    """The tool version when it is present here, else None; no source is consulted.

    Present means the ref names a tree made from this host's
    deployment and a view of it was made at the tool's directory;
    for a delegated kind, that its installer's directory holds what
    it installed. Whether the view's files are all still on disk is
    `audit`'s question, asked by `fm doctor` and not on every sync.

    Raises:
        RecordError: for a version the record does not track, or a
            version without this host.
    """
    if record.kind not in DOWNLOAD_KINDS:
        return self._probe_delegated(record.name, record.kind, version)
    deployment = resolve(record, version, self.host)
    return self._probe_download(record.name, version, deployment)

ensure

ensure(record: Record, version: str, *, runtime: Path | None = None, graph: Path | None = None) -> Ensured

Supply the tool at version as its record resolves it on this host.

runtime is the executable of the runtime an npm record names, node unless it says bun, supplied by the caller first. graph is the resolved set the lock pins for this version, which a delegated kind installs instead of resolving.

Raises:

Type Description
RecordError

for a version the record does not track, or a version without this host.

StoreError

as supply raises.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def ensure(
    self,
    record: Record,
    version: str,
    *,
    runtime: Path | None = None,
    graph: Path | None = None,
) -> Ensured:
    """Supply the tool at *version* as its record resolves it on this host.

    *runtime* is the executable of the runtime an `npm` record
    names, node unless it says bun, supplied by the caller first.
    *graph* is the resolved set the lock pins for this version,
    which a delegated kind installs instead of resolving.

    Raises:
        RecordError: for a version the record does not track, or a
            version without this host.
        StoreError: as `supply` raises.
    """
    deployment = (
        resolve(record, version, self.host)
        if record.kind in DOWNLOAD_KINDS
        else None
    )
    return self.supply(
        record.name,
        record.kind,
        version,
        deployment,
        package=record.package,
        min_version=record.min_version,
        runtime=record.runtime,
        runtime_exe=runtime,
        graph=graph,
    )

supply

supply(name: str, kind: str, version: str, deployment: Deployment | None = None, *, package: str = '', min_version: str = '', runtime: str = '', runtime_exe: Path | None = None, graph: Path | None = None) -> Ensured

Supply name at version from deployment or through its installer.

An archive or binary lands its artifact by the deployment's digest, extracts it, collects it as a tree and views it. A pypi is installed by uv into its own directory under the home, package naming what uv installs when it differs from the tool's name, and its launchers are the entry points. An npm tool is installed the same way through runtime_exe, the executable of the runtime runtime names, node unless it says bun, which the caller supplied first: npm run on node, or bun's own installer. Its launchers start with #!/usr/bin/env node, which the runtime answers on the caller's PATH, bun through the node shim its record declares. A dotnet tool is installed the same way through runtime_exe, the dotnet SDK's own executable, with dotnet tool install --tool-path into its own directory; its launchers are the shims the SDK writes, which find the runtime through DOTNET_ROOT, the SDK record's own environment. A system-check is the machine's own tool, found on PATH and held to min_version. python is not supplied through the store yet and refuses naming the kind.

One process at a time supplies a version: the supply holds the version's lock in the home while it works, and a second supply waits for it, saying so through the progress, then finds the version present.

Raises:

Type Description
StoreError

for a kind the store cannot supply, a downloaded kind with no deployment, an npm tool with no runtime handed over or a node with no npm beside it, a miss while offline, a mismatch at a tier, an archive that will not extract, an installer that failed or placed a launcher outside the tool's directory, a system tool missing or below its floor, or a ref already naming another tree.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def supply(
    self,
    name: str,
    kind: str,
    version: str,
    deployment: Deployment | None = None,
    *,
    package: str = "",
    min_version: str = "",
    runtime: str = "",
    runtime_exe: Path | None = None,
    graph: Path | None = None,
) -> Ensured:
    """Supply *name* at *version* from *deployment* or through its installer.

    An `archive` or `binary` lands its artifact by the deployment's
    digest, extracts it, collects it as a tree and views it. A
    `pypi` is installed by uv into its own directory under the
    home, *package* naming what uv installs when it differs from the
    tool's name, and its launchers are the entry points. An `npm`
    tool is installed the same way through *runtime_exe*, the
    executable of the runtime *runtime* names, node unless it says
    bun, which the caller supplied first: npm run on node, or bun's
    own installer. Its launchers start with `#!/usr/bin/env node`,
    which the runtime answers on the caller's PATH, bun through the
    `node` shim its record declares. A `dotnet` tool is installed
    the same way through *runtime_exe*, the dotnet SDK's own
    executable, with `dotnet tool install --tool-path` into its
    own directory; its launchers are the shims the SDK writes,
    which find the runtime through `DOTNET_ROOT`, the SDK
    record's own environment. A `system-check` is the machine's
    own tool, found on PATH and held to *min_version*. `python`
    is not supplied through the store yet and refuses naming the
    kind.

    One process at a time supplies a version: the supply holds the
    version's lock in the home while it works, and a second supply
    waits for it, saying so through the progress, then finds the
    version present.

    Raises:
        StoreError: for a kind the store cannot supply, a downloaded
            kind with no deployment, an `npm` tool with no runtime
            handed over or a node with no npm beside it, a miss
            while offline, a mismatch at a tier, an archive that
            will not extract, an installer that failed or placed a
            launcher outside the tool's directory, a system tool
            missing or below its floor, or a ref already naming
            another tree.
    """
    waiting = partial(
        self._progress, Event(name, version, "wait", "another process supplies it")
    )
    with exclusive(self.home.lock(name, version), waiting=waiting):
        return self._supply(
            name,
            kind,
            version,
            deployment,
            package=package,
            min_version=min_version,
            runtime=runtime,
            runtime_exe=runtime_exe,
            graph=graph,
        )

stage

stage(name: str, kind: str, version: str, deployment: Deployment, into: Path, *, exclude: bool = True) -> tuple[str, ...]

Land deployment's artifact and unpack it into into, installing nothing.

The artifact comes from the tiers and, unless offline, the origin; an archive is extracted and its declared root hoisted, a bare file saved as its file, and with exclude the deployment's exclusion patterns are applied. No entry point is required, no shim is made, no tree is collected and no ref is set: this is the look a check takes at a deployment for any host from any machine, and the first half of an install.

Returns:

Type Description
str

Every member of the unpacked tree before exclusion, as

...

install-relative forward-slashed paths, in name order.

Raises:

Type Description
StoreError

for a miss while offline, a mismatch at a tier, an archive that will not extract, or a declared root the archive lacks.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def stage(
    self,
    name: str,
    kind: str,
    version: str,
    deployment: Deployment,
    into: Path,
    *,
    exclude: bool = True,
) -> tuple[str, ...]:
    """Land *deployment*'s artifact and unpack it into *into*, installing nothing.

    The artifact comes from the tiers and, unless offline, the
    origin; an archive is extracted and its declared root hoisted,
    a bare file saved as its `file`, and with *exclude* the
    deployment's exclusion patterns are applied. No entry point is
    required, no shim is made, no tree is collected and no ref is
    set: this is the look a check takes at a deployment for any
    host from any machine, and the first half of an install.

    Returns:
        Every member of the unpacked tree before exclusion, as
        install-relative forward-slashed paths, in name order.

    Raises:
        StoreError: for a miss while offline, a mismatch at a tier,
            an archive that will not extract, or a declared root
            the archive lacks.
    """
    digest = Digest("sha256", deployment.sha256)
    artifact = self._land(name, version, deployment.url, digest)
    self._unpack(name, kind, deployment, artifact, into)
    members = tuple(sorted(p.relative_to(into).as_posix() for p in into.rglob("*")))
    if exclude:
        _exclude(deployment, into)
    return members

audit

audit(name: str, version: str) -> tuple[str, ...] | None

The paths of name's view at version the disk lacks; None without a view.

A walk of every path the view's record names, the check a sync no longer pays: a view damaged by hand after it was made is found here, named path by path, and mended by mend_view. An empty tuple is a whole view. None is a tool with no view at the directory, a delegated kind or one never supplied, which is the sync's to supply and nothing to audit.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def audit(self, name: str, version: str) -> tuple[str, ...] | None:
    """The paths of *name*'s view at *version* the disk lacks; None without a view.

    A walk of every path the view's record names, the check a sync
    no longer pays: a view damaged by hand after it was made is
    found here, named path by path, and mended by `mend_view`. An
    empty tuple is a whole view. None is a tool with no view at the
    directory, a delegated kind or one never supplied, which is the
    sync's to supply and nothing to audit.
    """
    tool_dir = self.home.tool_dir(name, version)
    record = self._view_of(tool_dir)
    if record is None:
        return None
    return tuple(
        entry.path
        for entry in record.entries
        if entry.rung != "parked" and not (tool_dir / entry.path).exists()
    )

audit_views

audit_views() -> tuple[DamagedView, ...]

Every view under the home that lacks files on disk, by tool and version.

The views are the store's own records, so nothing outside the store is read: no lock, no catalogue. A whole view is not listed. The paths are the view's, relative to the tool's directory.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def audit_views(self) -> tuple[DamagedView, ...]:
    """Every view under the home that lacks files on disk, by tool and version.

    The views are the store's own records, so nothing outside the
    store is read: no lock, no catalogue. A whole view is not
    listed. The paths are the view's, relative to the tool's
    directory.
    """
    found: list[DamagedView] = []
    for record in self._objects.views():
        at = Path(record.at)
        if at.parent != self.home.tools or "@" not in at.name:
            continue
        name, _, version = at.name.rpartition("@")
        missing = tuple(
            entry.path
            for entry in record.entries
            if entry.rung != "parked" and not (at / entry.path).exists()
        )
        if missing:
            found.append(DamagedView(name, version, missing))
    return tuple(found)

mend_view

mend_view(name: str, version: str) -> None

Make name's view at version whole again from the tree the store holds.

The repair for a view audit or audit_views found damaged: the view's record goes, which removes what the store created there and nothing else, and the same tree is viewed again at the same directory. The tree's blobs are in the object store already, so nothing is fetched and no record of the tool is read. A whole view is dropped and made again the same way.

Raises:

Type Description
StoreError

when no view of the tool exists at the directory.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def mend_view(self, name: str, version: str) -> None:
    """Make *name*'s view at *version* whole again from the tree the store holds.

    The repair for a view `audit` or `audit_views` found damaged: the
    view's record goes, which removes what the store created there
    and nothing else, and the same tree is viewed again at the same
    directory. The tree's blobs are in the object store already, so
    nothing is fetched and no record of the tool is read. A whole
    view is dropped and made again the same way.

    Raises:
        StoreError: when no view of the tool exists at the directory.
    """
    tool_dir = self.home.tool_dir(name, version)
    stale = self._view_of(tool_dir)
    if stale is None:
        raise StoreError(f"{name} {version}: no view at {tool_dir} to mend")
    self._objects.drop_view(stale.id)
    tool_dir.parent.mkdir(parents=True, exist_ok=True)
    self._objects.view(stale.tree, tool_dir)
link(ensured: Iterable[Ensured], into: Path) -> tuple[Path, ...]

Fill into with one link per executable the installs put on PATH.

A link is a symlink where the platform allows one and a launcher where it refuses; LINKS in into records what the engine made, and a link it did not make is never removed. A name two installs both offer goes to the first.

Returns:

Type Description
tuple[Path, ...]

The links made, in order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def link(self, ensured: Iterable[Ensured], into: Path) -> tuple[Path, ...]:
    """Fill *into* with one link per executable the installs put on PATH.

    A link is a symlink where the platform allows one and a
    launcher where it refuses; `LINKS` in *into* records what the
    engine made, and a link it did not make is never removed. A
    name two installs both offer goes to the first.

    Returns:
        The links made, in order.
    """
    into.mkdir(parents=True, exist_ok=True)
    manifest = into / LINKS
    previous: list[str] = (
        json.loads(manifest.read_text("utf-8")) if manifest.is_file() else []
    )
    for name in previous:
        stale = into / name
        if stale.is_symlink() or stale.is_file():
            stale.unlink()
    made: list[Path] = []
    names: set[str] = set()
    for item in ensured:
        # The entry points are the annotation, never a directory
        # scan: a bundle's own interpreter stays off the bin
        # directory unless the deployment names it.
        for entry in item.deployment.entry_points:
            candidate = item.tool_dir / entry
            if not candidate.is_file() or candidate.name in names:
                continue
            link = into / candidate.name
            _make_link(candidate, link)
            names.add(candidate.name)
            made.append(link)
            self._progress(Event(item.name, item.version, "link", str(link)))
    manifest.write_text(json.dumps([p.name for p in made]) + "\n", encoding="utf-8")
    return tuple(made)

delta

delta(ensured: Iterable[Ensured], bin_dir: Path | None = None) -> Delta

The PATH prepend and env the installs contribute.

With bin_dir, the one directory on PATH is the bin directory link filled, and the installs contribute their env only.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def delta(self, ensured: Iterable[Ensured], bin_dir: Path | None = None) -> Delta:
    """The PATH prepend and env the installs contribute.

    With *bin_dir*, the one directory on PATH is the bin directory
    `link` filled, and the installs contribute their env only.
    """
    paths: list[Path] = [bin_dir] if bin_dir is not None else []
    env: dict[str, str] = {}
    for item in ensured:
        if bin_dir is None:
            for directory in item.paths:
                if directory not in paths:
                    paths.append(directory)
        env.update(item.env)
    return Delta(tuple(paths), env)

fetch

fetch(records: Iterable[Record], *, hosts: Iterable[str] = HOSTS, into: Path) -> tuple[Fetched, ...]

Land every version's artifact for hosts into a store at into.

The folder is a mirror by construction: a source of this engine's layout. Bytes come from this store's sources and, unless offline, the origin; a mismatch refuses naming the tool.

Raises:

Type Description
StoreError

for a miss while offline, or a mismatch.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def fetch(
    self, records: Iterable[Record], *, hosts: Iterable[str] = HOSTS, into: Path
) -> tuple[Fetched, ...]:
    """Land every version's artifact for *hosts* into a store at *into*.

    The folder is a mirror by construction: a source of this
    engine's layout. Bytes come from this store's sources and, unless
    offline, the origin; a mismatch refuses naming the tool.

    Raises:
        StoreError: for a miss while offline, or a mismatch.
    """
    wanted = tuple(hosts)
    mirror = Home(into).open_store()
    landed: list[Fetched] = []
    for record in records:
        if record.kind not in DOWNLOAD_KINDS:
            continue
        for delta in record.deltas:
            for host, artifact in delta.artifacts.items():
                if host not in wanted:
                    continue
                digest = Digest("sha256", artifact.sha256)
                if mirror.state(digest) == "present":
                    landed.append(
                        Fetched(record.name, delta.version, host, digest, False)
                    )
                    continue
                path = self._land(record.name, delta.version, artifact.url, digest)
                with path.open("rb") as handle:
                    mirror.land(handle, expected=digest)
                landed.append(
                    Fetched(record.name, delta.version, host, digest, True)
                )
    return tuple(landed)

StoreError

Bases: Exception

A tool the store cannot supply; the message names the tool and the reason.

FetchError

FetchError(message: str, *, status: int | None = None)

Bases: Unreachable

A URL not read after the tries; the message names it and the last cause.

Source code in packages/strongroom/src/livery/strongroom/_sources.py
def __init__(self, message: str, *, status: int | None = None) -> None:
    super().__init__(message)
    self.status = status

UnpackError

Bases: Exception

An archive that will not unpack; the message names the archive and why.

Home dataclass

Home(root: Path)

The store's directories under one root.

Attributes:

Name Type Description
root Path

The home: Home.under(data_dir) for the machinery, under the runner's data directory; whatever the consumer passes otherwise.

Methods:

Name Description
under

The store's home under a runner's data directory, toolroom in it.

tool_dir

The view of name at version.

lock

The file a supply of name at version holds while it works.

open_store

Open the home's strongroom store, creating it on first use.

root instance-attribute

root: Path

store property

store: Path

The strongroom store.

tools property

tools: Path

Where each tool version's view lives, tools/<name>@<version>.

uv property

uv: Path

The uv tool installs, one directory per <name>@<version>, and pythons.

npm property

npm: Path

The npm installs, one directory per <name>@<version>, by either runtime.

dotnet property

dotnet: Path

The dotnet tool installs, one directory per <name>@<version>.

locks property

locks: Path

The supply locks, one file per <name>@<version>.lock.

under classmethod

under(data_dir: Path) -> Home

The store's home under a runner's data directory, toolroom in it.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
@classmethod
def under(cls, data_dir: Path) -> Home:
    """The store's home under a runner's data directory, `toolroom` in it."""
    return cls(data_dir / "toolroom")

tool_dir

tool_dir(name: str, version: str) -> Path

The view of name at version.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
def tool_dir(self, name: str, version: str) -> Path:
    """The view of *name* at *version*."""
    return self.tools / f"{name}@{version}"

lock

lock(name: str, version: str) -> Path

The file a supply of name at version holds while it works.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
def lock(self, name: str, version: str) -> Path:
    """The file a supply of *name* at *version* holds while it works."""
    return self.locks / f"{name}@{version}.lock"

open_store

open_store(*, sources: Iterable[Source] = (), offline: bool = False) -> Store

Open the home's strongroom store, creating it on first use.

A store that exists is opened with the same namespaces it was created with; a directory that holds another layout refuses as strongroom refuses it. sources are the tiers the store consults for an object it lacks, and offline keeps it from every origin.

Source code in packages/toolroom-store/src/livery/toolroom/store/_home.py
def open_store(
    self, *, sources: Iterable[Source] = (), offline: bool = False
) -> Store:
    """Open the home's strongroom store, creating it on first use.

    A store that exists is opened with the same namespaces it was
    created with; a directory that holds another layout refuses
    as strongroom refuses it. *sources* are the tiers the store
    consults for an object it lacks, and *offline* keeps it from
    every origin.
    """
    if (self.store / "strongroom.json").is_file():
        return Store.open(
            self.store, namespaces=NAMESPACES, sources=sources, offline=offline
        )
    self.root.mkdir(parents=True, exist_ok=True)
    return Store.create(
        self.store, namespaces=NAMESPACES, sources=sources, offline=offline
    )

Graph dataclass

Graph(file: str, digest: Digest, by: str = '')

The resolved graph of a delegated tool's version, as the lock names it.

A delegated kind installs a graph, not a file: the package named is one of many its installer resolves, and the transitive part moves between resolves at one version. The graph pins all of it, in the installer's own format, in a file beside the lock; the lock carries its name and its digest, so the file that installs is the file that was resolved.

Attributes:

Name Type Description
file str

The file's name under GRAPHS, beside the lock.

digest Digest

The file's bytes, so a graph edited by hand is caught.

by str

What resolved it, name and version, for the day an install refuses and someone must know what wrote it.

Methods:

Name Description
to_json

The graph as a JSON object.

from_json

The graph in value.

file instance-attribute

file: str

digest instance-attribute

digest: Digest

by class-attribute instance-attribute

by: str = ''

to_json

to_json() -> dict[str, Any]

The graph as a JSON object.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def to_json(self) -> dict[str, Any]:
    """The graph as a JSON object."""
    return {"file": self.file, "digest": str(self.digest), "by": self.by}

from_json classmethod

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

The graph in value.

Raises:

Type Description
LockError

when it is not one, naming where.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
@classmethod
def from_json(cls, value: Any, *, where: str) -> Graph:
    """The graph in *value*.

    Raises:
        LockError: when it is not one, naming *where*.
    """
    if (
        not isinstance(value, dict)
        or not isinstance(value.get("file"), str)
        or not value["file"]
        or not isinstance(value.get("digest"), str)
    ):
        raise LockError(f"{where}: the graph is not one")
    try:
        digest = Digest.parse(value["digest"])
    except ValueError as error:
        raise LockError(f"{where}: {error}") from None
    return cls(value["file"], digest, str(value.get("by", "")))

Lock dataclass

Lock(hosts: tuple[str, ...], tools: dict[str, Locked], notes: tuple[str, ...] = ())

The repository's lock: the hosts it locks for and one version per tool.

Attributes:

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

The host keys every locked download resolves on.

tools dict[str, Locked]

Tool name to its locked version and deployments.

notes tuple[str, ...]

What the resolution left out and why: an optional tool the catalogue could not serve. Not written to the file.

Methods:

Name Description
on_host

The tools locked for host, in name order.

to_json

The lock as a JSON object, tools in name order.

save

Write the lock to path, indented, with a trailing newline.

load

The lock at path.

hosts instance-attribute

hosts: tuple[str, ...]

tools instance-attribute

tools: dict[str, Locked]

notes class-attribute instance-attribute

notes: tuple[str, ...] = field(default=(), compare=False)

on_host

on_host(host: str) -> tuple[str, ...]

The tools locked for host, in name order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def on_host(self, host: str) -> tuple[str, ...]:
    """The tools locked for *host*, in name order."""
    return tuple(
        name for name in sorted(self.tools) if self.tools[name].applies(host)
    )

to_json

to_json() -> dict[str, Any]

The lock as a JSON object, tools in name order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def to_json(self) -> dict[str, Any]:
    """The lock as a JSON object, tools in name order."""
    return {
        "schema": LOCK_SCHEMA,
        "hosts": list(self.hosts),
        "tools": {name: self.tools[name].to_json() for name in sorted(self.tools)},
    }

save

save(path: Path) -> None

Write the lock to path, indented, with a trailing newline.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def save(self, path: Path) -> None:
    """Write the lock to *path*, indented, with a trailing newline."""
    path.write_text(json.dumps(self.to_json(), indent=2) + "\n", encoding="utf-8")

load classmethod

load(path: Path) -> Lock

The lock at path.

Raises:

Type Description
LockError

when the file is not a lock of this schema, naming the file.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
@classmethod
def load(cls, path: Path) -> Lock:
    """The lock at *path*.

    Raises:
        LockError: when the file is not a lock of this schema,
            naming the file.
    """
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError) as error:
        raise LockError(f"{path}: not a lock ({error})") from None
    if not isinstance(data, dict) or data.get("schema") != LOCK_SCHEMA:
        raise LockError(f"{path}: not a lock of schema {LOCK_SCHEMA}")
    hosts = data.get("hosts")
    tools = data.get("tools")
    if (
        not isinstance(hosts, list)
        or not all(isinstance(h, str) and h in HOSTS for h in hosts)
        or not isinstance(tools, dict)
    ):
        raise LockError(
            f"{path}: the lock names hosts outside the six, or no tools"
        )
    locked: dict[str, Locked] = {}
    for name, entry in tools.items():
        if (
            not isinstance(entry, dict)
            or not isinstance(entry.get("version"), str)
            or not isinstance(entry.get("hosts"), dict)
        ):
            raise LockError(f"{path}: the entry for {name} is not one")
        try:
            digests = {
                str(host): Digest.parse(str(digest))
                for host, digest in entry["hosts"].items()
            }
        except ValueError as error:
            raise LockError(f"{path}: {name}: {error}") from None
        raw = entry.get("graph")
        graph = (
            None if raw is None else Graph.from_json(raw, where=f"{path}: {name}")
        )
        scope = entry.get("on", [])
        if not isinstance(scope, list) or not all(
            isinstance(h, str) and h in hosts for h in scope
        ):
            raise LockError(
                f"{path}: {name}: `on` names a host outside the lock's"
                f" ({', '.join(hosts)})"
            )
        allowed = entry.get("allow-host", False)
        if not isinstance(allowed, bool):
            raise LockError(
                f"{path}: {name}: `allow-host` is {allowed!r}, not true or false"
            )
        optional = entry.get("optional", False)
        if not isinstance(optional, bool):
            raise LockError(
                f"{path}: {name}: `optional` is {optional!r}, not true or false"
            )
        locked[str(name)] = Locked(
            entry["version"], digests, graph, tuple(scope), allowed, optional
        )
    return cls(tuple(hosts), locked)

Locked dataclass

Locked(version: str, hosts: dict[str, Digest] = dict(), graph: Graph | None = None, on: tuple[str, ...] = (), allow_host: bool = False, optional: bool = False)

One tool as the lock holds it.

Attributes:

Name Type Description
version str

The version locked.

hosts dict[str, Digest]

Per host the tool is locked on, the deployment's digest; empty for a delegated kind, whose installer resolves the host.

graph Graph | None

The resolved graph of a delegated kind's version, or None for a downloaded kind and for a delegated one locked before a graph was written for it.

on tuple[str, ...]

The locked hosts the tool is required on, when they are fewer than the lock's; empty when it is required on every one.

allow_host bool

Whether a copy of the tool already on the machine may serve instead of the locked version, when it satisfies the requirement's floor; the workspace's host-allowed list says so, and the entry carries allow-host so every checkout and CI agree on which tools may vary.

optional bool

Whether every site that requires the tool marks it optional, so a host it is not locked on lacks it by design.

Methods:

Name Description
applies

Whether the tool is locked for host.

to_json

The entry as a JSON object.

version instance-attribute

version: str

hosts class-attribute instance-attribute

hosts: dict[str, Digest] = field(default_factory=dict)

graph class-attribute instance-attribute

graph: Graph | None = None

on class-attribute instance-attribute

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

allow_host class-attribute instance-attribute

allow_host: bool = False

optional class-attribute instance-attribute

optional: bool = False

applies

applies(host: str) -> bool

Whether the tool is locked for host.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def applies(self, host: str) -> bool:
    """Whether the tool is locked for *host*."""
    return not self.on or host in self.on

to_json

to_json() -> dict[str, Any]

The entry as a JSON object.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def to_json(self) -> dict[str, Any]:
    """The entry as a JSON object."""
    out: dict[str, Any] = {
        "version": self.version,
        "hosts": {host: str(digest) for host, digest in sorted(self.hosts.items())},
    }
    if self.graph is not None:
        out["graph"] = self.graph.to_json()
    if self.on:
        out["on"] = list(self.on)
    if self.allow_host:
        out["allow-host"] = True
    if self.optional:
        out["optional"] = True
    return out

LockError

Bases: ValueError

A requirement the catalogue cannot satisfy; the message names why.

Requirement dataclass

Requirement(name: str, floor: str = '', site: str = '', hosts: tuple[str, ...] = (), optional: bool = False, exclude: tuple[str, ...] = ())

One site's requirement of a tool: a floor, or any version, on some hosts or all.

Attributes:

Name Type Description
name str

The tool's name.

floor str

The lowest version that satisfies; empty for any.

site str

Where the requirement was declared, for a refusal.

hosts tuple[str, ...]

The hosts the requirement applies to, each a platform (windows, every locked host of that platform) or a host key (windows-x64); empty for every locked host.

optional bool

Whether ? marks it optional: locked where the catalogue can serve it, never refused.

exclude tuple[str, ...]

The platforms and host keys ! removes from its hosts.

Methods:

Name Description
parse

A requirement from its spelling, name?>=floor@scope.

__str__
satisfied_by

Whether version is at or above the floor.

on

The hosts of locked this requirement applies to, in their order.

name instance-attribute

name: str

floor class-attribute instance-attribute

floor: str = ''

site class-attribute instance-attribute

site: str = ''

hosts class-attribute instance-attribute

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

optional class-attribute instance-attribute

optional: bool = False

exclude class-attribute instance-attribute

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

parse classmethod

parse(text: str, *, site: str = '') -> Requirement

A requirement from its spelling, name?>=floor@scope.

Every part after the name is optional.

? marks it optional. The scope after @ is comma-separated platforms or host keys, each excluded with a leading !: dotnet_coverage@windows, tea>=1.1@linux,macos-arm, docker?@!windows-arm. The grammar is livery.toolroom.store.Spec's; a tool requirement takes no options.

Raises:

Type Description
LockError

for a spelling that is none of these, or a scope naming no host or a token that is neither a platform nor a host key.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
@classmethod
def parse(cls, text: str, *, site: str = "") -> Requirement:
    """A requirement from its spelling, ``name?>=floor@scope``.

    Every part after the name is optional.

    ``?`` marks it optional. The scope after ``@`` is comma-separated
    platforms or host keys, each excluded with a leading ``!``:
    ``dotnet_coverage@windows``, ``tea>=1.1@linux,macos-arm``,
    ``docker?@!windows-arm``. The grammar is
    [livery.toolroom.store.Spec][]'s; a tool requirement takes
    no options.

    Raises:
        LockError: for a spelling that is none of these, or a
            scope naming no host or a token that is neither a
            platform nor a host key.
    """
    where = site or "a requirement"
    try:
        spec = Spec.parse(text, where=where)
    except SpecError as error:
        raise LockError(str(error)) from None
    if spec.options:
        raise LockError(
            f"{where}: {text!r} names options; a tool requirement takes"
            " none, spell it `name?>=floor@scope`"
        )
    return cls(
        spec.name,
        spec.floor,
        site,
        spec.scope.include,
        spec.optional,
        spec.scope.exclude,
    )

__str__

__str__() -> str
Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def __str__(self) -> str:
    return str(
        Spec(
            self.name,
            optional=self.optional,
            floor=self.floor,
            scope=Scope(self.hosts, self.exclude),
        )
    )

satisfied_by

satisfied_by(version: str) -> bool

Whether version is at or above the floor.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def satisfied_by(self, version: str) -> bool:
    """Whether *version* is at or above the floor."""
    return not self.floor or version_tuple(version) >= version_tuple(self.floor)

on

on(locked: Iterable[str]) -> tuple[str, ...]

The hosts of locked this requirement applies to, in their order.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def on(self, locked: Iterable[str]) -> tuple[str, ...]:
    """The hosts of *locked* this requirement applies to, in their order."""
    return Scope(self.hosts, self.exclude).hosts(locked)

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

RecordDelta dataclass

RecordDelta(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.

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()))

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,
    )

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, ...]]]

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")

RecordError

Bases: ValueError

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

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)

Scope dataclass

Scope(include: tuple[str, ...] = (), exclude: tuple[str, ...] = ())

The hosts a requirement is limited to, as written after @.

Attributes:

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

The platforms and host keys named without !; empty for every supported host.

exclude tuple[str, ...]

The platforms and host keys named with !.

Methods:

Name Description
parse

The scope comma-separated text spells, every token checked.

hosts

The hosts of supported this scope reaches, in their order.

__bool__

Whether the scope limits anything: false for every host.

__str__

The scope as written after @.

include class-attribute instance-attribute

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

exclude class-attribute instance-attribute

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

parse classmethod

parse(text: str, *, where: str = 'a requirement', spelled: str = '') -> Scope

The scope comma-separated text spells, every token checked.

Parameters:

Name Type Description Default
text str

The tokens after @, linux,!linux-arm say.

required
where str

The site a refusal names.

'a requirement'
spelled str

The whole spelling the scope came from, for a refusal; text itself when empty.

''

Raises:

Type Description
SpecError

for a scope naming no token, or a token that is neither a platform nor a host key.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
@classmethod
def parse(
    cls, text: str, *, where: str = "a requirement", spelled: str = ""
) -> Scope:
    """The scope comma-separated *text* spells, every token checked.

    Args:
        text: The tokens after ``@``, ``linux,!linux-arm`` say.
        where: The site a refusal names.
        spelled: The whole spelling the scope came from, for a
            refusal; *text* itself when empty.

    Raises:
        SpecError: for a scope naming no token, or a token that is
            neither a platform nor a host key.
    """
    whole = spelled or text
    tokens = tuple(token.strip() for token in text.split(",") if token.strip())
    if not tokens:
        raise SpecError(
            f"{where}: {whole!r} names no host after @; a scope names a"
            f" platform ({', '.join(PLATFORMS)}) or a host key"
            f" ({', '.join(HOSTS)})"
        )
    include: list[str] = []
    exclude: list[str] = []
    for token in tokens:
        name = token.removeprefix("!")
        if name not in PLATFORMS and name not in HOSTS:
            raise SpecError(
                f"{where}: {name!r} in {whole!r} is neither a platform"
                f" ({', '.join(PLATFORMS)}) nor a host key ({', '.join(HOSTS)})"
            )
        (exclude if token.startswith("!") else include).append(name)
    return cls(tuple(include), tuple(exclude))

hosts

hosts(supported: Iterable[str]) -> tuple[str, ...]

The hosts of supported this scope reaches, in their order.

No inclusion reaches every supported host; an exclusion then removes its hosts, so a scope of exclusions alone starts from every supported host.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def hosts(self, supported: Iterable[str]) -> tuple[str, ...]:
    """The hosts of *supported* this scope reaches, in their order.

    No inclusion reaches every supported host; an exclusion then
    removes its hosts, so a scope of exclusions alone starts from
    every supported host.
    """
    return tuple(
        host
        for host in supported
        if (not self.include or _matches(host, self.include))
        and not _matches(host, self.exclude)
    )

__bool__

__bool__() -> bool

Whether the scope limits anything: false for every host.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def __bool__(self) -> bool:
    """Whether the scope limits anything: false for every host."""
    return bool(self.include or self.exclude)

__str__

__str__() -> str

The scope as written after @.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def __str__(self) -> str:
    """The scope as written after ``@``."""
    return ",".join([*self.include, *(f"!{name}" for name in self.exclude)])

Spec dataclass

Spec(name: str, options: tuple[str, ...] = (), optional: bool = False, floor: str = '', scope: Scope = Scope())

One requirement as the grammar spells it: name[options]?>=floor@scope.

Attributes:

Name Type Description
name str

The tool's or the extension's name.

options tuple[str, ...]

The names inside [...], in their order.

optional bool

Whether ? marks it optional.

floor str

The lowest version that satisfies; empty for any.

scope Scope

The hosts it is limited to; empty for every host.

Methods:

Name Description
parse

The requirement text spells.

__str__

The requirement as the grammar spells it.

name instance-attribute

name: str

options class-attribute instance-attribute

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

optional class-attribute instance-attribute

optional: bool = False

floor class-attribute instance-attribute

floor: str = ''

scope class-attribute instance-attribute

scope: Scope = field(default_factory=Scope)

parse classmethod

parse(text: str, *, where: str = 'a requirement') -> Spec

The requirement text spells.

Parameters:

Name Type Description Default
text str

ruff, llvm[slim]>=20, docker?@!windows.

required
where str

The site a refusal names: the one that declared it.

'a requirement'

Raises:

Type Description
SpecError

for a spelling the grammar does not read, an empty or malformed option, or a scope livery.toolroom.store.Scope.parse refuses.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
@classmethod
def parse(cls, text: str, *, where: str = "a requirement") -> Spec:
    """The requirement *text* spells.

    Args:
        text: ``ruff``, ``llvm[slim]>=20``, ``docker?@!windows``.
        where: The site a refusal names: the one that declared it.

    Raises:
        SpecError: for a spelling the grammar does not read, an
            empty or malformed option, or a scope
            [livery.toolroom.store.Scope.parse][] refuses.
    """
    found = _SPEC.match(text)
    if found is None:
        raise SpecError(
            f"{where}: {text!r} is not a requirement; spell it"
            " `name[options]?>=floor@scope`, every part after the name"
            " optional"
        )
    options: tuple[str, ...] = ()
    if found["options"] is not None:
        options = tuple(part.strip() for part in found["options"].split(","))
        bad = [option for option in options if not _OPTION.match(option)]
        if bad:
            raise SpecError(
                f"{where}: {text!r} names an option that is not a name:"
                f" {', '.join(repr(option) for option in bad)}"
            )
    scope = Scope()
    if found["scope"] is not None:
        scope = Scope.parse(found["scope"], where=where, spelled=text)
    return cls(
        found["name"],
        options,
        found["optional"] is not None,
        found["floor"] or "",
        scope,
    )

__str__

__str__() -> str

The requirement as the grammar spells it.

Source code in packages/toolroom-store/src/livery/toolroom/store/_requirement.py
def __str__(self) -> str:
    """The requirement as the grammar spells it."""
    spelled = self.name
    if self.options:
        spelled += f"[{','.join(self.options)}]"
    if self.optional:
        spelled += "?"
    if self.floor:
        spelled += f">={self.floor}"
    if self.scope:
        spelled += f"@{self.scope}"
    return spelled

SpecError

Bases: ValueError

A spelling the requirement grammar does not read; the message names why.

Option dataclass

Option(name: str, flags: tuple[str, ...] = (), negation: str = '', help: str = '', type_name: str = 'str', default: Any = None, choices: tuple[str, ...] = (), since: str = '', until: str = '', not_on: tuple[str, ...] = ())

One option of one tool verb, as the tool describes it.

Attributes:

Name Type Description
name str

The Python keyword a task writes: use_directory_urls.

flags tuple[str, ...]

What the tool accepts, longest first: ("--use-directory-urls",).

negation str

How this tool spells "off": --dirty, not always --no-<name>.

help str

The tool's own one-line description, for the stub's docstring.

type_name str

The Python type the stub declares: bool, str, int, list[str].

default Any

The tool's default, when it states one.

choices tuple[str, ...]

The closed set of values the tool accepts, when it names one. The

since str

The release this option first appears in, when the history knows.

until str

The release this option stopped appearing in, when it has gone. A

not_on tuple[str, ...]

The platforms observed to lack this, when any have been. Empty means

name instance-attribute

name: str

The Python keyword a task writes: use_directory_urls.

flags class-attribute instance-attribute

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

What the tool accepts, longest first: ("--use-directory-urls",).

negation class-attribute instance-attribute

negation: str = ''

How this tool spells "off": --dirty, not always --no-<name>. Empty when the option is not a negatable flag.

help class-attribute instance-attribute

help: str = ''

The tool's own one-line description, for the stub's docstring.

type_name class-attribute instance-attribute

type_name: str = 'str'

The Python type the stub declares: bool, str, int, list[str].

default class-attribute instance-attribute

default: Any = None

The tool's default, when it states one.

choices class-attribute instance-attribute

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

The closed set of values the tool accepts, when it names one. The stub declares these as a Literal, so an IDE offers them.

since class-attribute instance-attribute

since: str = ''

The release this option first appears in, when the history knows.

Empty when it was already there at the oldest release read: the file must not claim a since it never looked back far enough to see. Derived from the history at render time, never stored per release.

until class-attribute instance-attribute

until: str = ''

The release this option stopped appearing in, when it has gone. A removed option stays in the stub, since completion should work against any version the reader might be running, and this is what says so.

not_on class-attribute instance-attribute

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

The platforms observed to lack this, when any have been. Empty means nothing contradicts it: either every platform that looked found it, or only one ever looked. Derived from the history at render time like since/until: the store records what each platform saw at the release it read, and the standing claim is whatever its newest verdict says.

ToolSpec dataclass

ToolSpec(name: str, help: str = '', version: str = '', verbs: tuple[Verb, ...] = tuple(), in_process: bool = False)

Everything footman knows about one tool, from the tool itself.

Methods:

Name Description
negations

Map each option to its negation where it is not --no-<name>.

wrappers

The dotted verb paths that wrap a command.

color_flags

The colour switch this tool exposes, per verb.

Attributes:

Name Type Description
name str
help str
version str

The version this was extracted from, what an audit compares.

verbs tuple[Verb, ...]
in_process bool

Whether the tool can run inside footman's process (it publishes a

name instance-attribute

name: str

help class-attribute instance-attribute

help: str = ''

version class-attribute instance-attribute

version: str = ''

The version this was extracted from, what an audit compares.

verbs class-attribute instance-attribute

verbs: tuple[Verb, ...] = field(default_factory=tuple)

in_process class-attribute instance-attribute

in_process: bool = False

Whether the tool can run inside footman's process (it publishes a [console_scripts] entry point).

negations

negations() -> dict[str, str]

Map each option to its negation where it is not --no-<name>.

Only the exceptions: a table of things that already work would be noise, and would have to be regenerated far more often.

Source code in packages/toolroom-store/src/livery/toolroom/store/_spec.py
def negations(self) -> dict[str, str]:
    """Map each option to its negation where it is not `--no-<name>`.

    Only the exceptions: a table of things that already work would be
    noise, and would have to be regenerated far more often.
    """
    exceptions: dict[str, str] = {}
    for verb in self.verbs:
        for option in verb.options:
            if not option.negation:
                continue
            default = "--no-" + option.name.replace("_", "-")
            if option.negation != default:
                exceptions[option.name] = option.negation
    return exceptions

wrappers

wrappers() -> frozenset[str]

The dotted verb paths that wrap a command.

The bridge places a wrapper's flags before the child's argv instead of passing them into the child.

Source code in packages/toolroom-store/src/livery/toolroom/store/_spec.py
def wrappers(self) -> frozenset[str]:
    """The dotted verb paths that wrap a command.

    The bridge places a wrapper's flags before the child's argv
    instead of passing them into the child.
    """
    return frozenset(verb.name for verb in self.verbs if verb.wraps)

color_flags

color_flags() -> dict[str, tuple[str, str, str]]

The colour switch this tool exposes, per verb.

The value is {verb: (flag, on, off)}.

A verb with a --color/--colour/--colors option taking a closed set that includes always/never: the spelling footman would force to make the tool colour past its own non-tty check (or stay quiet past an ignored NO_COLOR). Both directions fall out of the one choices list, so detecting the off form costs nothing. Empty when the tool has no such switch, in which case it is assumed to obey FORCE_COLOR/NO_COLOR. This informs the curated _COLOR table (via fm toolroom.color); it is not applied automatically: a flag is only added for a tool proven to ignore the environment.

Source code in packages/toolroom-store/src/livery/toolroom/store/_spec.py
def color_flags(self) -> dict[str, tuple[str, str, str]]:
    """The colour switch this tool exposes, per verb.

    The value is `{verb: (flag, on, off)}`.

    A verb with a `--color`/`--colour`/`--colors` option taking a closed set
    that includes `always`/`never`: the spelling footman would force to
    make the tool colour past its own non-tty check (or stay quiet past an
    ignored `NO_COLOR`). Both directions fall out of the one `choices` list,
    so detecting the *off* form costs nothing. Empty when the tool has no
    such switch, in which case it is assumed to obey `FORCE_COLOR`/`NO_COLOR`.
    This informs the curated `_COLOR` table (via `fm toolroom.color`);
    it is not applied automatically: a flag is only added for a tool proven
    to ignore the environment.
    """
    found: dict[str, tuple[str, str, str]] = {}
    for verb in self.verbs:
        for option in verb.options:
            detected = _color_option(option)
            if detected is not None:
                found[verb.name] = detected
                break
    return found

Verb dataclass

Verb(name: str, help: str = '', options: tuple[Option, ...] = (), not_on: tuple[str, ...] = (), wraps: bool = False, positional: str = 'any', lead: str = '')

A subcommand: mkdocs build, ruff check.

Attributes:

Name Type Description
name str
help str
options tuple[Option, ...]
not_on tuple[str, ...]

The platforms observed to lack this whole subcommand. Said once here

wraps bool

Whether the verb runs another command: uv run, docker exec,

positional str

What positionals the verb takes, read from its usage line. The stub

lead str

The name of the required leading positional, when positional is

name instance-attribute

name: str

help class-attribute instance-attribute

help: str = ''

options class-attribute instance-attribute

options: tuple[Option, ...] = ()

not_on class-attribute instance-attribute

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

The platforms observed to lack this whole subcommand. Said once here rather than on each of its options, which is both smaller and what a reader wants: the command is missing, not forty flags.

wraps class-attribute instance-attribute

wraps: bool = False

Whether the verb runs another command: uv run, docker exec, coverage run. Its usage trails a [COMMAND] [ARG...] (or "program options"), and everything after the verb's own arguments belongs to the wrapped program. The bridge must place this call's flags before those arguments, or they leak past the tool into the child.

positional class-attribute instance-attribute

positional: str = 'any'

What positionals the verb takes, read from its usage line. The stub renders this with / and *:

  • "any": zero or more (ruff check [FILES]...), or unknown. The conservative default: *args, forbids nothing.
  • "none": the tool declares only options (mkdocs build [OPTIONS]), so the stub is keyword-only and a stray positional is a type error.
  • "required": a required leading positional (docker run IMAGE …), named by lead; the stub makes it positional-only.

lead class-attribute instance-attribute

lead: str = ''

The name of the required leading positional, when positional is "required": image for docker run, repo for git clone.

NameCollision

Bases: ValueError

A verb would generate a class named like one of the stub's imports.

The generated names are title-cased verbs, so a verb literally called tool-base or flag would shadow the import inside its tool's class body and every annotation after it would silently mean the wrong thing. No real tool spells such a verb; refusing loudly keeps the checked-in stub (sync and restub skip, and say why) until the renderer is taught an escape hatch it has never yet needed.

TableError

Bases: ValueError

A configuration file the table cannot be read from; the message names it.

build_current

build_current(index: Path) -> bool

Whether the index at index stands as its build record fingerprints it.

The build writes build.json beside the pointer, naming the records directory with a stat fingerprint. Current means the pointer is there, the record reads, and the fingerprint stands; anything else, an absent record included, is not current. Stats alone are read, so the answer costs milliseconds and a caller can skip a build, or the spawn of one, without reading a record.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def build_current(index: Path) -> bool:
    """Whether the index at *index* stands as its build record fingerprints it.

    The build writes `build.json` beside the pointer, naming the records
    directory with a stat fingerprint. Current means the pointer is
    there, the record reads, and the fingerprint stands; anything else,
    an absent record included, is not current. Stats alone are read, so the answer costs
    milliseconds and a caller can skip a build, or the spawn of one,
    without reading a record.
    """
    try:
        held = json.loads((index / BUILD_FILE).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return False
    if not isinstance(held, dict) or not (index / POINTER).is_file():
        return False
    records = held.get("records")
    if not isinstance(records, dict) or not isinstance(records.get("path"), str):
        return False
    return bool(tree_fingerprint([records["path"]]) == records.get("fingerprint"))

index_source

index_source(table: Mapping[str, object], root: Path) -> str

Where a workspace reads its catalogue, as its [toolroom] index names it.

A URL is the published index; a path, relative to root, is a directory holding an index or the records that build one.

Raises:

Type Description
CatalogueError

when the table names no source.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def index_source(table: Mapping[str, object], root: Path) -> str:
    """Where a workspace reads its catalogue, as its ``[toolroom] index`` names it.

    A URL is the published index; a path, relative to *root*, is a
    directory holding an index or the records that build one.

    Raises:
        CatalogueError: when the table names no source.
    """
    declared = table.get("index")
    if not isinstance(declared, str) or not declared:
        raise CatalogueError(
            "workshop.toml: [toolroom] index names no source; set it to the"
            " published index's URL, or to a directory holding an index or the"
            " records"
        )
    if "://" in declared:
        return declared
    return str(root / declared)

is_records

is_records(source: str) -> bool

Whether source is a directory of records rather than an index.

A directory with no pointer file and record files in it; a URL never.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def is_records(source: str) -> bool:
    """Whether *source* is a directory of records rather than an index.

    A directory with no pointer file and record files in it; a URL never.
    """
    if "://" in source:
        return False
    directory = Path(source)
    return not (directory / POINTER).is_file() and bool(records_in(directory))

read_pointer

read_pointer(source: str) -> dict[str, Any]

The pointer document at source, a directory or an HTTP base URL.

Raises:

Type Description
CatalogueError

when no pointer can be read there, or what is read is not one.

Source code in packages/toolroom-store/src/livery/toolroom/store/_catalogue.py
def read_pointer(source: str) -> dict[str, Any]:
    """The pointer document at *source*, a directory or an HTTP base URL.

    Raises:
        CatalogueError: when no pointer can be read there, or what is
            read is not one.
    """
    return _read_pointer(source)

bun_global_project

bun_global_project(install_root: Path) -> Path

The global project bun installs into under install_root, made empty.

bun's global install lives at <BUN_INSTALL>/install/global and looks for the project to install into by walking up from there, so with no project of its own it installs into the nearest ancestor holding a package.json, a home directory's included. An empty project made first is where the walk stops.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def bun_global_project(install_root: Path) -> Path:
    """The global project bun installs into under *install_root*, made empty.

    bun's global install lives at `<BUN_INSTALL>/install/global` and
    looks for the project to install into by walking up from there,
    so with no project of its own it installs into the nearest
    ancestor holding a `package.json`, a home directory's included.
    An empty project made first is where the walk stops.
    """
    project = install_root / "install" / "global"
    project.mkdir(parents=True, exist_ok=True)
    manifest = project / "package.json"
    if not manifest.is_file():
        manifest.write_text("{}\n", encoding="utf-8")
    return manifest

npm_cli

npm_cli(node: Path) -> Path

The npm-cli.js node ships beside node, in either layout node publishes.

A POSIX distribution has bin/node and lib/node_modules/npm; a Windows one has node.exe and node_modules/npm side by side.

Raises:

Type Description
StoreError

naming both places when neither holds it.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def npm_cli(node: Path) -> Path:
    """The `npm-cli.js` node ships beside *node*, in either layout node publishes.

    A POSIX distribution has `bin/node` and `lib/node_modules/npm`; a
    Windows one has `node.exe` and `node_modules/npm` side by side.

    Raises:
        StoreError: naming both places when neither holds it.
    """
    candidates = (
        node.parent.parent / "lib" / "node_modules" / "npm" / "bin" / "npm-cli.js",
        node.parent / "node_modules" / "npm" / "bin" / "npm-cli.js",
    )
    for candidate in candidates:
        if candidate.is_file():
            return candidate
    raise StoreError(
        f"{node}: no npm beside it; looked for {candidates[0]} and {candidates[1]}"
    )

silent

silent(_event: Event) -> None

The default progress: drop the event.

Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
def silent(_event: Event) -> None:
    """The default progress: drop the event."""

api_headers

api_headers(url: str) -> dict[str, str]

The headers a read of url sends: a user agent, and GitHub's token for its API.

The token comes from the environment (GH_TOKEN, then GITHUB_TOKEN) so nothing here depends on a CLI: GitHub allows 60 unauthenticated API calls an hour per address and 5,000 with a token, and a shared runner spends the smaller budget on whoever else is on it. Only a URL on GitHub's API host gets the token; livery.strongroom.fetch_url keeps it off any other host a redirect reaches.

Source code in packages/toolroom-store/src/livery/toolroom/store/_fetch.py
def api_headers(url: str) -> dict[str, str]:
    """The headers a read of *url* sends: a user agent, and GitHub's token for its API.

    The token comes from the environment (`GH_TOKEN`, then
    `GITHUB_TOKEN`) so nothing here depends on a CLI: GitHub allows 60
    unauthenticated API calls an hour per address and 5,000 with a
    token, and a shared runner spends the smaller budget on whoever
    else is on it. Only a URL on GitHub's API host gets the token;
    [livery.strongroom.fetch_url][] keeps it off any other host a
    redirect reaches.
    """
    headers = {"User-Agent": USER_AGENT}
    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
    if token and url.startswith("https://api.github.com/"):
        headers["Authorization"] = f"Bearer {token}"
    return headers

fetch_bytes

fetch_bytes(url: str, *, headers: Mapping[str, str] | None = None, tries: int = TRIES, connect_timeout: float = 10.0, transfer_timeout: float = 600.0) -> bytes

The bytes at url, read whole; a transient failure is tried tries times.

headers default to livery.toolroom.store.api_headers for the URL.

Raises:

Type Description
FetchError

when the tries are spent, or at once for an answer that says the object is not there.

Source code in packages/toolroom-store/src/livery/toolroom/store/_fetch.py
def fetch_bytes(
    url: str,
    *,
    headers: Mapping[str, str] | None = None,
    tries: int = TRIES,
    connect_timeout: float = 10.0,
    transfer_timeout: float = 600.0,
) -> bytes:
    """The bytes at *url*, read whole; a transient failure is tried *tries* times.

    *headers* default to [livery.toolroom.store.api_headers][] for the
    URL.

    Raises:
        FetchError: when the tries are spent, or at once for an answer
            that says the object is not there.
    """
    sent = dict(headers) if headers is not None else api_headers(url)
    last: Unreachable | None = None
    for attempt in range(max(1, tries)):
        try:
            with fetch_url(
                url,
                connect_timeout=connect_timeout,
                transfer_timeout=transfer_timeout,
                headers=sent,
            ) as response:
                return response.read()
        except Unreachable as error:
            last = error
            if not transient(error) or attempt + 1 == tries:
                break
            sleep(BACKOFF * (attempt + 1))
    raise FetchError(f"{url}: {last}", status=last.status if last else None)

fetch_file

fetch_file(url: str, into: Path, *, tries: int = TRIES) -> Path

Download url into into, named by its last path segment; the file.

A file already there with bytes in it is the download, so a second ask costs nothing. A download that fails part-way leaves nothing behind: a part-written file is never a hit.

Raises:

Type Description
FetchError

when the URL cannot be read after the tries.

Source code in packages/toolroom-store/src/livery/toolroom/store/_fetch.py
def fetch_file(url: str, into: Path, *, tries: int = TRIES) -> Path:
    """Download *url* into *into*, named by its last path segment; the file.

    A file already there with bytes in it is the download, so a second
    ask costs nothing. A download that fails part-way leaves nothing
    behind: a part-written file is never a hit.

    Raises:
        FetchError: when the URL cannot be read after the tries.
    """
    into.mkdir(parents=True, exist_ok=True)
    dest = into / url.rsplit("/", 1)[-1]
    if dest.is_file() and dest.stat().st_size:
        return dest
    last: Unreachable | None = None
    for attempt in range(max(1, tries)):
        try:
            with (
                fetch_url(
                    url,
                    connect_timeout=10.0,
                    transfer_timeout=600.0,
                    headers=api_headers(url),
                ) as response,
                dest.open("wb") as out,
            ):
                shutil.copyfileobj(response, out)
            return dest
        except (Unreachable, OSError) as error:
            dest.unlink(missing_ok=True)
            last = error if isinstance(error, Unreachable) else Unreachable(str(error))
            if not transient(last) or attempt + 1 == tries:
                break
            sleep(BACKOFF * (attempt + 1))
    raise FetchError(f"{url}: {last}", status=last.status if last else None)

fetch_json

fetch_json(url: str, *, tries: int = TRIES) -> Any

The JSON at url, whatever shape the endpoint answers with.

Raises:

Type Description
FetchError

when the URL cannot be read, or answers with something that is not JSON.

Source code in packages/toolroom-store/src/livery/toolroom/store/_fetch.py
def fetch_json(url: str, *, tries: int = TRIES) -> Any:
    """The JSON at *url*, whatever shape the endpoint answers with.

    Raises:
        FetchError: when the URL cannot be read, or answers with
            something that is not JSON.
    """
    data = fetch_bytes(url, tries=tries)
    try:
        return json.loads(data.decode("utf-8"))
    except ValueError as error:
        raise FetchError(f"{url}: answered, but not with JSON ({error})") from error

unpack

unpack(archive: Path, into: Path, *, name: str = '', format: str = '') -> None

Extract archive, a zip or a tar, whole into into.

name is the archive's file name when the path does not carry it (an object landed by digest); its suffix decides the format unless format says zip or tar, for an archive whose name lies. A zip member's mode is restored where it is set, and a tar is extracted with the data filter, so a member cannot write outside into.

Raises:

Type Description
UnpackError

for a suffix the store does not unpack, or an archive that will not extract.

Source code in packages/toolroom-store/src/livery/toolroom/store/_fetch.py
def unpack(archive: Path, into: Path, *, name: str = "", format: str = "") -> None:
    """Extract *archive*, a zip or a tar, whole into *into*.

    *name* is the archive's file name when the path does not carry it
    (an object landed by digest); its suffix decides the format unless
    *format* says `zip` or `tar`, for an archive whose name lies. A
    zip member's mode is restored where it is set, and a tar is
    extracted with the data filter, so a member cannot write outside
    *into*.

    Raises:
        UnpackError: for a suffix the store does not unpack, or an
            archive that will not extract.
    """
    label = (name or archive.name).lower()
    into.mkdir(parents=True, exist_ok=True)
    try:
        if format == "zip" or (not format and label.endswith(".zip")):
            with zipfile.ZipFile(archive) as opened:
                opened.extractall(into)
                root = into.resolve()
                for info in opened.infolist():
                    mode = (info.external_attr >> 16) & 0o777
                    if not mode or info.is_dir():
                        continue
                    target = (into / info.filename).resolve()
                    if target.is_relative_to(root) and target.is_file():
                        target.chmod(mode)
            return
        if format != "tar" and not label.endswith(ARCHIVES):
            raise UnpackError(
                f"{name or archive.name} is not an archive the store unpacks"
            )
        with tarfile.open(archive) as opened:
            opened.extractall(into, filter="data")
    except (tarfile.TarError, zipfile.BadZipFile, OSError) as error:
        raise UnpackError(f"{name or archive.name} will not extract: {error}") from None

tree_fingerprint

tree_fingerprint(paths: Iterable[Path | str]) -> str

The fingerprint of paths, each a file or a directory walked whole.

Every file contributes its path under the argument that named it, its size and its modification time in nanoseconds; a path that does not exist contributes its absence, and the arguments themselves contribute their spelling. Stats alone are read, so a build can ask whether anything moved before it loads a byte. A touched file with the same bytes reads as moved, which costs one rebuild and never a stale one.

Source code in packages/toolroom-store/src/livery/toolroom/store/_fingerprint.py
def tree_fingerprint(paths: Iterable[Path | str]) -> str:
    """The fingerprint of *paths*, each a file or a directory walked whole.

    Every file contributes its path under the argument that named it,
    its size and its modification time in nanoseconds; a path that
    does not exist contributes its absence, and the arguments
    themselves contribute their spelling. Stats alone are read, so a
    build can ask whether anything moved before it loads a byte. A
    touched file with the same bytes reads as moved, which costs one
    rebuild and never a stale one.
    """
    digest = hashlib.sha256()
    for given in paths:
        root = Path(given)
        digest.update(f"{root}\0".encode())
        if root.is_dir():
            files = sorted(p for p in root.rglob("*") if p.is_file())
        elif root.is_file():
            files = [root]
        else:
            digest.update(b"absent\0")
            continue
        for path in files:
            stat = path.stat()
            relative = path.relative_to(root) if root.is_dir() else Path(path.name)
            digest.update(
                f"{relative.as_posix()}\0{stat.st_size}\0{stat.st_mtime_ns}\0".encode()
            )
    return "sha256:" + digest.hexdigest()

resolve_lock

resolve_lock(catalogue: Catalogue, requirements: Iterable[Requirement], *, hosts: Iterable[str], keep: Lock | None = None, upgrade: Iterable[str] = (), host_allowed: Iterable[str] = ()) -> Lock

The lock for requirements against catalogue, on hosts.

Each tool takes the newest version that satisfies every floor declared for it and resolves on every host it is required on: the union of its requirements' scopes, the whole of hosts for one with no scope. A tool required on fewer hosts than the lock's is locked on those and its entry names them; one whose scopes reach no locked host is left out. A tool keep already locks stays at its version when that version still satisfies and resolves, unless it is named in upgrade; a tool no requirement names any more leaves the lock. A tool named in host_allowed carries the allowance in its entry, whatever keep said of it: the allowance is the sites' current word, never a kept one.

An optional requirement (?) is never refused. Its hosts join a tool's entry where the version the required sites chose has an artifact; a tool every site marks optional takes the newest version satisfying its floors that resolves somewhere, is locked where it resolves, and its entry says optional. What is left out, a host or a whole tool, is named in the lock's notes.

Raises:

Type Description
LockError

naming the first requirement that cannot be met: a tool the catalogue does not list, a floor above every version, or a host no eligible version has.

Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
def resolve_lock(
    catalogue: Catalogue,
    requirements: Iterable[Requirement],
    *,
    hosts: Iterable[str],
    keep: Lock | None = None,
    upgrade: Iterable[str] = (),
    host_allowed: Iterable[str] = (),
) -> Lock:
    """The lock for *requirements* against *catalogue*, on *hosts*.

    Each tool takes the newest version that satisfies every floor
    declared for it and resolves on every host it is required on: the
    union of its requirements' scopes, the whole of *hosts* for one
    with no scope. A tool required on fewer hosts than the lock's is
    locked on those and its entry names them; one whose scopes reach
    no locked host is left out. A tool *keep* already locks stays at
    its version when that version still satisfies and resolves,
    unless it is named in *upgrade*; a tool no requirement names any
    more leaves the lock. A tool named in *host_allowed* carries the
    allowance in its entry, whatever *keep* said of it: the allowance
    is the sites' current word, never a kept one.

    An optional requirement (``?``) is never refused. Its hosts join a
    tool's entry where the version the required sites chose has an
    artifact; a tool every site marks optional takes the newest
    version satisfying its floors that resolves somewhere, is locked
    where it resolves, and its entry says ``optional``. What is left
    out, a host or a whole tool, is named in the lock's ``notes``.

    Raises:
        LockError: naming the first requirement that cannot be met:
            a tool the catalogue does not list, a floor above every
            version, or a host no eligible version has.
    """
    locked_hosts = tuple(hosts)
    for host in locked_hosts:
        if host not in HOSTS:
            raise LockError(f"host {host!r} is not one of {', '.join(HOSTS)}")
    by_tool: dict[str, list[Requirement]] = {}
    for requirement in requirements:
        by_tool.setdefault(requirement.name, []).append(requirement)
    moving = set(upgrade)
    allowed = set(host_allowed)
    tools: dict[str, Locked] = {}
    notes: list[str] = []
    for name in sorted(by_tool):
        wants = by_tool[name]
        required = [want for want in wants if not want.optional]
        must = tuple(
            host
            for host in locked_hosts
            if any(host in want.on(locked_hosts) for want in required)
        )
        may = tuple(
            host
            for host in locked_hosts
            if host not in must
            and any(host in want.on(locked_hosts) for want in wants if want.optional)
        )
        if not must and not may:
            continue
        sites = ", ".join(sorted({w.site for w in wants if w.site})) or "a requirement"
        try:
            listed = catalogue.listed(name)
        except CatalogueError as error:
            if not required:
                notes.append(f"{name}: optional and not catalogued ({error}); left out")
                continue
            raise LockError(f"{error}; required by {sites}") from None
        held = keep.tools.get(name) if keep and name not in moving else None
        if required:
            version = (
                held.version
                if held is not None and _eligible(listed, held.version, wants, must)
                else _newest(listed, wants, must)
            )
        else:
            found = _newest_anywhere(listed, wants, may, held)
            if found is None:
                notes.append(
                    f"{name}: optional, and no version satisfying"
                    f" {', '.join(str(w) for w in wants)} resolves on"
                    f" {', '.join(may)}; left out"
                )
                continue
            version = found
        reach = (*must, *(host for host in may if _resolves(listed, version, (host,))))
        on = tuple(host for host in locked_hosts if host in reach)
        absent = [host for host in may if host not in on]
        if absent:
            notes.append(
                f"{name}: optional, {version} has no artifact for"
                f" {', '.join(absent)}; left out there"
            )
        scope = on if on != locked_hosts else ()
        tools[name] = replace(
            _locked(listed, version, on, scope),
            allow_host=name in allowed,
            optional=not required,
        )
    return Lock(locked_hosts, tools, tuple(notes))

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("_"))

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"

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")

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}"

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)

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"]),
    )

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,
        },
    }

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]}")

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

render

render(spec: ToolSpec, *, platform: str = '', class_name: str = '', in_process: str = '') -> str

The full text of stubs/<tool>.pyi for spec.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def render(
    spec: ToolSpec,
    *,
    platform: str = "",
    class_name: str = "",
    in_process: str = "",
) -> str:
    """The full text of `stubs/<tool>.pyi` for *spec*."""
    root = class_name or _class_name(spec.name)
    tree = _tree(spec.verbs)
    taken = _generated_names(tree, root)
    if clash := sorted(taken & _RESERVED_IMPORTS):
        raise NameCollision(
            f"verb class{'es' if len(clash) > 1 else ''} "
            f"{', '.join(clash)} would shadow a stub import"
        )
    hoisted = _hoisted(tree, taken)
    body = _classes(tree, root, hoisted=hoisted)
    aliases = _alias_block(hoisted)
    header = _HEADER.format(
        name=spec.name,
        version=spec.version or "an unpinned version",
        platform=platform or "this machine",
        in_process=in_process or ("available" if spec.in_process else "no"),
        imports=_imports(body, aliases),
    )
    between = f"\n\n{aliases}" if aliases else ""
    return f"{header}\n{_typevars(body)}{between}\n\n{body}"

render_observation

render_observation(name: str, observation: Observation) -> str

The stub of name at one observed version, exactly as that version read.

The verbs and options are the version's own, no history folded in, which is what a workspace types against when it locks that version. The header names the version and the platforms that read it.

Raises:

Type Description
NameCollision

for a verb whose class would shadow a stub import.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def render_observation(name: str, observation: Observation) -> str:
    """The stub of *name* at one observed version, exactly as that version read.

    The verbs and options are the version's own, no history folded in,
    which is what a workspace types against when it locks that version.
    The header names the version and the platforms that read it.

    Raises:
        NameCollision: for a verb whose class would shadow a stub import.
    """
    spec = spec_from(
        {"help": observation.help, "verbs": observation.verbs},
        name=name,
        version=observation.version,
    )
    return render(
        spec,
        platform=platforms_phrase(observation.platforms),
        class_name=class_name(name),
    )

spec_from

spec_from(surface: Mapping[str, Any], *, name: str, version: str = '', in_process: bool = False) -> ToolSpec

The spec a surface describes: the shape the records and the index hold.

surface carries help and verbs, each verb its options in the record's key shape; the inverse of what the bench writes.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def spec_from(
    surface: Mapping[str, Any],
    *,
    name: str,
    version: str = "",
    in_process: bool = False,
) -> ToolSpec:
    """The spec a surface describes: the shape the records and the index hold.

    *surface* carries `help` and `verbs`, each verb its options in the
    record's key shape; the inverse of what the bench writes.
    """
    return ToolSpec(
        name=name,
        help=surface.get("help", ""),
        version=version,
        in_process=in_process,
        verbs=tuple(
            Verb(
                name=verb_name,
                help=verb.get("help", ""),
                wraps=verb.get("wraps", False),
                positional=verb.get("positional", "any"),
                lead=verb.get("lead", ""),
                options=tuple(
                    Option(
                        name=option_name,
                        flags=tuple(option.get("flags", ())),
                        negation=option.get("negation", ""),
                        help=option.get("help", ""),
                        type_name=option.get("type", "str"),
                        default=option.get("default"),
                        choices=tuple(option.get("choices", ())),
                    )
                    for option_name, option in verb.get("options", {}).items()
                ),
            )
            for verb_name, verb in surface.get("verbs", {}).items()
        ),
    )

read_table

read_table(directory: Path) -> dict[str, object]

The [toolroom] table of directory; empty when it declares none.

Read from workshop.toml where the directory has one, and from toolroom.toml otherwise; with neither the table is empty. The table comes back as written: the workshop judges a workspace's keys against the schema it composes, and this reader judges none.

Raises:

Type Description
TableError

when the file is not TOML, or holds toolroom as something other than a table, naming the file.

Source code in packages/toolroom-store/src/livery/toolroom/store/_table.py
def read_table(directory: Path) -> dict[str, object]:
    """The `[toolroom]` table of *directory*; empty when it declares none.

    Read from `workshop.toml` where the directory has one, and from
    `toolroom.toml` otherwise; with neither the table is empty. The
    table comes back as written: the workshop judges a workspace's keys
    against the schema it composes, and this reader judges none.

    Raises:
        TableError: when the file is not TOML, or holds `toolroom` as
            something other than a table, naming the file.
    """
    path = next(
        (directory / name for name in CONFIG_FILES if (directory / name).is_file()),
        None,
    )
    if path is None:
        return {}
    try:
        data = tomllib.loads(path.read_text(encoding="utf-8"))
    except tomllib.TOMLDecodeError as error:
        raise TableError(f"{path}: not TOML: {error}") from error
    table: object = data.get(TABLE, {})
    if not isinstance(table, dict):
        raise TableError(
            f"{path}: [{TABLE}] is {type(table).__name__}; it must be a table"
        )
    return dict(cast("dict[str, Any]", table))

__getattr__

__getattr__(name: str) -> object

Serve a public name from its module on first use, then keep it.

Source code in packages/toolroom-store/src/livery/toolroom/store/__init__.py
def __getattr__(name: str) -> object:
    """Serve a public name from its module on first use, then keep it."""
    found = _EXPORTS.get(name)
    if found is None:
        raise AttributeError(
            f"module 'livery.toolroom.store' has no attribute {name!r}"
        )
    import importlib

    module, attribute = found
    value = getattr(importlib.import_module(module), attribute)
    globals()[name] = value
    return value