livery.toolroom.store._lock¶
livery.toolroom.store._lock ¶
The lock: one version per tool for the repository, resolved against the catalogue.
A requirement is a tool's name with a floor, declared at one of the sites, and may name the hosts it applies to; the sites' requirements union, and the lock takes for each tool the newest version the catalogue lists that satisfies every floor and resolves on every host the tool is required on. A version of a downloaded kind resolves on a host when it has that host's artifact; a delegated kind resolves everywhere its installer does. A requirement that cannot be satisfied refuses naming the tool, each floor and its site, and for a host that no eligible version has, the first version that has it. A tool required on some of the locked hosts alone is locked on those, and the entry says which; one whose scope names no locked host is not locked at all.
The lock is a file in the repository, toolroom.lock, so every checkout
and every runner installs the same version; it moves only through a
lock or an upgrade, never on its own.
Reach for livery.toolroom.store.Requirement, livery.toolroom.store.resolve_lock and livery.toolroom.store.Lock.
Classes:
| Name | Description |
|---|---|
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. |
Graph |
The resolved graph of a delegated tool's version, as the lock names it. |
Locked |
One tool as the lock holds it. |
Lock |
The repository's lock: the hosts it locks for and one version per tool. |
Functions:
| Name | Description |
|---|---|
resolve_lock |
The lock for requirements against catalogue, on hosts. |
Attributes:
| Name | Type | Description |
|---|---|---|
LOCK_FILE |
The lock's name at the repository root. |
|
LOCK_SCHEMA |
The lock's shape. Bumped when a reader must know. |
|
GRAPHS |
The directory beside the lock holding one resolved graph per delegated tool. |
GRAPHS
module-attribute
¶
The directory beside the lock holding one resolved graph per delegated tool.
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.
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
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
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
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 | |