livery.toolroom.store._record¶
livery.toolroom.store._record ¶
The tool record: one tool, every version tracked, each host's deployment and surface.
A record is inert data, authored in git as one file of JSON lines per
tool, records/<tool>.jsonl: the first line is the tool axis, what
does not move with a version; a version line is one version's
arrival, forward and append-only; and the statement lines under a
version line are what its reading changed, one option, one verb's own
fields, one withdrawal or one absence per line. A deployment resolves
through four layers, most specific winning: the tool's layout, the
host's override of it, the version's override, and the version's
override for one host. A version's surface, what its command line
accepts, is carried one option at a time: a reading names the options
and the verb fields the version changed and the tool's description
when it changed, and everything else is inherited from the nearest
earlier version that has a surface. Resolution is total and checked:
loading a record resolves every host of every version and every
version's surface, and refuses a host that resolves incomplete, an
override that names a host or version the record does not carry, an
override, a verb field or an option that restates the value it
inherits, a withdrawal of what no earlier version has, a statement
under a version that was not read, and a reading below the record's
prime, the oldest version its history reaches. A record names a
kind, per host an artifact with a mandatory digest, and the layout; it
never runs a command. A version with no artifact is tracked for its
surface alone: it has no host and nothing installs it.
Reach for livery.toolroom.store.Record.load to read a record, livery.toolroom.store.resolve for one host's deployment at one version, and livery.toolroom.store.surface_at for one version's whole surface; the rest is what a load validates.
Classes:
| Name | Description |
|---|---|
RecordError |
A record that breaks a rule; the message names the field. |
Layout |
One layer's layout fields; a field left |
Artifact |
One host's artifact for one version. |
Deployment |
One host's complete deployment of one version: the artifact and the layout. |
Surface |
One version's reading of the tool's command line, as its record carries it. |
Observation |
What one version accepted, whole, and who looked: its surface resolved. |
Delta |
One version's arrival: its artifacts, what it overrides, and its surface. |
Record |
A tool across every version tracked and every host it has. |
Functions:
| Name | Description |
|---|---|
default_mode |
The materialisation mode a kind takes unless the record or the project says. |
records_in |
The record files under directory, by name; empty when it is not one. |
resolve |
The complete deployment of version on host, through the four layers. |
observations |
Every version's whole surface, in sequence, resolved through inheritance. |
surface_at |
The whole surface of version, or |
validate |
Refuse a record that breaks a rule; every host of every version resolves. |
artifact_format |
What the artifact at url is by its suffix: |
class_name |
The class a tool's stub declares: |
version_key |
How versions order: the numeric run, OpenSSH's patchlevel, then the date. |
host_key |
The host key for a |
schema |
The JSON schema of a record file's lines, for editor completion. |
export_schema |
Write |
Attributes:
| Name | Type | Description |
|---|---|---|
PLATFORMS |
The operating systems a record may name. |
|
ARCHES |
The CPU architectures a record may name. |
|
HOSTS |
The six host keys, |
|
KINDS |
The installer kinds. A |
|
RUNTIMES |
What an |
|
DOWNLOAD_KINDS |
The kinds whose every host needs an artifact. |
|
FORMATS |
What a downloaded artifact is: sniffed from its URL's suffix unless |
|
MODES |
How a materialised tool reaches PATH: its entry points linked into the |
|
PACKAGE_VAR |
The one substitution a deployment's env values may carry: the install root. |
|
VERSION_VAR |
|
|
RECORD_SUFFIX |
A record file's suffix: |
|
LAYOUT_KEYS |
The layout fields an override may set, in the record's key order. |
|
SURFACE_PLATFORMS |
The platforms a reading of a tool's command line may name. |
|
VERB_KEYS |
A verb's fields in a surface, in the record's key order; every one is present. |
|
OPTION_KEYS |
An option's fields in a surface, in the record's key order; every one is present. |
|
TAR_SUFFIXES |
The suffixes of the tar archives the store unpacks. |
|
ARCHIVE_SUFFIXES |
The suffixes of every archive the store unpacks. |
PLATFORMS
module-attribute
¶
The operating systems a record may name.
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.
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.
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.
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.
PACKAGE_VAR
module-attribute
¶
The one substitution a deployment's env values may carry: the install root.
RECORD_SUFFIX
module-attribute
¶
A record file's suffix: records/<tool>.jsonl, named by the tool.
LAYOUT_KEYS
module-attribute
¶
The layout fields an override may set, in the record's key order.
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.
OPTION_KEYS
module-attribute
¶
An option's fields in a surface, in the record's key order; every one is present.
TAR_SUFFIXES
module-attribute
¶
The suffixes of the tar archives the store unpacks.
ARCHIVE_SUFFIXES
module-attribute
¶
ARCHIVE_SUFFIXES = (*TAR_SUFFIXES, '.zip')
The suffixes of every archive the store unpacks.
RecordError ¶
Bases: ValueError
A record that breaks a rule; the message names the field.
Layout
dataclass
¶
Layout(root: str | None = None, file: str | None = None, format: str | None = None, entry_points: tuple[str, ...] | None = None, paths: tuple[str, ...] | None = None, env: Mapping[str, str] | None = None, shims: Mapping[str, str] | None = None, exclude: tuple[str, ...] | None = None)
One layer's layout fields; a field left None is inherited.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
str | None
|
The directory inside the archive to hoist to the install
root; empty keeps the archive's own top. May carry
|
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
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
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
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
¶
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, ...]]]
|
Delta
dataclass
¶
Delta(sequence: int, version: str, date: str = '', artifacts: dict[str, Artifact] = dict(), layout: Layout = Layout(), host_layouts: dict[str, Layout] = dict(), surface: Surface | None = None)
One version's arrival: its artifacts, what it overrides, and its surface.
Attributes:
| Name | Type | Description |
|---|---|---|
sequence |
int
|
The delta's place in the record, from 1, consecutive: the version line's place in the file. |
version |
str
|
The version string this delta adds. |
date |
str
|
When the version arrived, |
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 |
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
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
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
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
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 | |
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
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
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
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 | |