livery.toolroom.tools._host¶
livery.toolroom.tools._host ¶
The seam between the bridge and whatever executes its calls.
toolroom is vocabulary-complete on its own, and the seam speaks stdlib:
the bridge hands this module a list[str] plus run policy, and gets
back an int-with-attributes. When footman is present in the process,
every call routes through footman's run() — receipts, capture,
dry-run, recording(), lanes — without footman ever importing (or even
knowing about) toolroom. When it is not, a plain subprocess executor
answers with toolroom's own Result.
Detection keys on orchestration, not mere presence: a call routes
hosted only when a footman context is actually live — a task body, a
parallel() worker, a recording() block — because that is when
receipts, dry-run, and recording must be impossible to bypass. A bare
call in a process that merely imported footman (a pytest run
auto-loading footman's plugin, an app embedding both) takes the
standalone executor and standalone semantics, deterministically: which
exception a failure raises must never depend on what some other module
imported. An installed-but-never-imported footman does not make this a
footman process either, and importing it here would change the process
just to answer a question about it.
The hosted branch's lazy imports reach the same names the in-tree bridge imports today. When footman grows a named executor contract, this module is the only place that changes.
Classes:
| Name | Description |
|---|---|
Argv |
A command line built but not run — |
Result |
The outcome of one standalone tool call — and the value it returns. |
ToolError |
A standalone tool call exited non-zero (and |
Functions:
| Name | Description |
|---|---|
hosted |
Whether footman is orchestrating this call. |
container_error |
The taught refusal for a bare container in an argv slot. |
color_on |
The ambient colour answer for this process — the ladder's bottom rung. |
colour_wanted |
A colour mode resolved to an answer — the ladder, one rung at a time. |
color_env |
The colour variables to set on a child to force colour on (or off). |
child_env |
The child's environment with this call's colour answer written in. |
note |
A quiet aside about how a call ran (demotion notes). |
run |
The one door every bridge call leaves through. |
probe |
A truthful value read outside any host — |
Argv ¶
A command line built but not run — toolroom.git.push.argv(force=True).
An ordinary list[str] everywhere in Python: it indexes, slices,
iterates, compares and prints exactly like the list it is, and any
runner spawns it as-is. Always the raw tokens — the one shape of a
command with no shell in it. Passing the tokens on is plain Python:
a wrapper takes them splatted (uv.run("--", *cmd)), and stdlib
helpers take the list directly (shlex.join(cmd)).
The moment the line is about to cross into a shell, name that shell:
.posix()— one string,shlex-quoted forsh/bash/zsh..windows()— one string, quoted the wayCreateProcessparses.
Naming it is the caller's job because toolroom cannot know it: the same handle can target different hosts across calls, the OS does not determine the shell, and the payload may reach no shell at all. The quoting is the destination's, never this machine's.
footman keeps a twin of this class for its receipts
(Result.to_argv()); both are ordinary list[str], so they compare
equal token-for-token and either flows anywhere the other does.
Methods:
| Name | Description |
|---|---|
posix |
This command as one string, quoted for a POSIX shell. |
windows |
This command as one string, quoted the way |
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
Result ¶
Bases: int
The outcome of one standalone tool call — and the value it returns.
A Result is the exit code: it subclasses int, so
code = git.push(), if git.push(), and == 0 all read naturally.
It also carries the captured output, split by stream, and the tokens
that ran. Under a footman host the bridge returns footman's own
Result instead — a superset of this surface (receipts, --json,
replay-on-failure); the two are twins by design, never the same
class, and code written against this surface runs under both.
Methods:
| Name | Description |
|---|---|
__new__ |
|
to_argv |
The executed command as an |
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
ok |
bool
|
True when the tool exited zero. |
code |
int
|
The exit code as a plain int — the value this Result is. |
stdout |
str
|
The captured standard output (empty when |
stderr |
str
|
The captured standard error (empty when |
command |
str
|
The command that ran, as one readable line. |
command
property
¶
command: str
The command that ran, as one readable line.
A token that redacts itself — footman's Secret, duck-typed on
reveal so nothing here imports it — reads back as ***: this
line exists to be shown, and a secret leaves through .to_argv()
or the caller's own unwrap, never through display.
__new__ ¶
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
ToolError ¶
ToolError(result: Result)
Bases: RuntimeError
A standalone tool call exited non-zero (and nofail was not set).
Carries the Result so the handler keeps the streams and the
command. Under a footman host failures take footman's lane instead
(the task fails, output replays); this error exists only where there
is no host to do that.
Attributes:
| Name | Type | Description |
|---|---|---|
result |
|
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
hosted ¶
hosted() -> bool
Whether footman is orchestrating this call.
True only with a live footman context — a task body, a parallel()
worker, a recording() block — where routing through run() is
what keeps receipts, dry-run, and recording honest. Presence alone
(footman merely imported somewhere in the process) is not
orchestration: a standalone-minded call keeps standalone semantics
however the process came to hold a footman.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
container_error ¶
The taught refusal for a bare container in an argv slot.
toolroom's own copy of the wording footman's run() door teaches —
shared wording, per the split ruling, never shared code — so the
lesson reads the same whichever door refuses. An Argv gets its own
text: it is the one container that plausibly lands here on purpose,
and the fix differs by what was meant.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
color_on ¶
color_on() -> bool
The ambient colour answer for this process — the ladder's bottom rung.
Read from the environment, hosted or not: NO_COLOR wins, any of the
force variables forces, and otherwise a terminal on stdout decides (a
dumb one is no terminal). Inside a footman run that reads the answer
the run published at its boundary; outside one, whatever the user
exported. One rule, no import, and nothing that varies with whether
footman happens to be in the process.
Ambient is the only tier the environment carries. A decision meant for
one call travels on the call — .opts(color=…) — because
os.environ is one per process while calls are not, and two threads
wanting different answers cannot both have one here.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
colour_wanted ¶
A colour mode resolved to an answer — the ladder, one rung at a time.
always/never are the answer; auto takes the ambient one. The
seam owns this because both lanes need it: the argv half must pick a
tool's on- or off-switch here whatever executes the call.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
color_env ¶
The colour variables to set on a child to force colour on (or off).
A spawned tool's stdout is a pipe whenever toolroom captures it, so
isatty() is false and a well-behaved tool goes monochrome — exactly
when the bytes are headed for a terminal anyway. This is what those
variables are for, so forcing on sets the whole force set and forcing
off sets NO_COLOR; the direction is completed by removing the
other side's variables (see child_env), never by setting "0".
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
child_env ¶
The child's environment with this call's colour answer written in.
env follows run(env=…): None inherits, a mapping replaces. A
decided colour merges on top of whichever of those the call has —
an instruction aimed at this child outranks the environment it was
handed, exactly as run(color=…) treats it hosted. auto leaves an
explicit environment alone, because ambient is what that environment
already carries; inheriting, it writes the ambient answer in, since
standalone has no run boundary to have published it.
Every colour variable is cleared before this direction's are set, so
off leaves no inherited FORCE_COLOR for a presence-checking tool to
honour and on leaves no stray NO_COLOR.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
note ¶
note(text: str) -> None
A quiet aside about how a call ran (demotion notes).
Hosted, it reaches the real stderr when the run is --verbose;
standalone there is no verbose lane, so the note is dropped — the
demotions it describes are behaviour-preserving either way.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
run ¶
run(target: list[str] | Any, *, parts: tuple[tuple[str, str], ...], exact: tuple[str, ...], handed: tuple[tuple[Any, ...], dict[str, Any]] | None = None, nofail: bool = False, capture: bool = True, input: str | bytes | None = None, env: dict[str, str] | None = None, title: str | None = None, pre_record: Any = None, recorded: bool = True, timeout: float | None = None, cwd: str | Path | None = None, rel: str | Path | None = None, color: str = 'auto') -> Any
The one door every bridge call leaves through.
target is the argv to spawn — or, hosted-only, the in-process
callable the bridge prepared. parts/exact are the two spellings
of the same call (role-tagged for painting, literal for --verbose);
standalone execution has no receipt to paint, so it reads neither.
handed is the call as the caller wrote it — positionals and
keywords pre-render, a False flag included where the argv omits it.
Execution ignores it, like probe()'s shown: it exists for the
testing seam, which records what the code under test decided to
pass, not only what would have run.
color is the call's colour mode, unresolved — auto means "follow
whoever owns the ambient", and hosted that is the run, so the mode
travels rather than an answer computed from the environment. The
argv half is already decided by the time a call reaches here; this is
the environment half, which hosted belongs to footman: run(color=)
applies it to that one child, merging over env= and reaching the
in-process lane too.
Source code in packages/toolroom/src/livery/toolroom/tools/_host.py
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 | |
probe ¶
probe(argv: list[str], *, shown: tuple[str, ...], env: dict[str, str] | None, timeout: float | None) -> Result
A truthful value read outside any host — installed_version's spawn.
Deliberately not run(): a version read is not a step of anyone's
story, so it must answer the same under --dry-run and recording()
as it does bare — no receipt, no colour ladder, no footman at all.
It lives at the seam so the testing double (toolroom.testing) has
one door to intercept; shown is the name-led spelling of the same
call, which that double matches canned answers against — execution
ignores it, and never raises for a non-zero exit: the caller reads
the code.