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 |
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 |
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: |
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: |
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 |
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 |
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: |
class_name |
The class a tool's stub declares: |
default_mode |
The materialisation mode a kind takes unless the record or the project says. |
export_schema |
Write |
host_key |
The host key for a |
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 |
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 |
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 |
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: |
|
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, |
|
KINDS |
The installer kinds. A |
|
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: |
|
RUNTIMES |
What an |
|
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__ |
|
BUILD_FILE
module-attribute
¶
The build's record beside the pointer: what it fingerprinted, so a gate can ask.
POINTER
module-attribute
¶
The pointer document at an index's root, naming each tool's tree.
LINKS
module-attribute
¶
The manifest a bin directory keeps of the links the engine made there.
Progress
module-attribute
¶
Receives every event; must not raise.
TOOLS
module-attribute
¶
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
¶
The namespace of URL-keyed downloads, the convention strongroom publishes; volatile.
GRAPHS
module-attribute
¶
The directory beside the lock holding one resolved graph per delegated tool.
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
¶
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
¶
The six host keys, <platform>-<arch>. A record carries any subset.
KINDS
module-attribute
¶
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
¶
The layout fields an override may set, in the record's key order.
MODES
module-attribute
¶
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
¶
An option's fields in a surface, in the record's key order; every one is present.
PACKAGE_VAR
module-attribute
¶
The one substitution a deployment's env values may carry: the install root.
PLATFORMS
module-attribute
¶
The operating systems a record may name.
RECORD_SUFFIX
module-attribute
¶
A record file's suffix: records/<tool>.jsonl, named by the tool.
RUNTIMES
module-attribute
¶
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
¶
The platforms a reading of a tool's command line may name.
VERB_KEYS
module-attribute
¶
A verb's fields in a surface, in the record's key order; every one is present.
CONFIG_FILES
module-attribute
¶
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
¶
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']
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. |
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
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
stub ¶
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
at
classmethod
¶
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
of_records
classmethod
¶
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
of_index
classmethod
¶
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
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 |
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. |
DamagedView ¶
Delta
dataclass
¶
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
|
tree |
Digest | None
|
The tree |
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. |
paths
property
¶
The directories the deployment puts on PATH, under the tool directory.
Event
dataclass
¶
Fetched
dataclass
¶
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
probe ¶
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
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 |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
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 |
Source code in packages/toolroom-store/src/livery/toolroom/store/_engine.py
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
audit ¶
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
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
mend_view ¶
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
link ¶
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
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
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
StoreError ¶
Bases: Exception
A tool the store cannot supply; the message names the tool and the reason.
FetchError ¶
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
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: |
Methods:
| Name | Description |
|---|---|
under |
The store's home under a runner's data directory, |
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. |
under
classmethod
¶
The store's home under a runner's data directory, toolroom in it.
tool_dir ¶
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.
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
Graph
dataclass
¶
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 |
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. |
to_json ¶
from_json
classmethod
¶
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
Lock
dataclass
¶
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. |
notes
class-attribute
instance-attribute
¶
on_host ¶
The tools locked for host, in name order.
to_json ¶
The lock as a JSON object, tools in name order.
Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
load
classmethod
¶
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
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 |
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. |
applies ¶
to_json ¶
The entry as a JSON object.
Source code in packages/toolroom-store/src/livery/toolroom/store/_lock.py
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
( |
optional |
bool
|
Whether |
exclude |
tuple[str, ...]
|
The platforms and host keys |
Methods:
| Name | Description |
|---|---|
parse |
A requirement from its spelling, |
__str__ |
|
satisfied_by |
Whether version is at or above the floor. |
on |
The hosts of locked this requirement applies to, in their order. |
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
satisfied_by ¶
on ¶
The hosts of locked this requirement applies to, in their order.
Artifact
dataclass
¶
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. |
__post_init__ ¶
Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
to_json ¶
from_json
classmethod
¶
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
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, |
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 |
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. |
to_json ¶
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
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
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
|
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 |
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
|
shims |
Mapping[str, str] | None
|
Link name to an executable the install carries, such as
|
exclude |
tuple[str, ...] | None
|
Patterns of archive members left out before import,
install-relative and forward-slashed, |
Methods:
| Name | Description |
|---|---|
set_fields |
The fields this layer sets, in |
to_json |
The set fields as a JSON object, in |
from_json |
A layer from its JSON object. |
set_fields ¶
The fields this layer sets, in LAYOUT_KEYS order.
to_json ¶
The set fields as a JSON object, in LAYOUT_KEYS order.
Source code in packages/toolroom-store/src/livery/toolroom/store/_record.py
from_json
classmethod
¶
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
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 |
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
|
description |
str
|
One line on what the tool is. |
kind |
str
|
One of |
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 |
mode |
str
|
How the tool reaches PATH once materialised, one of
|
min_version |
str
|
The floor a |
hosts |
tuple[str, ...]
|
The host keys the tool has, from |
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 |
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, |
save |
Write the record as |
host_layouts
class-attribute
instance-attribute
¶
__post_init__ ¶
delta_for ¶
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
hosts_of ¶
to_json ¶
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
from_json
classmethod
¶
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
lines ¶
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
parse
classmethod
¶
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
load
classmethod
¶
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
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
|
extractor |
int
|
The generation of the reader that took the reading, a positive integer. |
help |
str | None
|
The tool's own description, or |
verbs |
Mapping[str, Mapping[str, Any] | None]
|
Verb name to its patch: an object with any of the verb's
own fields ( |
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 |
verbs
class-attribute
instance-attribute
¶
Scope
dataclass
¶
The hosts a requirement is limited to, as written after @.
Attributes:
| Name | Type | Description |
|---|---|---|
include |
tuple[str, ...]
|
The platforms and host keys named without |
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 |
parse
classmethod
¶
The scope comma-separated text spells, every token checked.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text
|
str
|
The tokens after |
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
hosts ¶
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
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 |
optional |
bool
|
Whether |
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. |
parse
classmethod
¶
The requirement text spells.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text
|
str
|
|
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
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: |
flags |
tuple[str, ...]
|
What the tool accepts, longest first: |
negation |
str
|
How this tool spells "off": |
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 |
flags
class-attribute
instance-attribute
¶
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
¶
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
¶
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 |
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 |
version
class-attribute
instance-attribute
¶
version: str = ''
The version this was extracted from, what an audit compares.
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 ¶
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
wrappers ¶
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
color_flags ¶
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
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: |
positional |
str
|
What positionals the verb takes, read from its usage line. The stub |
lead |
str
|
The name of the required leading positional, when |
not_on
class-attribute
instance-attribute
¶
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 bylead; the stub makes it positional-only.
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 ¶
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
index_source ¶
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
is_records ¶
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
read_pointer ¶
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
bun_global_project ¶
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
npm_cli ¶
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
api_headers ¶
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
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
fetch_file ¶
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
fetch_json ¶
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
unpack ¶
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
tree_fingerprint ¶
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
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
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 | |
artifact_format ¶
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
class_name ¶
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
default_mode ¶
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
export_schema ¶
export_schema(path: Path) -> None
Write schema() to path as indented JSON with a trailing newline.
host_key ¶
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
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
records_in ¶
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
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
schema ¶
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
1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 | |
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
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
1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 | |
version_key ¶
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
render ¶
The full text of stubs/<tool>.pyi for spec.
Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
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
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
read_table ¶
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 |
Source code in packages/toolroom-store/src/livery/toolroom/store/_table.py
__getattr__ ¶
Serve a public name from its module on first use, then keep it.