livery.toolroom.tools¶
livery.toolroom.tools ¶
Typed handles for command-line tools — the tool room.
toolroom deliberately does not transcribe each tool's flags into
Python parameters. Transcription drifts: the wrapper pins the flag-set
its author copied, the tool moves on, and one day show_source=True
emits a flag the installed binary rejects. Instead, keyword arguments
translate mechanically — the installed tool's own CLI stays the
single source of truth, at whatever version it is:
fix=True→--fix(False/None→ omitted entirely)strict=off→--no-strict(disable a default-on flag;offis thetoolroom.offsentinel —no_strict=Trueis the same thing by name)output_format="github"→--output-format githubselect=["E", "F"]→--select E --select F(an empty list/tuple is omitted entirely, so a parameter's default passes straight through)x=1(single letter) →-x 1- a trailing underscore escapes Python keywords:
import_="x"→--import x
Attribute access chains subcommands (toolroom.docker.compose.up(detach=True)
→ docker compose up --detach), positional strings pass through verbatim,
and any executable works without being declared here:
toolroom.terraform("plan") just runs terraform plan.
toolroom stands alone: with nothing else installed, a call spawns the
tool with plain subprocess and answers in Result; a failure raises
ToolError unless nofail. When footman
is present in the process, the same call routes through footman's
run() instead and inherits everything a task run means — capture,
replay-on-failure, dry-run, recording(), --json receipts — without
either package depending on the other. _host is the seam.
tool.installed_version() returns the installed binary's version as an
int tuple (cached per process, resolved outside any host so dry-run and
recording can't lie to it) — for the rare case where code must branch
on the tool's actual CLI generation.
Modules:
| Name | Description |
|---|---|
testing |
Canned answers for bridge calls — toolroom's own test double. |
Classes:
| Name | Description |
|---|---|
Tool |
One command-line tool; see the module docstring for the grammar. |
ArgvTool |
What |
Functions:
| Name | Description |
|---|---|
read_version |
The version string inside a tool's |
version_tuple |
A version string reduced to comparable integers — the CLI generation. |
console_script |
The |
negations |
Each tool's keywords whose off spelling is not |
wrappers |
Each tool's verbs that wrap another command, by tool. |
colour_controls |
Each curated tool's probed colour control, by tool: how footman forces it. |
__getattr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__version__ |
str
|
|
off |
_Off
|
|
Flag |
TypeAlias
|
A boolean flag: |
Value |
TypeAlias
|
An option that takes a value. Scalars are |
ValuedFlag |
TypeAlias
|
An option whose value is optional — usable bare ( |
ruff |
|
|
ruff_format |
|
|
basedpyright |
|
|
uv |
|
|
git |
|
|
docker |
|
|
bun |
|
|
mkdocs |
|
|
zensical |
|
|
coverage |
|
|
cspell |
|
|
prek |
|
|
markdownlint |
|
|
claude |
|
|
gh |
|
|
ssh |
|
|
ssh_keygen |
|
|
ssh_keyscan |
|
|
eclint |
|
|
djlint |
|
|
mypy |
|
|
ty |
|
|
twine |
|
|
git_changelog |
|
|
git_cliff |
|
|
build |
|
|
cmake |
|
|
ninja |
|
|
pytest |
|
|
python |
|
|
bash |
|
|
zsh |
|
|
fish |
|
|
pwsh |
|
|
nu |
|
|
cmd |
|
Flag
module-attribute
¶
A boolean flag: True → --flag, off → the tool's own negation,
False/None → omitted (which is what lets a task parameter's default
flow straight through).
Value
module-attribute
¶
Value: TypeAlias = str | int | float | _os.PathLike[str] | Sequence[str | int | float | _os.PathLike[str]] | _Off | None
An option that takes a value. Scalars are str()-ed — a Path passes
straight through — and a sequence repeats the flag once per item.
ValuedFlag
module-attribute
¶
An option whose value is optional — usable bare (gpg_sign=True, sign
with the default key) or with a value (gpg_sign="KEY"). Both spell a
valid command; the tool prints its placeholder attached to the flag,
--gpg-sign[=<key-id>], which is how the extractor tells the two apart.
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
ArgvTool ¶
ArgvTool(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)
Bases: Tool
What .argv hands back: the same handle, whose call builds.
A Tool in every other respect — verbs chain, .opts()/.flags()
still apply, and _sub carries the class down the chain so a verb
reached through .argv keeps building rather than quietly reverting to
a running handle. It is a real class rather than a flag on Tool so
the typing stub can say what a built call returns without pretending a
Tool sometimes returns one thing and sometimes another.
Methods:
| Name | Description |
|---|---|
__call__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
__call__ ¶
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
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
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
console_script ¶
The [console_scripts] entry point named name, unloaded, or None.
An installed distribution that declares a console script of that name answers; its tool runs in footman's own process from that entry point. The entry point is not loaded, so asking imports none of the tool's code.
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
negations ¶
Each tool's keywords whose off spelling is not --no-<flag>, by tool.
fix=False on such a keyword spells the tool's own off flag, mkdocs's
clean=False as --dirty; the stub generator reads the same table.
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
wrappers ¶
Each tool's verbs that wrap another command, by tool.
A wrapper takes its own options before the command it runs, so a call
to one spells its flags first: uv run, docker exec, python itself.
Source code in packages/toolroom/src/livery/toolroom/tools/__init__.py
colour_controls ¶
Each curated tool's probed colour control, by tool: how footman forces it.
A row is (argv0, on, off, flag_on, flag_off, pre_verb): the tool obeys
env (FORCE_COLOR and NO_COLOR), needs its own flag, or can force
neither way (none); unprobed had no trigger. fm toolroom.color
writes the table, toolroom forces colour from it, and the docs show it.