livery.workshop._tool_tasks¶
livery.workshop._tool_tasks ¶
The tools group: declare a tool, lock the versions, upgrade one, write the stubs.
Every verb resolves against the catalogue [toolroom] index names and
writes toolroom.lock at the root; a lock that cannot be met refuses
naming the tool, each floor with the site that declared it, and the
host no eligible version has. Each lock verb then writes the stubs
under typings/, and restub writes them alone.
Functions:
| Name | Description |
|---|---|
tools_lock |
Resolve every site's requirements and write |
tools_add |
Declare a tool at the project site, lock it, and materialise it. |
tools_sync |
Match this machine to |
sync_tools |
Match this machine to root's |
tools_restub |
Write the stubs the catalogue offers into |
Attributes:
| Name | Type | Description |
|---|---|---|
tools |
|
tools
module-attribute
¶
tools = group('toolroom', help='The tools the workspace requires: declare, lock, upgrade, restub')
tools_lock ¶
tools_lock(upgrade: Annotated[bool, doc('move every entry to the newest version that satisfies')] = False, upgrade_tool: Annotated[list[str] | None, doc('move just these entries to their newest')] = None, check: Annotated[bool, doc('report whether the lock is current; write nothing')] = False, relock: Annotated[list[str] | None, doc('delegated tools whose graph is resolved again')] = None) -> None
Resolve every site's requirements and write toolroom.lock.
An entry the lock already holds stands while it still satisfies
every floor and resolves on every locked host; a tool no site
requires any more leaves the lock. Nothing on a machine changes:
the lock says what a checkout installs, and sync installs it.
--upgrade moves every entry to the newest version that
satisfies, and --upgrade-tool moves the ones it names. An
upgrade is an act on the repository: every package runs the version
the lock names, so one entry moving moves every package with it.
--check answers whether the lock is current and writes nothing,
exiting non-zero when it would move. A delegated tool's resolved
graph is written when its version enters the lock and kept after;
--relock writes one again though the version stands, which is
what an install asks for when it refuses because the runtime has no
build for what the graph pins.
Source code in packages/workshop/src/livery/workshop/_tool_tasks.py
tools_add ¶
Declare a tool at the project site, lock it, and materialise it.
The requirement joins [toolroom] requires in the root workshop.toml
unless it is already there, the lock is resolved with it, and the
tool is supplied through the store on this machine with its receipt
written. A spelling that is not a requirement refuses before
anything is written.
Source code in packages/workshop/src/livery/workshop/_tool_tasks.py
tools_sync ¶
tools_sync(frozen: Annotated[bool, doc('install the lock as it is; never resolve')] = False, locked: Annotated[bool, doc('refuse if the lock is not current')] = False, offline: Annotated[bool, doc("supply from the machine's store and its sources only")] = False) -> None
Match this machine to toolroom.lock, writing the lock first if it must.
What sync does for the tools alone, in uv's shape. By default the
lock is written when there is none or when the sites' requirements
have moved past it, and then every tool it names is supplied
through the store, a receipt per tool says what reached PATH, and
the stubs follow. A tool the store cannot supply is reported and
the others are supplied.
--frozen installs the lock exactly as it is and resolves
nothing, which is what a CI job wants: a runner's checkout is
judged, never re-resolved. --locked refuses when the lock is
not current instead of writing it, which is the assertion a gate
makes. --offline reads the catalogue and the deployments from
the machine's store alone.
Source code in packages/workshop/src/livery/workshop/_tool_tasks.py
sync_tools ¶
sync_tools(root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False) -> None
Match this machine to root's toolroom.lock, writing it first if it must.
The engine behind toolroom.sync, taking the workspace root as an
argument: a birth runs it for the newborn from inside its own
task, and a task may not change the process directory, so the
root travels as a value; sync calls it for the same reason.
The flags mean what the task's do. Once the lock stands, the
receipts are read before anything is supplied
(livery.workshop._reconcile.tools_current): when every tool the
lock holds for this host has its receipt at the locked version and
its directory in the store, nothing is supplied and the line says
the tools are up to date. A receipt that is off names itself, and
the supply writes it again.
Source code in packages/workshop/src/livery/workshop/_tool_tasks.py
tools_restub ¶
tools_restub(offline: Annotated[bool, doc("read the index from the machine's store only")] = False) -> None
Write the stubs the catalogue offers into typings/.
One stub per tool the lock holds, at the locked version, as
livery.toolroom.stubs modules, and livery.toolroom.handles
beside them declaring the handles for the tools package's index to
import. The four checkers read typings/ first,
so a locked tool's handle completes with its own verbs and flags;
a tool the workspace does not deploy gets no stub and types as a
bare Tool. sync and the lock verbs write them too; this writes
them alone, offline from the machine's store with --offline.