API reference¶
The whole public surface. Anything underscore-prefixed is implementation — it moves without notice.
The handles¶
livery.toolroom.tools.Tool ¶
Tool(name: str, *base: str, in_process: bool = False, path: str = '', entry: str = '', single_dash: bool = False, version_argv: tuple[str, ...] = ('--version',), policy: dict[str, Any] | None = None)
One command-line tool; see the module docstring for the grammar.
in_process (footman run-control set via .opts(), like nofail) runs a
Python tool inside footman's process instead of spawning: the tool's own
[console_scripts] entry point is resolved and invoked — the same
no-transcription contract, minus the interpreter spawn. Beyond speed
this matters for correctness: on macOS, SIP strips DYLD_* from child
processes, so a tool that needs Homebrew's native libraries (mkdocs
with cairo, say) can only see them in-process, where an env var set
before the import sticks. Tools constructed with in_process=True
default to it and fall back to a subprocess when no entry point is
installed; .opts(in_process=True) is a demand and errors if the entry
can't be found. Parallelism survives: entries that accept an
argument list (click commands, main(argv=None) — detected from the
signature) are called directly and capture through the per-task stdout
router; even a legacy zero-arg main() parallelises — the argv router
serves each call its own view of sys.argv.
The in-process lane is a host feature — those routers are footman's.
Standalone, a tool constructed with in_process=True simply spawns
(same command, same semantics), and .opts(in_process=True) — a
demand — is a taught refusal.
Methods:
| Name | Description |
|---|---|
__getattr__ |
|
opts |
Set footman run-control policy for the call — the same |
at |
Rebind this handle to an executable — the identity channel, |
flags |
Bind a tool's own global options before the next subcommand. |
__call__ |
|
installed_version |
The version of the binary this tool runs, as a comparable int tuple. |
Attributes:
| Name | Type | Description |
|---|---|---|
__class_getitem__ |
|
|
argv |
Tool[Argv]
|
Build this call's command line instead of running it. |
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
__class_getitem__
class-attribute
instance-attribute
¶
__class_getitem__ = classmethod(_types.GenericAlias)
argv
property
¶
Build this call's command line instead of running it.
Insert .argv right before the parentheses — the call is otherwise
spelled exactly as it would be to run it, same verb, same flags,
same completion — and it hands back an Argv of raw tokens rather
than executing:
mkdocs.gh_deploy.argv(force=True)
# -> Argv(['mkdocs', 'gh-deploy', '--force'])
The tokens serialise at the point they cross into a shell —
cmd.posix() / cmd.windows() — or splat on as tokens (*cmd):
inner = docker.compose.up.argv(detach=True)
ssh("app@host", inner.posix())
Like .opts(), it may sit anywhere earlier in the chain
(docker.argv.compose.up(…) builds too); before the parentheses is
where it reads best and how the docs spell it. The line it builds is
colour-free: the forced-colour switch a few tools need is injected
when spawning, so what runs may carry one more flag than this
returns.
__getattr__ ¶
opts ¶
Set footman run-control policy for the call — the same .opts() a task
has, mirroring its policy-vs-work split. A closed vocabulary
(nofail, in_process, capture, title, step) that rides beside
the call, never becoming a tool flag:
git.opts(nofail=True).push() # tolerate a non-zero exit
pytest.opts(capture=False)("-s") # stream this run live
git.opts(recorded=False).rev_parse("HEAD") # a value read, not an event
recorded=False is the one that changes what the run sees rather than
how the tool is invoked: the call runs in the task's directory and
environment as always, but reports nothing — no receipt, no row in
--json, no recording() entry — and hands back its Result. Reach
for it when the call is how the task knows something rather than
something the task did.
Because it is a fixed set, capture here is unambiguously footman's — a
tool's own --capture (pytest's) still goes in the call. The overridden
options ride the chain and win at call time. For a tool's own global
options that must precede a verb, use .flags().
color="always"|"never" decides this call's colour outright, and
"auto" (the default) takes the ambient answer — the run's inside a
footman run, the user's environment outside one. An explicit choice
beats NO_COLOR, which is what makes a colour assertion hold on CI
that exports it:
git.opts(color="always").diff() # colour, whatever the ambient
The decision travels on the call rather than through the environment
because os.environ is one per process and calls are not — two
threads wanting different answers can both have one this way. It
drives whichever half of the forcing each tool needs: the variables
for those that read them, their own switch for those that don't. For
a tool's own colour flag, spell it in the call
(ruff.check(color="always")) and toolroom keeps out of the way.
env= is the child's environment exactly as run(env=…) means it —
what you pass is what the child gets — and like the rest of the set it
rides the chain and replays. input= feeds the child's standard input,
and unlike the rest it is consumed: stdin is consumable, so the
payload is delivered exactly once however the handle is chained or
shared, and a second call is a taught refusal rather than a
silently-unfed child hanging on a stdin that never comes. Re-opt with
a fresh payload per call:
uv.pip.install.opts(input=requirement)("-r", "-")
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
at ¶
Rebind this handle to an executable — the identity channel,
beside .opts() (policy) and .flags() (the tool's own argv).
Everything else rides along: verbs, bound flags, policy — including
a pending input= payload, whose cell is shared, not copied. What
changes is what runs: tools.python.at(venv_python) is that
venv's interpreter carrying python's whole typed surface, and the
shown command line keeps the tool's own name.
The in-process lane runs this interpreter, which is exactly what
an .at() handle says not to do — so the handle always spawns, and
an explicit in_process=True on one is a taught refusal.
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
flags ¶
Bind a tool's own global options before the next subcommand.
Some flags belong to the tool, not the verb, and must precede it:
docker --host tcp://x ps works, docker ps --host tcp://x does
not. flags places them at the current point in the chain, so they
land ahead of whatever verb follows and ahead of its arguments:
tools.docker.flags(host="tcp://x").ps(all=True)
# -> docker --host=tcp://x ps --all
The flags are translated by the same rules as any call, and the
returned tool keeps chaining, so .flags(...) composes mid-stream.
(footman run-control — nofail, capture, … — goes in .opts().)
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
__call__ ¶
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 | |
installed_version ¶
The version of the binary this tool runs, as a comparable int tuple.
Asks the executable itself — <tool> --version, or whatever spelling
the tool was declared with (cmd /c ver) — and reads the answer with
the same parser the stub extractor uses, so the two can never disagree
about a version string's grammar. Runs outside the task context, so
--dry-run and recording() can't lie to it, and caches per process.
It answers "what will this task actually invoke", which is not the
version a stub header records. A stub says what extraction read, on
whatever machine synced it, from whatever binary it resolved — the
two differ whenever PATH and the extractor disagree (a Homebrew keg
against /usr/bin/git, say). This one is the end-user question; the
stub's is maintainer bookkeeping.
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
The vocabulary¶
livery.toolroom.tools.Argv ¶
livery.toolroom.tools.Result ¶
Bases: int
One standalone call's outcome: the exit code, plus streams and tokens.
Hosted calls answer with footman's richer twin; both satisfy this surface, which is the one the stubs promise.
Methods:
| Name | Description |
|---|---|
__new__ |
|
to_argv |
|
Attributes:
| Name | Type | Description |
|---|---|---|
ok |
bool
|
|
code |
int
|
|
stdout |
str
|
|
stderr |
str
|
|
command |
str
|
|
__new__ ¶
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
Flag control¶
Versions¶
livery.toolroom.tools.read_version ¶
The version string inside a tool's --version output, or "".
The string is preserved exactly, build tail and all (0.6.0-wk.5), for
anything that records which build was read. Use version_tuple to
compare.
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
livery.toolroom.tools.version_tuple ¶
A version string reduced to comparable integers — the CLI generation.
Only the leading numeric run counts, and the first component carrying a
build tag ends the read: 0.6.0-wk.5 and 1.13.0.git.kitware.jobserver-1
both compare as their base, (0, 6, 0) and (1, 13, 0).
That is the honest answer to the question this is asked — is the CLI new
enough — because a build tail says nothing about which flags exist.
Scraping its digits would answer it backwards: 0.6.0-wk.5 is a fork
build of 0.6.0, which every version grammar sorts at or before it,
while (0, 6, 0, 5) sorts after.
So two builds of one base compare equal, and every caller has to say
what it does with that rather than read equality as an answer. Ordering a
release chain breaks the tie on publication date, which separates a wk
series correctly without this having to know what wk means. The
snapshot guard cannot — an incoming reading is dated today whatever it
holds — so it declines to move rather than guess.
An unreadable version yields (), which compares lower than everything —
"can't tell" must never read as "newer".
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
Testing¶
How these fit together is Testing's story; this is the reference.
livery.toolroom.tools.testing.answers ¶
answers(table: Mapping[Any, Answer] | None = None, *, hosted: bool = False) -> Generator[list[Call]]
Answer every bridge call in the block from table, spawning nothing.
Yields the live list of Call records — assert on it after (or
during) the block. With hosted=True the block simulates the
hosted lane: _host.hosted answers True (so the bridge takes its
hosted paths — an in-process tool's callable is recorded, never
invoked), successes come back as footman's Result, and failures
raise footman's RunFailed — what code written for a footman task
returns and catches. The default speaks toolroom's own vocabulary:
Result back, ToolError raised.
The per-process installed_version cache is cleared for the block
and restored after it, so a canned version can neither be pre-empted
by a real read earlier in the process nor leak into later tests.
Not thread-safe: the seam is swapped module-wide for the duration.
A canned prefix that matched nothing by a clean block exit warns
(UnservedAnswers): an answer canned but never served is almost
always a mis-keyed prefix, and without the warning the test passes
vacuously. A block that exits on an exception is not warned — it
already failed loudly.
Source code in packages/toolroom/src/livery/toolroom/tools/testing.py
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 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 | |
livery.toolroom.tools.testing.Call ¶
Call(*, argv: Argv, raw: Argv, command: str, args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, env: dict[str, str] | None, opts: dict[str, Any], probe: bool = False)
One intercepted call: what would have run, and what was handed.
argv is the name-led spelling — raw tokens, assert-friendly.
raw is what would actually have spawned: resolved interpreter
path, forced colour switch and all (the same pairing footman's
steps keep as .command/.raw). command is the shown line,
values quoted and secrets redacted.
args and kwargs are the call as the caller wrote it,
pre-render: positionals verbatim (a Path stays a Path), and the
call keywords with False values included — the bridge omits a
False flag from the argv, the record must not, because "never
handed" and "handed, as False" are different facts and tests assert
on both. The rule of thumb: assert on kwargs for what the code
decided to pass, on argv for what would have run. .flags()
keywords are part of the handle, rendered into the verb path before
any call exists, so they show only in argv/raw; run policy
stays in opts.
env is the environment the call handed the seam (None
inherits); opts carries the rest of the run policy (nofail,
capture, input, cwd, timeout, …) exactly as it crossed.
probe marks a version read — a probe has no call of its own, so
its args/kwargs are () and {} by construction.
Methods:
| Name | Description |
|---|---|
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
argv |
Argv
|
|
raw |
Argv
|
|
command |
str
|
|
args |
tuple[Any, ...]
|
|
kwargs |
dict[str, Any]
|
|
env |
dict[str, str] | None
|
|
opts |
dict[str, Any]
|
|
probe |
bool
|
|
Source code in packages/toolroom/src/livery/toolroom/tools/testing.py
__slots__
class-attribute
instance-attribute
¶
livery.toolroom.tools.testing.UnservedAnswers ¶
Bases: Warning
A canned answer matched no call by the end of an answers() block.
An unmatched call is often incidental — the recorder default
exists for exactly that — but an unmatched table entry is a test
bug in the making: an answer was canned to steer the code under
test and never served, usually because the key was mis-spelt,
path-led where matching is name-led, or split into the wrong
tokens, and the test passes vacuously as if the entry did not
exist. A warning rather than an error so a deliberately shared
table (one fixture serving several tests, each exercising a subset)
can filter it; escalate it to a failure with -W error or a
filterwarnings mark where the table is per-test. A block that
exits on an exception is not warned — it already failed loudly.