livery.workshop._tools¶
livery.workshop._tools ¶
The tools a workspace requires: six declaration sites, one lock, receipts.
A tool requirement is a name with a floor, git or git>=2.40, and
six sites declare them: the base, under [toolroom] requires in its
contract file, for uv, which makes the venv every step runs in; the
steps that judge a present package, each naming its tools; a listed
extension, the workspace's or one a package's set holds, under
[toolroom] requires in its extension.toml, for the tools it runs
(cmake's cmake and ninja, conan's conan), and in a [for.<target>]
table, for what it needs while that table applies; a plugin the
project mounts, through its workshop.tools entry point; a package
instance, in its workshop.toml under [toolroom] requires, for what
its extensions cannot know; and the project, in the root contract's
[toolroom] requires, for what belongs to the repository. The sites'
requirements union, and toolroom.lock at the root holds one version
per tool for the whole repository, the newest the catalogue lists that
satisfies every floor and resolves on every supported host. The root
contract's [workspace] hosts names those hosts, every host key when
it is absent, and [toolroom] index names where the catalogue is read
from: the published index by URL, a directory holding one, or the
records that build one.
Entering the environment materialises the bundle the sites require, on
fm sync and on fm toolroom.add: each locked tool is supplied through
the machine's store in one of three modes, its entry points linked
into the checkout's bin directory, its own directories on PATH, or no
PATH at all, and a receipt under .workshop/receipts/ records the
exact version, the host, the deployment's digest and what reached
PATH. A receipt is a checkout's statement of what it installed, as the
release train's receipt is a release's; fm env.check reads them
back and names the drift when the lock's deployment has moved under
one.
The stubs the type checkers read are materialised too, into typings/
at the root, pyright's default stub path and a search path the rendered
configuration hands the other three checkers: one rendering per tool
the lock holds, at the locked version, as livery.toolroom.stubs
modules with livery.toolroom.handles beside them declaring each
handle, which the installed tools package's index imports. Both live
under the livery.toolroom namespace package, beside the tools package
and never inside its directory: a tree inside it would shadow the
package for a checker run on explicit paths. The store renders each
stub from the locked version's own surface, from the records or from
the index, so no source holds a stub. A tool the workspace does not
deploy gets no stub. fm toolroom.restub writes them, and so do fm sync
and every lock verb.
Classes:
| Name | Description |
|---|---|
ToolReceipt |
What this checkout installed of one tool, as its file records it. |
Materialised |
What one materialisation did to one tool. |
Stubbed |
What |
Functions:
| Name | Description |
|---|---|
tools_table |
The |
base_requirements |
The tools the base requires in every workspace, at the site |
requirements |
Every requirement the six sites declare, in site order. |
plugin_tools |
The tools each plugin the project mounts declares, by its entry point name. |
host_allowed |
The tools whose copy on the machine may serve: the root contract's. |
unrequired_allowances |
The host-allowed names no site requires yet, sorted: allowances ahead of need. |
tool_names |
The tools the sites require, each once, in the order first declared. |
this_host |
This machine's host key as the store names it: |
supported_hosts |
The hosts the workspace supports and locks for, in host-key order. |
index_source |
Where the catalogue is read from, as |
has_index |
Whether the root contract names a catalogue source at all. |
receipt_gap |
Why what receipt claims does not hold here; empty when it does. |
store_cannot_supply |
Why the store supplies nothing here; empty when it can. |
catalogue |
The catalogue the repository resolves against, from |
forget_catalogues |
Drop every catalogue this process read, so the next read is fresh. |
store_home |
The tool store's home on this machine, where every checkout's tools are. |
lock_path |
The lock's file, |
current_lock |
The lock as committed, or |
lock_is_current |
Whether |
write_lock |
Resolve the sites' requirements and write the lock; the lock written. |
unreached_scopes |
One line per scoped requirement no locked host matches, and so locks nothing. |
resolve_graph |
Resolve package at version and write its graph; the graph or why not. |
exe |
name as this platform spells an executable. |
graphs_dir |
Where the resolved graphs live, beside the lock. |
with_graphs |
lock with a graph per delegated tool, and what to say about it. |
runtime_of |
The runtime a tool runs on: an |
with_runtimes |
found, plus each runtime a tool among them runs on and nothing names. |
declare |
Add text to the project's |
receipts_dir |
The checkout's receipts directory. |
bin_dir |
The checkout's bin directory. |
tool_receipts |
What the checkout at root installed of each tool, by the tool's name. |
mode_of |
The mode name materialises in: the project's say, the record's, the kind's. |
sources |
The tiers consulted before an origin, |
site_floors |
The highest floor the sites declare per tool, with the site that asked. |
materialise |
Supply every locked tool, or names alone, and write their receipts. |
typings_dir |
The typings directory the stubs are written under. |
stubs_dir |
The |
stubs_present |
How many tool stubs the typings directory holds. |
write_stubs |
Write the stubs of the locked tools into the typings directory. |
source_mark |
What the catalogue source is right now, in one digest, without reading it whole. |
handles_path |
The |
handles_index |
The |
stub_lines |
Write the stubs and say what happened, as |
emission |
What the receipts add to an entered shell: PATH entries and variables. |
drift |
Per tool the sites require, what |
undeployed |
Refuse the task: name is a tool of the store and is not on |
Attributes:
| Name | Type | Description |
|---|---|---|
WORKSPACE |
The contract table the supported hosts live under. |
|
DEFAULT_HOSTS |
tuple[str, ...]
|
The hosts supported when |
VERDICT_PHASES |
The phases whose tools take no host allowance: the version is the verdict. |
|
PINNED_TOOLS |
The tools no allowance reaches by name: the entry pins uv. |
|
BASE_SITE |
The site of the base's own requirements, the ones every workspace has. |
|
TYPINGS |
The directory under the root the stubs are written into, pyright's default. |
|
TYPINGS_PACKAGE |
The namespace package the stubs and handles live under, beside the tools package. |
|
RECEIPTS |
Where a checkout keeps its receipts, one file per tool, gitignored. |
|
BIN |
The checkout's bin directory: the entry points of every tool in |
|
RECEIPT_SCHEMA |
A receipt's shape. Bumped when a reader must know. |
|
STUBS_RECEIPT |
The receipt naming the lock and the source the last stub write rendered from. |
WORKSPACE
module-attribute
¶
The contract table the supported hosts live under.
DEFAULT_HOSTS
module-attribute
¶
The hosts supported when [workspace] hosts is absent; empty for
every host key, which the store names and which is read only then.
VERDICT_PHASES
module-attribute
¶
The phases whose tools take no host allowance: the version is the verdict.
PINNED_TOOLS
module-attribute
¶
The tools no allowance reaches by name: the entry pins uv.
BASE_SITE
module-attribute
¶
The site of the base's own requirements, the ones every workspace has.
TYPINGS
module-attribute
¶
The directory under the root the stubs are written into, pyright's default.
TYPINGS_PACKAGE
module-attribute
¶
The namespace package the stubs and handles live under, beside the tools package.
RECEIPTS
module-attribute
¶
Where a checkout keeps its receipts, one file per tool, gitignored.
BIN
module-attribute
¶
The checkout's bin directory: the entry points of every tool in link mode.
RECEIPT_SCHEMA
module-attribute
¶
A receipt's shape. Bumped when a reader must know.
STUBS_RECEIPT
module-attribute
¶
The receipt naming the lock and the source the last stub write rendered from.
Under state/ rather than receipts/: that directory is the tool
receipts, which tool_receipts() reads as a set and refuses a file of
another shape in. Each kind of thing under .workshop/ keeps its own
directory, so no walk of one kind can reach another.
ToolReceipt
dataclass
¶
ToolReceipt(tool: str, version: str, host: str, kind: str, mode: str, deployment: str = '', tool_dir: str = '', paths: tuple[str, ...] = (), env: dict[str, str] = dict(), entry_points: tuple[str, ...] = (), source: str = 'store', answered: str = '', stamp: dict[str, str] = dict())
What this checkout installed of one tool, as its file records it.
fm sync writes one receipt per tool under the checkout's
.workshop/receipts/; livery.workshop.tool_receipts reads
them all.
Attributes:
| Name | Type | Description |
|---|---|---|
tool |
str
|
The tool's name. |
version |
str
|
The exact version installed, the lock's. |
host |
str
|
The host key it was installed for, this machine's. |
kind |
str
|
The installer kind. |
mode |
str
|
How it reached PATH, one of livery.toolroom.store.MODES. |
deployment |
str
|
The digest of the deployment installed; empty for a delegated kind, whose installer resolves the host. |
tool_dir |
str
|
Where the tool is, under the machine's store home (livery.workshop.store_home). |
paths |
tuple[str, ...]
|
The absolute directories the tool puts on PATH in |
env |
dict[str, str]
|
The variables the tool sets, resolved against its directory. |
entry_points |
tuple[str, ...]
|
The executables' names the tool puts on PATH:
linked into the checkout's bin directory in |
source |
str
|
|
answered |
str
|
The version the host's copy printed when it served; empty for a store install. |
stamp |
dict[str, str]
|
The host copy's identity when it served: its |
Methods:
| Name | Description |
|---|---|
to_json |
The receipt as a JSON object. |
load |
The receipt at path. |
to_json ¶
The receipt as a JSON object.
Source code in packages/workshop/src/livery/workshop/_tools.py
load
classmethod
¶
load(path: Path) -> ToolReceipt
The receipt at path.
Raises:
| Type | Description |
|---|---|
ValueError
|
for a file that is not a receipt of this schema, naming the file. |
Source code in packages/workshop/src/livery/workshop/_tools.py
Materialised
dataclass
¶
Materialised(receipt: ToolReceipt | None, installed: bool, failure: str = '', note: str = '')
What one materialisation did to one tool.
Attributes:
| Name | Type | Description |
|---|---|---|
receipt |
ToolReceipt | None
|
The receipt written, or |
installed |
bool
|
Whether the store installed it on this call. |
failure |
str
|
Why the tool could not be supplied; empty when it was. |
note |
str
|
What the sync should say beyond the receipt: why a host copy was passed over for the store's version; empty otherwise. |
Stubbed
dataclass
¶
Stubbed(written: tuple[str, ...], kept: tuple[str, ...], skipped: dict[str, str], removed: tuple[str, ...])
What write_stubs did.
Attributes:
| Name | Type | Description |
|---|---|---|
written |
tuple[str, ...]
|
The tools whose stub changed on disk, or was new. |
kept |
tuple[str, ...]
|
The tools whose stub was already what the catalogue holds. |
skipped |
dict[str, str]
|
Per tool the catalogue lists and no stub was written for, why. |
removed |
tuple[str, ...]
|
Stubs of tools the catalogue no longer lists. |
tools_table ¶
The [toolroom] table of the contract at path, judged; empty when absent.
Source code in packages/workshop/src/livery/workshop/_tools.py
base_requirements
cached
¶
base_requirements() -> tuple[Requirement, ...]
The tools the base requires in every workspace, at the site BASE_SITE.
Read from the [toolroom] requires of the base's contract file,
which spells them as an extension's extension.toml does: uv,
which makes the venv every step runs in, so a workspace with no
package requires it too.
Raises:
| Type | Description |
|---|---|
Failed
|
when an entry is not a requirement, naming it. |
Source code in packages/workshop/src/livery/workshop/_tools.py
requirements ¶
requirements(root: Path) -> tuple[Requirement, ...]
Every requirement the six sites declare, in site order.
The base's come first, at the site BASE_SITE: a workspace
requires uv with or without a package, since its own tasks.py
and tests run in the venv uv makes. The steps that judge a present
package bring the tools they run, each requirement naming
step <name> as its site, and so do the steps that judge the
root's own files, which are judged as a package holding the root's
set is.
An extension's site is extension <name>, read from its
extension.toml's [toolroom] requires and from each of its
[for.<target>] tables that applies now: cmake's build tools
are required while a package's set holds cmake, and a measurer's
tool while the workspace lists what it measures for. An extension
that neither the workspace lists nor a package's set holds
declares nothing here, since listing is the only activation
channel. A plugin the project mounts through its direct
dependencies is plugin <name>, read from its entry module
(livery.workshop._tools.plugin_tools).
Source code in packages/workshop/src/livery/workshop/_tools.py
plugin_tools ¶
The tools each plugin the project mounts declares, by its entry point name.
The plugins are the footman.builtin names the project's direct
dependencies offer, as footman's project rung mounts them. A plugin
declares the tools its verbs need in a data module that its
workshop.tools entry point names, under the plugin's own name:
"livery.forge" = "livery.forge._dev_tools:TOOLS", a tuple of
requirement strings, ("docker?",) for one it can do without.
Loading it imports that module alone, never the plugin's tasks.
Raises:
| Type | Description |
|---|---|
Failed
|
when a declaration is not a tuple or list of strings, naming the plugin. |
Source code in packages/workshop/src/livery/workshop/_tools.py
host_allowed ¶
The tools whose copy on the machine may serve: the root contract's.
The root contract's [toolroom] host-allowed, each name once,
sorted. A name no site requires yet is kept and named by the lock
as an allowance ahead of its requirement: a workspace may allow
cmake before its first C++ package arrives, and the lock's line
is where a misspelling shows. A tool a step reads its verdict from
refuses, naming the steps that read it: a linter that varies by
machine makes the gate disagree with CI. uv refuses by name,
since the entry pins it. A tool an extension that writes release
notes requires refuses, naming the extension: a release's entries
must not depend on the machine. A download whose executable is
not named like the tool, or that has none, refuses too: the
allowance finds the tool on PATH by its name.
Source code in packages/workshop/src/livery/workshop/_tools.py
unrequired_allowances ¶
The host-allowed names no site requires yet, sorted: allowances ahead of need.
Source code in packages/workshop/src/livery/workshop/_tools.py
tool_names ¶
The tools the sites require, each once, in the order first declared.
With host, the tools required there: a requirement scoped to other
hosts alone (dotnet_coverage@windows) requires nothing on it.
Source code in packages/workshop/src/livery/workshop/_tools.py
supported_hosts ¶
The hosts the workspace supports and locks for, in host-key order.
[workspace] hosts names them in the requirement scope tokens:
a platform (macos), a host key (linux-arm), and either with !
to remove it, a list of removals alone starting from every host.
Absent, every host key is supported.
Raises a refusal for a token that is neither a platform nor a host key, and for a list that is empty or leaves no host.
Source code in packages/workshop/src/livery/workshop/_tools.py
index_source ¶
Where the catalogue is read from, as [toolroom] index names it.
A URL is read as the published index; a path, relative to the root, is a directory holding an index or the records that build one.
Source code in packages/workshop/src/livery/workshop/_tools.py
has_index ¶
Whether the root contract names a catalogue source at all.
receipt_gap ¶
receipt_gap(tool: str, receipt: ToolReceipt, bin_dir: Path) -> str
Why what receipt claims does not hold here; empty when it does.
A receipt is the store's own record of what it installed for this checkout, so it is the thing to check: looking for an executable by a tool's name instead answers a different question, and answers it wrongly for a tool that is not a program.
What a receipt claims depends on how the tool was supplied. One
that puts directories on PATH claims they exist and that each entry
point runs from one of them, the venv's own bin, or PATH, since a
name is not always a binary's (git_cliff installs
git-cliff). One that carries environment values claims each
value that is a path is there: the cmake-conan provider is a file
CMake reads, and no program by that name exists anywhere. One that
claims nothing was verified on the host rather than installed, so
the host must still answer for it.
Returns:
| Type | Description |
|---|---|
str
|
The first claim that does not hold, as a line to print after |
str
|
the tool's name, or empty when every claim does. |
Source code in packages/workshop/src/livery/workshop/_tools.py
store_cannot_supply ¶
Why the store supplies nothing here; empty when it can.
The sites require tools whatever a contract says, because the base requires uv: a workspace with no package still runs in the venv uv makes. Nothing is supplied until a lock names versions, and nothing can be locked until the contract names a catalogue to resolve against, so the two are one question with one answer a reader can act on.
Empty when a lock is present, and empty for a workspace that requires no tool at all.
Source code in packages/workshop/src/livery/workshop/_tools.py
catalogue ¶
The catalogue the repository resolves against, from [toolroom] index.
A directory of records is read as the authoring site reads it; an index, by URL or directory, through the machine's store, which keeps what it fetched so a second read is offline.
Source code in packages/workshop/src/livery/workshop/_tools.py
forget_catalogues ¶
store_home ¶
store_home() -> Home
The tool store's home on this machine, where every checkout's tools are.
The toolroom directory in the runner's data directory, one per
machine and shared by every checkout on it, as a
livery.toolroom.store.Home.
Source code in packages/workshop/src/livery/workshop/_tools.py
lock_path ¶
current_lock ¶
The lock as committed, or None when the repository has none yet.
Source code in packages/workshop/src/livery/workshop/_tools.py
lock_is_current ¶
Whether toolroom.lock is what the sites resolve to now; and what moved.
The question --locked and --check ask, and nothing is written to
answer it. An entry that still satisfies every floor stands, so a
newer version published since the lock was written moves nothing:
that is what an upgrade is for. What moves the answer is a
requirement the lock does not hold, or holds at a version that no
longer satisfies.
The graphs are not compared: a delegated tool's graph is resolved when its version enters the lock and written beside it, so a fresh resolution never carries one, and reading its absence as a move would move every delegated entry on every check.
Returns:
| Name | Type | Description |
|---|---|---|
bool
|
Whether the lock on disk is current, and why not when it is |
|
not |
str
|
no lock at all, a requirement nothing satisfies, or the |
tuple[bool, str]
|
tools whose entries would move. |
Source code in packages/workshop/src/livery/workshop/_tools.py
write_lock ¶
write_lock(root: Path, *, upgrade: tuple[str, ...] = (), relock: tuple[str, ...] = (), offline: bool = False) -> Lock
Resolve the sites' requirements and write the lock; the lock written.
An entry the lock already holds stands unless it is named in upgrade or no longer satisfies; a refusal names the tool, each floor with its site, and the host at fault. A delegated tool whose version entered the lock has its graph resolved with it, and one named in relock has its graph resolved again though its version stands, which is what an install the graph could not satisfy asks for.
Source code in packages/workshop/src/livery/workshop/_tools.py
unreached_scopes ¶
One line per scoped requirement no locked host matches, and so locks nothing.
Source code in packages/workshop/src/livery/workshop/_tools.py
resolve_graph ¶
resolve_graph(root: Path, name: str, package: str, version: str, *, kind: str, runtime: str) -> tuple[Graph | None, str]
Resolve package at version and write its graph; the graph or why not.
A pypi graph is uv's universal hashed requirements, resolved
against the workspace's Python floor, so one file covers every
interpreter the workspace supports. An npm graph is the
runtime's own lockfile, resolved without installing anything.
Neither runs unless what resolves it is here: a checkout that has
not materialised its tools yet locks the version and says the
graph waits.
Source code in packages/workshop/src/livery/workshop/_tools.py
exe ¶
graphs_dir ¶
with_graphs ¶
with_graphs(root: Path, lock: Lock, listing: Catalogue, *, kept: Lock | None = None, relock: tuple[str, ...] = ()) -> tuple[Lock, list[str]]
lock with a graph per delegated tool, and what to say about it.
A pypi tool's graph is uv's hashed requirements, a npm tool's
is its runtime's lockfile, each written under GRAPHS beside the
lock and named there by its digest; a dotnet tool has none, since
its package carries its dependencies and the version pins the
whole. A graph that cannot be
resolved now, the runtime it needs being absent on a checkout
that has not materialised yet, leaves the tool as it was: it
installs the way it did and says so, and the next lock writes it.
A tool named in relock is resolved again though its version stands. Nothing here re-resolves on its own: a resolve is a fresh answer from an index, so it moves the lock, and a lock moves when a person says so, never as a side effect of installing.
Source code in packages/workshop/src/livery/workshop/_tools.py
runtime_of ¶
The runtime a tool runs on: an npm tool's record's, node unless it says bun.
A dotnet tool runs on dotnet, the SDK. Empty for every other
kind, which runs on nothing the lock supplies.
Source code in packages/workshop/src/livery/workshop/_tools.py
with_runtimes ¶
with_runtimes(found: tuple[Requirement, ...], listing: Catalogue) -> tuple[Requirement, ...]
found, plus each runtime a tool among them runs on and nothing names.
An npm or dotnet tool is installed through its runtime and
runs on it, so the runtime is the tool's dependency and the lock
holds it as such, on the hosts the tool is required on: the site
named is the tool that needs it. A runtime some site requires on
every host needs no more; otherwise one requirement per distinct
scope is added, and the lock unions them. A requirement the
catalogue does not list is left for the resolver to refuse by
name.
Source code in packages/workshop/src/livery/workshop/_tools.py
declare ¶
Add text to the project's [toolroom] requires; whether the contract changed.
A requirement already declared at the project site, in the same
spelling, is left as it is. The contract is edited in place: the
[toolroom] table gains the entry, or is added at the end with it.
Source code in packages/workshop/src/livery/workshop/_tools.py
receipts_dir ¶
bin_dir ¶
tool_receipts ¶
tool_receipts(root: Path) -> dict[str, ToolReceipt]
What the checkout at root installed of each tool, by the tool's name.
The receipts the last sync wrote, each a livery.workshop.ToolReceipt: a receipt names the version the lock pins and where the tool is on this machine. Empty for a checkout no sync has supplied.
Raises:
| Type | Description |
|---|---|
ValueError
|
for a file under the receipts directory that is not a receipt, naming it. |
Source code in packages/workshop/src/livery/workshop/_tools.py
mode_of ¶
mode_of(root: Path, name: str, kind: str, declared: str = '', *, paths: tuple[str, ...] = ()) -> str
The mode name materialises in: the project's say, the record's, the kind's.
paths are the deployment's, which decide a download's default.
Raises a refusal naming the override when it is not one of MODES.
Source code in packages/workshop/src/livery/workshop/_tools.py
sources ¶
The tiers consulted before an origin, [toolroom] sources: folders or URLs.
Source code in packages/workshop/src/livery/workshop/_tools.py
site_floors ¶
The highest floor the sites declare per tool, with the site that asked.
A tool no site floors is absent. The lock already honours these floors when it chooses a version; the check of a system tool on a machine honours them here, since the machine's own copy is never the locked version.
Source code in packages/workshop/src/livery/workshop/_tools.py
materialise ¶
materialise(root: Path, names: tuple[str, ...] = (), *, offline: bool = False, strict: bool = True) -> tuple[Materialised, ...]
Supply every locked tool, or names alone, and write their receipts.
The bundle is what the sites require: every tool the lock holds
for this host; one locked for other hosts alone is skipped, and
named it refuses. A downloaded kind is supplied from the
catalogue's deployment for
this host through the store's sources and the origin; a delegated
kind through its installer. A system tool is the machine's own,
held to the highest of the record's floor and the sites' floors;
the refusal names the site whose floor it is under. A tool the
lock marks allow-host is looked for on PATH first: a copy that
satisfies the floor serves, its receipt saying host and the
version that answered, and the store installs nothing for it; a
copy that is absent or below the floor is passed over with a
note, and the locked version is supplied as for any other tool. A
host receipt whose file is unchanged since it was written is
reused without a probe. Tools in
link mode are linked into the checkout's bin directory together,
so a name two tools offer goes to the first. A receipt is written
per tool supplied, and on a materialise of the whole bundle the
receipt of a tool the lock no longer holds is removed, so its
paths leave the environment with it.
Raises a refusal naming the tool when the lock does not hold it.
A tool the store cannot supply refuses too, naming the reason,
unless strict is off: then it is reported in its outcome and the
others are supplied, which is what sync wants, since one tool's
origin being unreachable must not stop the environment from
entering. A tool the lock marks optional is reported and never
refused, strict or not: the verbs that need it name its absence
when they run.
Source code in packages/workshop/src/livery/workshop/_tools.py
1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 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 | |
typings_dir ¶
stubs_dir ¶
The stubs package under the typings directory's livery.toolroom.
stubs_present ¶
write_stubs ¶
Write the stubs of the locked tools into the typings directory.
One stub per tool toolroom.lock holds, rendered by the store from the
locked version's own surface, from the records or from the index:
a tool the workspace does not deploy gets no stub, and its handle
types as a bare Tool. The handles module beside the stubs
declares the handles, one import and one name: Class[Result] per
stub written, and the installed tools package's index imports every
name from it. The handles cannot live in the stubs package's own
index: a package's index binds its submodules, and uv would name
uv.pyi rather than the handle. Nothing is written inside the
tools package's own directory, and a tree left there is removed:
it shadows the package for a checker run on explicit paths. Without
a lock nothing is written.
A receipt under .workshop/state/ names the lock and the source
the last write rendered from, a records directory by its stat
fingerprint and an index by its pointer. When both stand and every file it
wrote is there, nothing is read and nothing is written, which is
the steady state of every sync; otherwise a stub already on disk
as the source renders it is kept, so a checker's cache stands.
Source code in packages/workshop/src/livery/workshop/_tools.py
1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 | |
source_mark ¶
What the catalogue source is right now, in one digest, without reading it whole.
A directory of records is its stat fingerprint; an index, by directory or URL, is the digest of its pointer document.
Source code in packages/workshop/src/livery/workshop/_tools.py
handles_path ¶
The handles.pyi module beside the stubs, declaring the typed handles.
handles_index ¶
The handles module declaring the handles of names, in order.
The installed tools package's own index imports every name from
this module, so the handle uv types as Uv[Result] exactly
when stubs/uv.pyi is beside it.
Source code in packages/workshop/src/livery/workshop/_tools.py
stub_lines ¶
Write the stubs and say what happened, as sync and the lock verbs print it.
A refusal is raised when strict; otherwise it is the one line returned, naming the reason, since a lock written or a bundle materialised stands whether or not the stubs could follow.
Source code in packages/workshop/src/livery/workshop/_tools.py
emission ¶
What the receipts add to an entered shell: PATH entries and variables.
The checkout's bin directory first when any receipt links into it,
then each path receipt's directories in tool order, then the
variables, a later receipt's value winning.
Source code in packages/workshop/src/livery/workshop/_tools.py
drift ¶
Per tool the sites require, what fm env.check says of its receipt.
An empty string is a tool whose receipt matches the lock; anything else names the problem: no receipt, a receipt at another version than the lock, or a deployment the lock has moved under it.
Source code in packages/workshop/src/livery/workshop/_tools.py
undeployed ¶
Refuse the task: name is a tool of the store and is not on PATH.
Call it where a step spawns a tool of the store and the spawn
raises OSError, or where shutil.which finds nothing for a
tool the step spawns by its path. A toolroom handle spawns its tool
by name from PATH, and the store's tools are on PATH only
after the machine has deployed them and the shell has entered the
environment. A traceback from the spawn names nothing a person can
act on. This refusal names the tool and the next action: run
fm sync, then the env.emit line it prints, then run the task
again.
It never returns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The tool's name, as its handle spawns it. |
required |
Raises:
| Type | Description |
|---|---|
Failed
|
always, naming name and the sync that deploys it. |