API reference¶
Auto-generated from the source via
mkdocstrings. Everything here is importable
straight from the livery.footman package
(from livery.footman import task, run, App).
Defining tasks¶
livery.footman.Group ¶
A node in the command tree: named tasks and nested sub-groups.
Methods:
| Name | Description |
|---|---|
task |
Register a function as a task. |
group |
Create and register a nested command group, returning it. |
pre_tasks |
Register the once-per-invocation hook, run before anything else. |
pre_bind |
Register the before-binding hook: |
post_tasks |
Register the once-per-invocation closing hook: |
pre_reexec |
Register a block for the moment this process replaces itself. |
wrap_task |
Register a one-yield wrapper around the body: sugar over the pair. |
wrap_bind |
Register a two-yield wrapper spanning bind, body and all: sugar |
pre_task |
Register the before-each-task hook: |
post_task |
Register the after-each-task hook: |
default |
Register fn as this group's default action — what a bare |
opts |
Per-use option overrides for this group's default action, the same |
__call__ |
Run this group's default action — the imperative mirror of a bare |
Attributes:
| Name | Type | Description |
|---|---|---|
name |
|
|
help |
|
|
hidden |
|
|
expose |
|
|
tasks |
dict[str, Task]
|
|
groups |
dict[str, Group]
|
|
contributions |
dict[str, list[Any]]
|
|
mounted_from |
str | None
|
|
default_task |
Task | None
|
The default action — what a bare |
Source code in packages/footman/src/livery/footman/_registry.py
contributions
instance-attribute
¶
default_task
property
¶
The default action — what a bare fm <group> runs.
Derived, never stored: the default is the child task named
default (@group.default ↔ fm lint.default), so default-ness
has one spelling, survives forks and grafts by construction, and
there is no pointer to desync.
task ¶
task(fn: Callable[_P, _R_co]) -> TaskFn[_P, _R_co]
task(fn: None = None, *, name: str = '', pre: Sequence[Task] = (), post: Sequence[Task] = (), progress: bool = True, infinite: bool = False, shared: bool | None = None, confirm: str = '', interactive: bool = False, keep_going: bool | None = None, atomic: bool = False, timeout: float | None = None, retries: int = 0, cwd: str | Path = '', rel: str | Path = '', serial: bool = False, exclusive: bool = False, hidden: bool | None = None, expose: str | None = None, lanes: Sequence[Lane] = (), uses: Sequence[GlobalOption] = ()) -> Callable[[Callable[_P, _R_co]], TaskFn[_P, _R_co]]
task(fn: Task | None = None, *, name: str = '', pre: Sequence[Task] = (), post: Sequence[Task] = (), progress: bool = True, infinite: bool = False, shared: bool | None = None, confirm: str = '', interactive: bool = False, keep_going: bool | None = None, atomic: bool = False, timeout: float | None = None, retries: int = 0, cwd: str | Path = '', rel: str | Path = '', serial: bool = False, exclusive: bool = False, hidden: bool | None = None, expose: str | None = None, lanes: Sequence[Lane] = (), uses: Sequence[GlobalOption] = ()) -> Task | Callable[[Task], Task]
Register a function as a task.
Usable bare (@task) or parameterised (@task(name="build")) to
override the command name. pre/post declare dependency tasks (by
reference) that run before/after this one — the scheduler runs
independent prerequisites in parallel:
Availability gating lives in the @requires decorators — stack
@requires, @requires_dep, @requires_tool, or @requires_env
above @task to list a task as unavailable (with a reason) where it
can't run, rather than hide it.
Three different things, worth keeping apart:
hidden=True— out of the listings, callable as ever. The task drops out of--list,--treeand group help (--allbrings it back), whilefm <name>runs it exactly as before, Tab completes it, and the did-you-mean index knows it: a listing is prose about the project, completion is help with a name you are already typing. For the tasks a machine calls and a human never types: a CI entry point, a release step another task drives. It is presentation only — prerequisites still run it, a group's empty-body fan-out still includes it, and--jsonreports it marked rather than missing, because a machine is who calls it. Unset inherits the enclosing group's answer, sogroup("internal", hidden=True)hides a whole subtree and a child can still sayhidden=False.@requires…— listed with a reason it can't run here.if sys.platform == "darwin": @task ...— plain Python, and the task does not exist: nothing to list, nothing to call, no address at all. Reach for it when the task is meaningless on this machine, not when it is merely uninteresting to type.
progress=False marks a task whose duration has no rhyme or
reason (a REPL, a watcher, a network fetch): any run containing it
never records timing history and never shows a determinate
progress bar — the indeterminate pulse still does.
infinite=True marks a task that runs until stopped — a dev
server, a follow-mode tail. It implies progress=False, and the
run swaps the status line for a one-time hint that Ctrl-C is how
this ends. Listings and help carry the same note.
shared=False says this task is never shared: every request for
it runs. A run normally performs one execution per task and arguments,
whoever asks — pre=[build] then build() in a body is one build —
which is wrong for work whose whole point is to happen again, like a
notification or a timestamp. One rule covers every spelling, so nobody
has to remember whether a task was reached by declaration or by call:
two dependents each get their own run, just as two calls do.
Sharing is a property of the request, resolved by a ladder: this
reference's own .opts(shared=…), then the task's declaration, then
whatever asked for it, then shared. It propagates down — an unshared
request asks unshared for everything it needs, or the promise would be
a half-truth — which is worth knowing before reaching for it, because
one shared=False unshares that task's whole subtree. A step that
genuinely is reusable pins itself with shared=True, which beats an
inherited answer.
.opts(shared=False) asks for one unshared run without changing the
task, on a call or on a declared edge alike. Such a run gets its own
value but never rewrites what the run already remembers: the first
result stands, so later shared requests stay stable.
confirm="…" gates the task on a yes/no answer asked before the
task and its prerequisites run — deny and the task (and its
subtree) is skipped; --yes auto-answers it. interactive=True
hands the task the real terminal — no output capture, sole stdio —
so its body can prompt or run a REPL; it can't run under --json, and
because it owns the terminal, a run that contains an interactive task
goes fully sequential — that task and everything else, one at a time.
cwd= roots the task's working directory: a policy token ("root" —
the highest cascade file's directory, "taskfile" — the file the task
was defined in (the default), "asinvoked" — a pinned snapshot of the
launch directory, "unmanaged" — footman stays out entirely) or an
absolute path. rel= appends a relative suffix to the resolved base.
ctx.cwd and every run()/tools subprocess follow it.
Source code in packages/footman/src/livery/footman/_registry.py
1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 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 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 | |
group ¶
Create and register a nested command group, returning it.
hidden=True keeps the whole subtree out of the human listings
(--list, --tree, help — --all shows them) while leaving every
address in it callable and completable — see @task(hidden=…).
expose="project_only" says the whole subtree belongs to a project:
outside one it is not listed, not completed, and refused by name.
"global_only" says the opposite, "always" says both. A child may
still answer for itself — the same tri-state hidden has.
Source code in packages/footman/src/livery/footman/_registry.py
pre_tasks ¶
Register the once-per-invocation hook, run before anything else.
It happens after the whole tasks.py cascade is assembled and before
availability gates, the manifest, and any task — the one single-threaded
moment where the invocation is still editable. It is handed the
Invocation:
@footman.pre_tasks
def gate_deploys(inv):
audit = inv.tasks["audit"]
for t in inv.tasks:
if t.name.startswith("deploy"):
t.add_pre(audit)
Its edits are part of the plan, never a runtime surprise: an added pre
runs and shows in --dry-run, a disabled task drops out of listings and
completion. Setting os.environ here is ordinary code — it is pre-DAG
and single-threaded, so everything downstream sees it, including
requires_env gates and env() parameter fallbacks. (Per-task
environment is a different lane: ctx.env.)
Hooks run in cascade order — root's first, the folder nearest your cwd
last, each seeing the previous ones' edits — the same "local overrides
global" precedence the task cascade uses. Read and edit each task
through TaskView, never the private _footman_* attributes.
It also runs in the detached child that rebuilds the completion
manifest, so a gate that depends on what a hook sets is baked into
completion too. That is why it must be quick and quiet, and why
tree edits derive from files, config and environment — never from
inv.cli, which the child does not have.
Source code in packages/footman/src/livery/footman/_registry.py
pre_bind ¶
Register the before-binding hook: pre_bind(inv, task).
The earliest per-task moment: it fires before the task's parameters
are bound, so what it writes into task.env reaches env()
fallbacks, coercion, and check(fn) validators — the one moment a
plugin can influence what the body will be handed:
@footman.pre_bind
def credentials(inv, task):
task.env["DEPLOY_TOKEN"] = vault.read("deploy")
Because nothing is bound yet, task.args is not readable here —
read the values in pre_task, the post-bind moment. Binding happens
once per request: a request that then joins work the run already
performed still bound first, so pre_bind may fire for a request
whose row ends up shared.
Source code in packages/footman/src/livery/footman/_registry.py
post_tasks ¶
Register the once-per-invocation closing hook: post_tasks(inv).
The run report's moment, on the main thread, after every task has
concluded and before the summary or the --json envelope prints —
so a rewrite a hook makes through a result view is what gets
reported. The invocation now carries the whole story:
@footman.post_tasks
def digest(inv):
failed = [r for r in inv.results if not r.ok]
slack.post(f"{len(failed)} failed of {len(inv.results)}, "
f"{inv.total_ms:.0f} ms")
inv.results is every row, in the order the work was created, as
result views —
executions, shared rows, refusals, and skipped nodes
(inv.skipped is that subset; a post_task-only reporter never
sees what never ran, which is why this moment exists). Under
--json anything a hook prints goes to stderr — the envelope owns
stdout. Hooks run in cascade order; a raising hook is named and
fails the invocation rather than passing silently.
Source code in packages/footman/src/livery/footman/_registry.py
pre_reexec ¶
Register a block for the moment this process replaces itself.
A verb that re-runs its own command line in a new process — a sync that installed the code the process is running, a handoff into another environment — loses everything the process held. A plugin with state worth keeping across that gets it here:
@footman.pre_reexec
@contextlib.contextmanager
def carry_the_trace():
fragment = write_what_we_have()
yield {"MY_PLUGIN_STATE": str(fragment)}
fragment.unlink() # still here, so nothing was replaced
The hook is a context manager taking nothing and yielding a mapping
of environment entries for the successor, which the caller hands to
execve or subprocess.run(env=…). What it yields is merged with
every other subscriber's, and the caller's own entries win.
The block it wraps ends by not returning: an exec that works never
comes back, and a handoff that waits for its replacement exits with
its code. So a normal return means the replacement did not happen
and whatever was written down should be taken back; an exception
means it did, and the state stands. livery.footman.handing_off is
the composer a re-execing verb calls.
Source code in packages/footman/src/livery/footman/_registry.py
wrap_task ¶
Register a one-yield wrapper around the body: sugar over the pair.
Write the pre half, result = yield, then the post half — locals
carry your state, and a try/finally around the yield closes even
when the task fails:
@footman.wrap_task
def span(inv, task):
s = tracer.start(task.name, dict(task.args))
result = yield
s.end(ok=result.ok)
It enters at the pre_task moment and is resumed with the
ResultView at post_task — one engine, both spellings, so the
rules are the pair's rules: per request (a request satisfied by an
execution the run already performed is resumed with its shared
row), unwound in reverse plugin order, a raising half failing the
task, named. The one thing it never sees is a task that failed to
bind — its anchor moment never fires; observe the bind boundary
with @wrap_bind, which enters there.
Source code in packages/footman/src/livery/footman/_registry.py
1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 | |
wrap_bind ¶
Register a two-yield wrapper spanning bind, body and all: sugar
over pre_bind + pre_task + post_task, one generator per request.
The first yield sits at the bind boundary and receives the bound
arguments; the second sits around the body and receives the
ResultView:
@footman.wrap_bind
def audit(inv, task):
started = clock()
try:
bound = yield # after binding: the real values
result = yield # after the body: the outcome
finally:
log(task.name, clock() - started)
A failed bind arrives as the failure raised at the first yield,
so a try/finally (or except) around it closes the span even
then — the one span wrap_task cannot close. Everything else is the
pair's rules, per request.
Source code in packages/footman/src/livery/footman/_registry.py
1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 | |
pre_task ¶
Register the before-each-task hook: pre_task(inv, task).
Runs on the task's worker thread — in parallel across tasks, for
every request: a chain segment, a prerequisite, a fan-out member, a
body call. Only the body is shared: a request satisfied by an
execution the run already performed still gets the pair, opened here
and closed by post_task with its shared row — so pairing never
depends on sharing, and only a reporter that cares reads
result.state. It fires after binding, so task.args holds the
real values the body would receive:
@footman.pre_task
def open_span(inv, task):
task.state.span = tracer.start(task.name, dict(task.args))
inv is the frozen invocation — read it freely, it cannot change under
you. Per-plugin scratch goes on task.state (private to your plugin,
one namespace per execution, delivered back to your post_task);
per-task environment goes in task.env (the task's own overlay —
never os.environ, which is shared with every parallel sibling).
A raising hook fails the task like a failed prerequisite, named.
The return value is reserved: a future power for a pre that
supplies the task's result and skips the body. Today a returned value
is noted and ignored — state belongs on task.state.
Source code in packages/footman/src/livery/footman/_registry.py
post_task ¶
Register the after-each-task hook: post_task(inv, task, result).
The task-finished event: once a request's ladder opened, it fires
when the request concludes — an execution whatever its outcome, a
bind refusal, or a request satisfied by an execution the run already
performed (result.state == "shared"). It fires whether or not your
plugin registered a pre, and however any pre fared. Posts unwind in
reverse plugin order, so the first plugin in speaks last.
result reads everything (ok, code, returned, error,
duration, output, steps) and writes one thing: set_returned,
which rewrites the reported value — the summary and the --json
envelope — never what a dependent or a body caller received. A raising
hook fails an otherwise-green task, named: a reporter that crashed
must not pass silently.
@footman.post_task
def close_span(inv, task, result):
task.state.span.end(ok=result.ok)
Source code in packages/footman/src/livery/footman/_registry.py
default ¶
default(fn: Callable[_P, _R_co]) -> TaskFn[_P, _R_co]
default(fn: None = None, *, pre: Sequence[Task] = (), post: Sequence[Task] = (), progress: bool = True, infinite: bool = False, shared: bool | None = None, confirm: str = '', interactive: bool = False, keep_going: bool | None = None, atomic: bool = False, timeout: float | None = None, retries: int = 0, cwd: str | Path = '', rel: str | Path = '', serial: bool = False, exclusive: bool = False, hidden: bool | None = None, expose: str | None = None) -> Callable[[Callable[_P, _R_co]], TaskFn[_P, _R_co]]
default(fn: Task | None = None, *, pre: Sequence[Task] = (), post: Sequence[Task] = (), progress: bool = True, infinite: bool = False, shared: bool | None = None, confirm: str = '', interactive: bool = False, keep_going: bool | None = None, atomic: bool = False, timeout: float | None = None, retries: int = 0, cwd: str | Path = '', rel: str | Path = '', serial: bool = False, exclusive: bool = False, hidden: bool | None = None, expose: str | None = None) -> Task | Callable[[Task], Task]
Register fn as this group's default action — what a bare
fm <group> runs, and what the group returns when called.
Usable bare (@group.default) or parameterised
(@group.default(keep_going=True)). It takes the same orchestration
options as @task — pre/post, progress, infinite, confirm,
interactive, keep_going, atomic — with no name (the group
already names it).
The function's signature is the group's whole CLI surface,
positionals included: fm lint src/ hands src/ to the default the
way any task takes an argument. A nested task always keeps its own
dotted address (fm lint.python), so a bare word after the group is
unambiguously the default's value — when a value happens to equal a
child's name, the run carries a one-line stderr note pointing at the
dotted spelling.
An empty-body default fans the group's own tasks out in parallel, so
interactive=True on one is rejected — there is no single body to own
the terminal. Give the default a real body to make it interactive.
The default registers as the child task named default — a
fixed, well-known name, not the function's own (which stays private,
so renaming it is free). The decorator you wrote is the address you
type: @lint.default ↔ fm lint.default; bare fm lint stays the
idiomatic spelling, the way GET / serves /index.html. The name is
the mechanism — @group.default is sugar for a task named default.
Source code in packages/footman/src/livery/footman/_registry.py
2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 | |
opts ¶
Per-use option overrides for this group's default action, the same
.opts() a task has — pre=[lint.opts(keep_going=True)]. Overrides ride
the group's default when it runs (bare, as a pre=, or called). The
static type is a task reference with an untracked signature — Group
doesn't carry its default's parameters the way TaskFn carries a
task's.
Source code in packages/footman/src/livery/footman/_registry.py
__call__ ¶
Run this group's default action — the imperative mirror of a bare
fm <group> and of pre=[group].
A runnable group (one with an @group.default) is callable from a task
body the way a task is: a check task can call lint(fix=fix). It runs
the default's action synchronously and in order — a custom body as
written, or, for an empty-body default, the group's own tasks, each
handed the arguments it declares (partial reach, by name). Like every
body call it forwards arguments explicitly and runs to completion before
the next statement; prerequisites and parallelism stay the scheduler's
job — reach for a real chain, pre=, or parallel() for those.
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.expose ¶
Say where a task is offered: @expose("global_only").
The decorator spelling of @task(expose=…), for authors who prefer the
gates above the signature — it sets the same one answer, so stacking it
twice is a contradiction rather than an addition, unlike @requires_*.
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.task_tree ¶
The composed task tree of this process, as --json --list reports it.
Every task and group the cascade and the plugins mounted into the
running CLI, with each task's hidden flag and the extension that
mounted it, in the shape the catalog envelope prints. A task that
renders a listing of its own CLI reads this instead of running the
CLI again: the tree is built before any task runs, and this is a copy
of it. A tree is a process's own, made from the distributions on its
path, so another directory's tree is listed by running that
directory's CLI with --json --list. Outside a run the tree is the
process registry's, which holds what was registered so far.
Source code in packages/footman/src/livery/footman/_manifest.py
Availability gates¶
Stack these above @task to list a task as unavailable (with a reason) where it can't run. Every availability gate is evaluated live, and all failures are collected.
livery.footman.requires ¶
Gate a task on a live predicate — available only while it is truthy.
The generic gate the three specialisations build on. A predicate that raises reads as unavailable, the exception named:
@task
@requires(lambda: Path("config.toml").exists(), reason="needs config.toml")
def publish(): ...
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.requires_dep ¶
Gate a task on Python modules being importable (find_spec, no import).
Keep the real import in the body; this only checks availability, so a
missing optional dependency lists as a clean reason, never an import crash.
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.requires_tool ¶
Gate a task on command-line tools being on PATH (shutil.which).
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.requires_env ¶
Gate a task on environment variables being set (in os.environ).
Source code in packages/footman/src/livery/footman/_registry.py
Running commands¶
livery.footman.run ¶
run(cmd: str | list[str] | Callable[..., Any], *args: Any, nofail: bool = False, recorded: bool = True, capture: bool = True, input: str | bytes | None = None, timeout: float | None = None, title: str | None = None, pre_record: Callable[[ResultView], None] | None = None, env: dict[str, str] | None = None, color: str = 'auto', cwd: str | Path | None = None, rel: str | Path | None = None, encoding: str | None = 'utf-8', shell: bool | str = False, strict: bool = False, clean: bool = False, view: CommandView | None = None) -> Result
Run a command or a Python callable in the current task's context.
Subprocess output is decoded as UTF-8 by default; pass encoding= for a
tool that speaks another code page, or encoding=None for the locale
default. Ignored for callables (in-process, no bytes boundary).
input= feeds the child's standard input and closes it — the one lane a
payload can't take through argv (uv pip install -r - reads its
requirements there). A string, encoded the way the capture is decoded
(encoding=). Bytes go as they are, in a binary lane: no newline
translation on any platform, and the captured streams are decoded with
surrogateescape, so stdout.encode(encoding, "surrogateescape")
gives a binary tool's bytes back exactly. The read side of the process
boundary is a task parameter marked stdin; this is the write side, so a
task can sit in
the middle of a pipeline without a shell between it and either
neighbour. An in-process tool has no standard input to feed — input=
on one is a taught TypeError.
cwd= roots this one call somewhere other than the task's directory;
rel= appends a relative suffix to the base in force (ctx.cwd, or the
explicit cwd=), so run("npm run build", rel="web") is the ergonomic
spelling of cwd=ctx.cwd / "web". cwd="unmanaged" opts this one call
out instead — the task-level token, per call: a subprocess spawns
inheriting the live process cwd, an in-process callable runs under it —
for a call that touches no paths while its task keeps ctx.cwd
everywhere else.
color= decides what this one child emits: "always" forces the colour
variables into its environment, "never" writes NO_COLOR and removes
any inherited force variables (a tool reading mere presence would honour
one straight past NO_COLOR), and the default "auto" follows the run's
own decision. Explicit beats ambient, so color="always" holds under an
exported NO_COLOR. It merges on top of env= when both are given, and
the in-process lane's overlay reads it too — so a per-call colour reaches
both halves of a tool's colour, its flags and its environment, through
one door. footman's own chrome (the step lines) stays on the run-wide
decision: this is about the child's bytes, not the frame around them.
recorded=False runs this call off the record. A call is a step
by default: it earns a receipt line, a row in --json, a recording()
entry, and its output joins the task's block. Some calls aren't part of
the task's story, though — they are how a task knows something (git
rev-parse HEAD in a release task). Those return their Result and
report nothing: no record, no receipt, no output replayed. The one
reader they reach is a profile: while the run keeps a trace, the call
is timed as a section named for its command, so the trace shows where
a task's time went; without --profile nothing is kept of it.
Everything else still applies, because the call is not unmanaged — only
unreported. It runs in ctx.cwd with ctx.env, inside the task's lane,
with colour resolved the same way, it is terminated with the rest on a
fail-fast, and it still raises unless nofail=True. It also executes
under recording(), where a step would be faked — unless the recording
carries a scripted answer for it (recording(answers=…)), in which case
the script wins: a value read is not the story being recorded, and
faking it would corrupt the story that is —
the real steps downstream would record whatever a blank answer produced.
pre_record= reviews the record before it is sealed. Some tools
speak exit codes that need interpreting — djlint --reformat exits 1
when it changed files, which is success for a formatting gate. The
reviewer receives the draft (ResultView) after the work ran: it reads
what was captured and may set title and code; the receipt, the
record, and the raise-on-nonzero decision all read what the review
leaves behind, so the call site writes no nofail=. A reviewer that
raises fails the call with its own error — a broken reviewer is a
broken gate — and the record keeps what the work honestly produced.
Dry-run never reviews (nothing ran, nothing captured), and a
recorded=False call has no record to review (a note, not an error).
In-process work is a step now: run() runs commands. Lift a
callable instead — @step / step(fn, title=…) builds an item that
earns a receipt, and with step("…"): records a block where it
stands. A tool wrapper's in-process lane is the one exception: a
callable with a view runs in-process, as the wrapper's own spelling
of a command.
view is a tool wrapper's structured view of the call (CommandView),
so the shown command line can be normalised and role-coloured while
execution runs whatever the tool needs. An explicit title still wins;
a direct run([...]) is unaffected.
Source code in packages/footman/src/livery/footman/_context.py
3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 | |
livery.footman.Result ¶
Bases: int
The outcome of one run() call — and the value run() returns.
A Result is the exit code: it subclasses int, so code = run(...),
if run(...), and run(...) == 0 all keep working. It also carries the
captured output, split by stream, and the command that produced it — so
run("git rev-parse HEAD").stdout.strip() reads the hash without the
stderr noise glued on. stdout/stderr are separated for both subprocess
and in-process runs; a streamed run (capture=False) leaves them empty.
Methods:
| Name | Description |
|---|---|
__new__ |
|
to_argv |
What this call ran, as the tokens it was spawned from. |
__setattr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
command |
str
|
The command line that ran, normalised for reading — options in |
shown |
str
|
|
stdout |
str
|
Captured standard output; empty when the step streamed instead. |
stderr |
str
|
Captured standard error; empty when the step streamed instead. |
duration |
float
|
Wall-clock seconds the step took. |
started |
float | None
|
When the step began, on the run's monotonic clock — the same clock |
raw |
str
|
The exact command line executed, shell-quoted — the bytes footman |
timed_out |
bool
|
Whether |
address |
str
|
The record's tree-derived name: the requester's path, this |
audit |
tuple[AuditEntry, ...]
|
The verdict's provenance: every lifecycle moment that acted on |
env |
dict[str, str] | None
|
The environment this call would have run in — the task's own, or |
cwd |
Path | None
|
The directory this call would have run in — the task's resolved |
code |
int
|
The exit code (0 is success) — the same value the |
ok |
bool
|
Whether the command succeeded (exit code 0). |
output |
str
|
|
failed_at |
str | None
|
The lifecycle moment the failure came from, None on success — a |
work_code |
int | None
|
The code the record carried when the failing moment began — a |
command
property
¶
command: str
The command line that ran, normalised for reading — options in
separated form, values shell-quoted. What recording() asserts
against, and what a dependent reads back.
shown
property
¶
shown: str
command as it is safe to print — every argument that arrived
as a Secret replaced by ***, everything else identical.
Equal to command unless the call carried a secret, so a record is
the same string on both sides in the ordinary case. Every surface
footman shows a command line on reads this one: the step line, the
--verbose announce, --json, a profile span, the message a
RunFailed carries. The record keeps the real value, because a
dependent, recording(), and the caller who passed it all read
command and none of them are a display.
started
property
¶
started: float | None
When the step began, on the run's monotonic clock — the same clock
a task row's started reads, so a step places inside its task's
span. None for a record that never ran (a dry-run's rehearsal).
raw
property
¶
raw: str
The exact command line executed, shell-quoted — the bytes footman
handed the tool, which may spell an option --flag=value where
command shows --flag value. What --verbose prints. Equal to
command when there is nothing to normalise.
timed_out
property
¶
timed_out: bool
Whether timeout= expired and footman killed the tree. The code
is 124 — the shell convention — and stdout/stderr hold whatever
the command managed to say first, which on a hang is the only clue
there is.
address
property
¶
address: str
The record's tree-derived name: the requester's path, this record's label, and an ordinal once a label repeats among siblings — counted in request order as written, so it is deterministic across runs and hosts. Empty outside a managed context.
audit
property
¶
audit: tuple[AuditEntry, ...]
The verdict's provenance: every lifecycle moment that acted on
it, in execution order — the body entry with what the work itself
produced, a review entry per pre_record reviewer. Empty for a
record that executed nothing (a dry-run plan line).
env
property
¶
The environment this call would have run in — the task's own, or
the env= handed to the call — kept on a recorded step only, so
a recording() can assert what a command would have seen (assert
"UV_TOOL_DIR" not in steps[0].env). None on a record that ran:
a live environment can hold secrets, and a record travels into
--json and the report.
cwd
property
¶
cwd: Path | None
The directory this call would have run in — the task's resolved
one, or the call's cwd=/rel= — kept on a recorded step only,
like env. None on a record that ran, and for a call that opted
out with cwd="unmanaged".
output
property
¶
output: str
stdout then stderr, concatenated — a convenience for "show me
everything". NOT interleaved in real time (each stream is captured
whole); when the order across the two streams matters, read stdout
and stderr separately.
failed_at
property
¶
failed_at: str | None
The lifecycle moment the failure came from, None on success — a
derived reading of the audit: the last moment that wrote the verdict.
A red tool reviewed green reads None (the record succeeded); a green
tool failed by its reviewer reads "review".
work_code
property
¶
work_code: int | None
The code the record carried when the failing moment began — a derived reading of the audit, None on success or when nothing came before the failure. A green build failed in review keeps its 0 here, visible rather than inferred.
__new__ ¶
__new__(code: int, *, command: str = '', stdout: str = '', stderr: str = '', duration: float = 0.0, raw: str = '', shown: str = '', timed_out: bool = False, address: str = '', audit: tuple[AuditEntry, ...] = (), tokens: tuple[str, ...] = (), started: float | None = None, env: dict[str, str] | None = None, cwd: Path | None = None) -> Result
Source code in packages/footman/src/livery/footman/_context.py
to_argv ¶
to_argv() -> Argv
What this call ran, as the tokens it was spawned from.
.raw shows the command line quoted for the machine footman is
standing on, which is right for a --verbose line and wrong the
moment the string is sent somewhere else. This returns the same
command as an Argv — raw tokens, re-quotable for whichever shell
will actually parse them:
r = git.commit(m="ship 1.2.0")
r.to_argv() # ["git", "commit", "-m", "ship 1.2.0"]
r.to_argv().posix() # "git commit -m 'ship 1.2.0'"
Named apart from toolroom's .argv builders on purpose: this one describes
a call that has already run, so git.push().argv(…) — meaning to
build a command line — is an AttributeError rather than a push
that quietly happened. For the same reason the two can differ by one
token: what ran may carry a forced-colour switch (git's
-c color.ui=always) that a line built to be sent elsewhere does not.
Source code in packages/footman/src/livery/footman/_context.py
__setattr__ ¶
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.ResultView ¶
ResultView(*, title: str, code: int, stdout: str, stderr: str, duration: float, raw: str, command: str, returned: Any = None)
A step's record, in the review window: the draft a pre_record
reviewer receives after the work ran and before the record is sealed.
The verdict is still open — title and code are plain writable
attributes, and the raise-on-nonzero decision reads the code the review
leaves behind, so "fail by this tool's definition of failure" needs no
nofail= at the call site. Everything the run captured is read-only:
review sees what the run kept, never edits it — an uncaptured
(capture=False) call reviews the code alone. ok derives from code,
so the two can never disagree.
Methods:
| Name | Description |
|---|---|
set_returned |
Rewrite the reported value — the summary line and the |
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
title |
str
|
The receipt's label. Starts as the shown command (or the call's |
code |
int
|
The verdict. What the review leaves here is the step's exit code — |
ok |
bool
|
Whether the code, as it stands, is success — derives from |
stdout |
str
|
Captured standard output; empty when the call streamed instead. |
stderr |
str
|
Captured standard error; empty when the call streamed instead. |
output |
str
|
|
duration |
float
|
Wall-clock seconds the work took — machinery-owned, read-only. |
raw |
str
|
The exact command line executed — the review can read what really |
command |
str
|
The normalised command line as it stood before review. |
returned |
Any
|
What the body returned, when this draft is a task's row — None by |
Source code in packages/footman/src/livery/footman/_context.py
__slots__
class-attribute
instance-attribute
¶
__slots__ = ('_code', '_command', '_duration', '_raw', '_returned', '_stderr', '_stdout', '_title', '_touched')
title
property
writable
¶
title: str
The receipt's label. Starts as the shown command (or the call's
title=); what the review leaves here is what the report shows.
code
property
writable
¶
code: int
The verdict. What the review leaves here is the step's exit code — the raise decision and the receipt both read it. The audit records whether a reviewer wrote it or left it alone.
output
property
¶
output: str
stdout then stderr, concatenated — the same convenience the
sealed Result offers.
raw
property
¶
raw: str
The exact command line executed — the review can read what really ran while retitling what the report shows.
returned
property
¶
returned: Any
What the body returned, when this draft is a task's row — None by circumstance elsewhere (a subprocess step has no return value).
set_returned ¶
set_returned(value: Any) -> None
Rewrite the reported value — the summary line and the --json
envelope — never what a dependent or a body caller received: that was
snapshotted the moment the body handed it over. The review window is
this write's home: reviewed, attributed in the audit, before the
record seals.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.AuditEntry ¶
Bases: NamedTuple
One entry of a record's audit: a lifecycle moment that acted on the verdict — who acted, and what they set.
The body entry is always present and carries what the work itself
produced; a review entry names the reviewer, with code None when it
was involved without writing the verdict (a reviewer that only set the
title). Entries are in execution order.
Attributes:
| Name | Type | Description |
|---|---|---|
moment |
str
|
Where in the record's lifecycle this happened: |
actor |
str
|
Who acted: the command line for the body, the hook's name for a |
code |
int | None
|
The code this moment left, or None for involvement without a verdict |
livery.footman.Argv ¶
A command line built but not run — what Result.to_argv() hands back
(and what a builder like toolroom's git.push.argv(force=True) makes).
An ordinary list[str] everywhere in Python: it indexes, slices,
iterates, compares and prints exactly like the list it is, and run(cmd)
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: run(cmd) runs
them, 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 footman 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 — a line built on Windows for a
Linux box still comes back POSIX-quoted (which is why neither method is
the local-platform _shell_quote).
Lives here beside Result because run() accepts one and
Result.to_argv() returns one. toolroom carries its own twin of this
class on purpose — the seam between the packages speaks plain
list[str], so neither ever imports the other's.
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__ |
|
posix ¶
posix() -> str
This command as one string, quoted for a POSIX shell.
What an ssh payload wants: ssh joins its remaining arguments with
spaces and hands the remote shell one string to re-split, so the
only argument boundaries that survive are the ones quoted into it.
cmd = git.commit.argv(m="ship 1.2.0")
ssh("deploy@host", cmd.posix())
Quoting a built line that already carries a .posix() payload quotes
it once more, which is exactly what each further hop needs.
Source code in packages/footman/src/livery/footman/_context.py
windows ¶
windows() -> str
This command as one string, quoted the way CreateProcess parses.
The Windows counterpart of .posix(), for a payload headed to a
Windows box — subprocess.list2cmdline quoting, which cmd and
PowerShell both read. Chosen by the caller, never sniffed from the
machine footman happens to be standing on.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.RunFailed ¶
RunFailed(result: Result)
Bases: Exception
A run() command exited non-zero (and nofail was not set).
The message names the command the way every other surface does — with
any Secret argument redacted — because a failure line is a display,
and the one place it most reliably lands is somebody's CI log. The
record it carries, .result, is untouched: .result.command is the
real command line, for the handler that reads rather than prints.
Attributes:
| Name | Type | Description |
|---|---|---|
result |
|
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.RunTimeout ¶
Bases: RunFailed
A run(timeout=…) expired and the process tree was killed.
A RunFailed, so every except RunFailed keeps catching it; catch this
to tell a hang from an ordinary non-zero exit — the distinction a version
or help probe branches on.
Attributes:
| Name | Type | Description |
|---|---|---|
result |
|
|
timeout |
|
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.parallel ¶
parallel(*, keep_going: bool = False) -> Fanout
parallel(*calls: WorkItem[Any] | StepFn[..., Any] | TaskFn[..., Any] | Group, keep_going: bool = False) -> Fanout | list[Result]
Run tasks and steps concurrently; wait; fail if any fail.
Each one runs in a child of the current context with its own output
buffer, flushed atomically on completion so concurrent output never
interleaves. Pass task functions directly (parallel(lint, typecheck))
and built step items for everything else — parallel(convert(images)),
or parallel(step(fn)(args)) for a function you didn't write. A bare
zero-argument maker is welcome too: parallel(clean) builds and runs
clean().
Nothing anonymous runs: footman only schedules, records, and safely cancels work it owns, and a bare callable is a stranger — no name for the report, no place in the plan, no way to stop it cleanly. The lift is one word, and it buys the step a receipt.
With no arguments it is a block instead, and the calls inside it are the fan-out — written as ordinary calls, with their values afterwards:
with parallel() as p:
build("web")
p(step(shutil.rmtree)(tmp, ignore_errors=True))
web, cleaned = p.results
Inside the block a task call is queued, so it has no value there (using
one is a taught error); a built step item joins through p(item);
everything runs when the block ends, under the same rules — sharing,
hooks, -s/-j.
Source code in packages/footman/src/livery/footman/_context.py
4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 | |
livery.footman.step ¶
step(target: Callable[P, Generator[None, ResultView, R]], /, *, title: str | None = None) -> StepFn[P, R]
step(target: str) -> _StepBlock
One name, three positions: @step on a def, with step("title"):
over a block, step(fn, title=…) around a function you didn't write.
Decorator and expression positions are the same expression, so both
return the maker — calling it builds the item; nothing runs until
something executes it (parallel(), or calling the built item).
Source code in packages/footman/src/livery/footman/_step.py
livery.footman.pre_record ¶
Attach a reviewer to a task: @pre_record(fn) stacked on the def.
The reviewer receives the task's record while it is still a draft — after
the body concluded, before the record is sealed, observed, or reported.
It reads the draft (a ResultView) and may set title and code; the
row's verdict follows what the review leaves behind, and the record's
audit names the reviewer and what it did.
Reviewers run from the inside out: the hook written closest to the
function sees the draft first, and each one above it sees what the
previous reviewers left. Stacks above or below @task alike — the
decorated function (and a TaskFn when stacked above the lifter) keeps
its static type. A reviewer that raises fails the task with its own
error: a broken reviewer is a broken gate.
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.passthrough ¶
livery.footman.inherited ¶
The task this one shadows in the cascade — footman's super().
A nearer tasks.py overriding a task by name usually wants to extend
it, not replace it. Call this inside the overriding task's body to get
the task it shadows, then call that like the plain function it is:
# svc/api/tasks.py — the root also defines `check`
@task
def check(fix: bool = False, contracts: bool = True):
inherited()(fix=fix) # arguments are forwarded explicitly
if contracts:
run("./verify-contracts.sh")
Forwarding is deliberately manual: the two signatures are independent
(a leaf usually adds a parameter), so automatic forwarding could only
drop arguments silently or fail at run time — where spelling the call
out shows you the mismatch as you type it. Being an ordinary call,
it also runs to completion
before the next statement — and composes with parallel(inherited(),
extra) when you want otherwise.
fm --where <task> lists the whole shadow chain; fm --help <task>
shows the inherited task's options, so you can read the forwarding
call straight off it.
Source code in packages/footman/src/livery/footman/_context.py
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 | |
Failing on purpose¶
livery.footman.fail ¶
Fail the current task with a reason (and exit code, default 1).
The blessed way to stop a task deliberately: fail("no open PR to act on"),
or fail("reserved branch", code=3) to pick the exit code too. A function,
not a raise, on purpose — a task lives in your repo under your linter, and
raise SomeError("a literal") trips flake8-errmsg (EM101) and tryceratops
(TRY003) at the call site, every failure. A call trips neither, the same
reason sys.exit() and pytest.fail() are functions. return N still
spells a bare code; sys.exit(...) still works — fail() is just the
footman-native one, with a reason and a code together.
fail() means failure, so code=0 — success — is a contradiction it
refuses rather than a corner it interprets: return 0 (or a plain
return) spells stopping early with success.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.Failed ¶
Bases: Exception
A task chose to fail — the exception footman.fail() raises.
A deliberate stop with a reason (and optional exit code): the user-facing
sibling of RunFailed (which is a command's failure). Carries .reason
and .code; footman renders the reason verbatim — no type prefix — in the
failure line and the --json error field. Exported so a task can
except footman.Failed:, but fail() is the blessed way to raise it.
Attributes:
| Name | Type | Description |
|---|---|---|
reason |
|
|
code |
|
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.TimedOut ¶
TimedOut(task: str, timeout: float, *, after: str = 'stopped', body: str = '', at: float = 0.0, not_retried: bool = False)
Bases: Failed
A task's @task(timeout=…) deadline expired.
A Failed, so except footman.Failed: keeps catching it and the reason
renders verbatim in the failure line and the --json error field.
Carries .timeout (the declared seconds) and .after — what became of
the work: stopped (footman issued a stop before the body returned) or
completed (no stop was issued and the body finished on its own, just
late). An open set: TaskResult.after_deadline explains which further
values are designed and why they are not shipped.
The message never pretends the work did not happen. Where the body completed, it says so and says what the body's own verdict was, then states that the deadline governs — the receipt tells the whole truth while the task still fails on its contract (notes/20260807-timeout-and-retry.md).
Attributes:
| Name | Type | Description |
|---|---|---|
timeout |
|
|
after |
|
|
not_retried |
|
Source code in packages/footman/src/livery/footman/_context.py
Checking the runner¶
What fm doctor prints is findings: footman's own checks of the runner's directories and scratch, then every doctor an installed package registers under the footman.doctors entry-point group. A doctor returns these; --fix runs each one's repair and checks again.
livery.footman.Finding ¶
Bases: NamedTuple
One answer of a doctor: what was checked, what is wrong, how to fix it.
def doctor(**facts):
missing = [p for p in views() if not p.exists()]
if not missing:
return [footman.Finding("views: whole")]
return [footman.Finding("views", f"{len(missing)} missing", "sync", mend)]
Attributes:
| Name | Type | Description |
|---|---|---|
what |
str
|
The check and its answer, short, the way a receipt names a step. |
found |
str
|
What is wrong; empty for a healthy check, which prints |
fix |
str
|
The words a person acts on when the finding stands. |
repair |
Callable[[], None] | None
|
An action that mends it, run under |
what
instance-attribute
¶
what: str
The check and its answer, short, the way a receipt names a step.
found
class-attribute
instance-attribute
¶
found: str = ''
What is wrong; empty for a healthy check, which prints what alone.
Progress¶
livery.footman.progress ¶
Report this task's own progress: done of total units.
Some work knows exactly how far along it is — 23 of 150 migrations, bytes of a download — and that is better evidence than any duration history. A reporting task's counts drive the live bar directly (counted beats estimated), so the bar is honest on the very first run, where the estimator would still be guessing.
@task
def migrate():
for i, record in enumerate(records, 1):
apply(record)
progress(i, len(records))
A total of 0 (or less) clears the report, returning the run to its
estimate. Outside a run, or with no live status line, this is a
no-op — plain calls and captured runs cost nothing.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.track ¶
Iterate iterable, reporting progress as it goes.
The ergonomic form of progress(): the total comes from len() when
the iterable has one, or from total when you know it for a
generator. Without either, iteration still works — the run simply
keeps whatever progress it had.
Source code in packages/footman/src/livery/footman/_context.py
Profiling from inside a task¶
livery.footman.section ¶
section(name: str) -> _SectionTimer
Time a section of the running task — with footman.section("resolve"):.
Records onto the task's own timeline, subdividing its span; nested
blocks nest. For work that overlaps — several waits in flight at once —
use stream(), where overlap is legal.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.mark ¶
mark(name: str) -> None
Record an instant on the running task's timeline — a moment worth a label, no duration.
livery.footman.stream ¶
A named parallel timeline under the running task — see Stream.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.Stream ¶
A named parallel timeline of sections under the running task.
Made in the task body (ci = footman.stream("ci")); the handle remembers
its task, so a helper thread the body spawned may record through it.
Sections on a stream may overlap — that is what a stream is for.
Methods:
| Name | Description |
|---|---|
section |
A section on this stream: bracketing ( |
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
name |
str
|
|
Source code in packages/footman/src/livery/footman/_context.py
section ¶
section(name: str) -> _SectionTimer
section(name: str, *, start: datetime | float | None = None, end: datetime | float | None = None) -> _SectionTimer | None
A section on this stream: bracketing (with ci.section("poll"):)
or retroactive — ci.section("build", start=t0, end=t1) records a
window learned after the fact (a CI check's real run, reported by
its API), placed by wall clock.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.Section
dataclass
¶
One recorded interval of a task's time — what the --json envelope
carries and a profile renders. stream is "" for the task's own
timeline (these nest and never overlap, by construction); a named stream
is its own parallel timeline, where overlap is legal. A mark() is a
section with no duration.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
started |
float
|
|
duration |
float
|
|
stream |
str
|
|
Asking the person running it¶
livery.footman.prompt ¶
Ask the person running the task for a line of input.
A bare input() doesn't work in a task: its prompt goes to stdout, which
footman buffers per task so parallel output never interleaves (and --json
stays one envelope), so the prompt is swallowed and the task looks hung.
prompt() writes to the real terminal on stderr instead — never captured —
and serialises concurrent prompts.
Usable only inside an @task(interactive=True) task; called in an ordinary
task body it raises a taught error naming the two fixes. Off a terminal,
under --no-input or --dry-run, or when it would otherwise block, it
returns default if given, else raises — an unattended run fails loudly,
and a rehearsal is unattended by nature. For a value a
script must supply, take it as a task parameter (a CLI flag) instead.
type= reuses the parameter type language as the validator: the answer
runs through the same coercion pipeline a flag does — int, Path, an
enum, Literal[…], a union, or Annotated[…] carrying between() /
check() / exists — and a bad answer is taught and re-asked rather
than raised. An empty answer takes default (returned as given,
uncoerced), and an unattended run takes it the same way. One value per
prompt: collections, and the markers that decide how a parameter gets
filled (ask(), env(), suggest(), …), are refused by name — declare
a parameter, or reach for select().
secret=True hides the typing (getpass) and returns a Secret, so the
answer redacts in tracebacks and structured output the same way
ask(secret=True) does — hiding a value while it is typed and then
printing it in the first traceback would be a strange kind of secret.
A default returned unattended is wrapped too: where the value came from
doesn't change what it is. A secret is text by nature, so secret=True
with a non-str type= is refused — ask(secret=True) on a typed
parameter is that spelling.
Source code in packages/footman/src/livery/footman/_context.py
2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 | |
livery.footman.confirm ¶
Ask a yes/no question. --yes auto-answers yes; Enter alone takes
default; off a terminal or under --no-input/--dry-run the answer
is default. Guarded like prompt() — interactive tasks only.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.select ¶
select(message: str, options: Sequence[str], *, multiple: Literal[True], default: list[str] = ...) -> list[str]
select(message: str, options: Sequence[str], *, multiple: Literal[False] = False, default: str = ...) -> str
select(message: str, options: Sequence[Any], *, multiple: bool = False, default: Any = _UNSET) -> Any
Let the person pick from a runtime-computed list — the one interactive case a flag can't cover, because the options aren't known until the task runs (which changed packages to release, which stale branches to delete).
options are strings, or (label, value) pairs to show one thing and
return another. multiple=True returns the chosen subset as a list;
otherwise one value is returned. Guarded like prompt() (interactive tasks
only), and off a terminal or under --no-input/--dry-run it returns
default, or raises if none was given.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.attended ¶
attended() -> bool
Whether a prompt would reach a human: stdin is a real terminal and the
run was not declared unattended (--no-input, --dry-run).
The question prompt()/confirm()/select() already answer for
themselves by degrading to their defaults — attended() is for changing
the shape of a run instead: skip an optional wizard outright, take the
quiet path in CI. --yes deliberately does not count as unattended: it
auto-answers confirm() gates but forbids nothing.
Readable anywhere, but it licenses nothing: a mid-body prompt still
requires @task(interactive=True), because owning the terminal under
parallelism is a separate question from someone being there to answer.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.tty ¶
tty() -> bool
Whether this run's output lands on a live terminal, colour policy
aside: the real stdout is a terminal (on Windows, one that interprets
ANSI) and output is not captured into a --json envelope. NO_COLOR and
--color do not change the answer — a person with colour turned off is
still watching, so gate pagers and live displays here and colour on
colored(). False outside a run: the scheduler stamps it per task.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.colored ¶
colored() -> bool
Whether this task's own output should dress for colour — the same
never/always/auto cascade footman's own chrome follows:
--color=never (or NO_COLOR, or a dumb terminal) says no,
--color=always forces colour even into a pipe (but never into a
--json envelope), and auto follows the terminal.
Source code in packages/footman/src/livery/footman/_context.py
Painting output¶
wants_color(stream) answers whether to paint text for a stream, following --color, NO_COLOR and the stream's own tty-ness, and styled(text, style, on=…) paints it.
livery.footman.wants_color ¶
Whether to paint output for stream under a resolved colour mode.
"always"/"never" are the explicit tri-state answers (--color=…, config,
FORCE_COLOR/NO_COLOR); "auto" (the default) falls back to the stream's
own tty-ness, honouring NO_COLOR and a dumb terminal.
Source code in packages/footman/src/livery/footman/_describe.py
livery.footman.styled ¶
text in style when on, else as it is: bold, dim, cyan, bold-cyan or red.
Pass on=wants_color(stream) so a pipe or NO_COLOR gets plain text;
inside a task, colored() answers the same question for its output.
Raises:
| Type | Description |
|---|---|
ValueError
|
for a style |
Source code in packages/footman/src/livery/footman/_describe.py
The process boundary¶
stdin binds to typed parameters, and a Stdout[T] return owns stdout. The full contract lives on Pipelines and JSON output.
livery.footman.Stdin
module-attribute
¶
livery.footman.stdin ¶
Bind this parameter from the process's standard input, via Annotated:
def review(diff: Annotated[str, stdin] = ""): ...
# git diff | fm review AND fm review < changes.patch
The annotation decides how the bytes are interpreted: str reads the
stream as UTF-8 text (universal newlines), bytes reads it raw. Two
call forms refine that:
stdin("prompt")binds one top-level field of a JSON document on stdin — the value flows through the same coercion and validation as a CLI token.stdin(lines=True)binds a list parameter from lines of text — each line is coerced like one CLI token, solist[int]andlist[Path]work as they would as repeated flags.
Precedence is CLI > stdin > env > default > prompt, so an explicit
option always wins and one signature serves both fm process file.txt
and cat file.txt | fm process. The stream is read once, fully, at the
boundary — never inside a task body, so the parallel-stdin guard is
never in play — and the same payload serves every parameter that asks.
A terminal on stdin means "not provided": the parameter falls back to
its default, and a required parameter refuses with a taught message
rather than blocking on a read.
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
field |
str | None
|
|
lines |
bool
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.Stdout
module-attribute
¶
Shorthand for Annotated[T, stdout] on a return annotation:
Stdout[dict | None] is the house spelling for a filter that sometimes
has nothing to say (marker outermost, like NoSplit[list[X] | None]);
Stdout[dict] | None means the same thing. See stdout.
livery.footman.stdout
module-attribute
¶
stdout: Final[StdoutMarker] = StdoutMarker()
Declare that a task's return value is the document on stdout, via the return annotation:
The task is then a Unix filter by declaration — no flag at any call site.
The return type decides the bytes, mirroring stdin: Stdout[str] emits
the string verbatim (plus a trailing newline), Stdout[bytes] writes raw
bytes, anything structured is JSON — pretty-printed on a terminal, one
compact line into a pipe, dataclasses and Secret redaction handled by
the same encoder --json uses — so a Secret inside a structured document
serialises as ***, and a task that means to emit one says
token.reveal(). A Stdout[str] built by formatting is unaffected: string
operations on a Secret yield a plain str, which is how the
print-a-credential filter (eval "$(fm env-export)") works without a
switch to disarm redaction everywhere else.
The rules that keep it honest: an explicit --json wins (the document
rides inside results[].returned); only the addressed task emits (a
declaring task reached as a pre=/post= dependency or a fan-out member
is suppressed, not refused); two declaring tasks in one chain is a
plan-time refusal; None means empty stdout, exit 0; a failed task emits
nothing; everything that is not the document — prints, run() output —
replays on stderr. A bare -> int stays the exit-code channel; declaring
Stdout[int] makes the int the document instead. A body call is
unaffected: status() from another task just returns the value.
The working directory & lanes¶
livery.footman.cwd ¶
cwd() -> Path
The current task's working directory, always concrete.
ctx.cwd as the policy ladder resolved it — the blessed base for a task
body's own path arithmetic (footman.cwd() / "dist"), instead of
relative paths against the process cwd, which belongs to no one in a
parallel run. Outside a run it is simply the process cwd.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.chdir ¶
Really change the process directory — inside a serial/exclusive task.
The sugar for bodies that own the globals: the default target is the
task's own ctx.cwd; arguments follow the marker grammar exactly — a
policy token (root, taskfile, asinvoked) or an absolute path, with
rel= for a relative suffix; a bare relative path is the same taught
error the markers give. Performs a real os.chdir, keeps ctx.cwd in
sync (so a nested run() roots where the block does), restores both on
exit. In a parallel task it is a taught error — the cwd belongs to no
one there.
Source code in packages/footman/src/livery/footman/_context.py
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 | |
livery.footman.Lane ¶
A serialised claim on one named resource: one holder at a time,
contending only with claimants of the SAME lane — unrelated work runs
untouched (nothing drains; that is exclusive=, a different regime).
Made by footman.lane() and claimed by handing the handle to a task's
or a step maker's lanes=: the import system is the registry, so a
misspelt lane is an undefined name, and sharing a resource across
modules is importing its binding. footman itself ships exactly two —
cwd_lane and console_lane — built with the same call.
Methods:
| Name | Description |
|---|---|
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
name |
str
|
The resource's one name — what the live line shows a wait on. |
reason |
str | None
|
Optional documentation on the declaration. |
Source code in packages/footman/src/livery/footman/_globals.py
livery.footman.lane ¶
Declare a named resource to serialise on. One binding per resource: re-declaring a taken name is a refusal naming both sites — reuse is spelled by importing the handle, never by re-declaring. (The same site re-executing — a module re-imported — is the same declaration.)
Source code in packages/footman/src/livery/footman/_globals.py
livery.footman.cwd_lane
module-attribute
¶
livery.footman.console_lane
module-attribute
¶
Where a task keeps things¶
Two folders footman writes, both created on access. cache_dir() is derived data the collector sweeps by age; data_dir() is durable and machine-local — credentials, tokens, generated assets — and is never collected. The rest are places footman reads, created by nobody but you: config_dir() and config_file() are your user-level settings, user_tasks_file() the personal rung riding every project, and project_root() the top of this invocation's cascade (None outside a project). fm self.path is the same set from the command line. Where each one lands is the CLI's business, not the task's; see Custom CLIs.
livery.footman.cache_dir ¶
cache_dir() -> Path
This CLI's cache directory, created if it isn't there yet.
Derived data, safe to delete: footman's collector sweeps this folder by age, so put nothing here you would mind losing.
Where it lands is the branded CLI's business — its own folder, or
~/.cache/<name> by default. A task asks for the kind of folder it
wants and gets one that exists.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.scratch_dir ¶
A fresh directory for this process's scratch, swept once the process is gone.
Under cache_dir(), in scratch/, named <label>-<pid>-<random>:
the owner's pid is in the name, so footman's collector can tell a
directory a killed or replaced process left from one still in use.
Remove it yourself when the work ends; what an exit without handlers
leaves, a kill or an exec, goes when the collector next runs and finds
the owner's pid gone, in the daily child or fm janitor. A pid the
operating system has given to a new process keeps the directory until
that process ends too.
scratch = footman.scratch_dir("replay")
try:
build(scratch)
finally:
shutil.rmtree(scratch, ignore_errors=True)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label
|
str
|
What the directory is for: letters, digits, dots, hyphens and underscores. It names the directory for a reader of the cache; the collector reads only the pid after it. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
when label is empty or carries another character. |
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.alive ¶
Whether a process with pid exists.
The one probe for every pid a task or a plugin writes down: a daemon's
pid file, a scratch directory's owner, a lock's holder. A pid of zero
or less is nobody's. On POSIX a signal of zero asks without sending,
and a process that refuses the asking exists. On Windows the kernel is
asked for a handle, since os.kill there ends the process for any
signal it does not special-case, and a handle whose exit code is set
is a process that ended and is not yet reaped.
Source code in packages/footman/src/livery/footman/_gc.py
livery.footman.data_dir ¶
data_dir() -> Path
This CLI's data directory, created if it isn't there yet.
Durable and machine-local — credentials, tokens, generated assets. The
collector never touches it, which is the whole difference from
cache_dir(). Created owner-only (0o700), like ~/.ssh, because
credentials are exactly what it is documented to hold.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.config_dir ¶
config_dir() -> Path
This CLI's config directory — your writing, never footman's.
The user-level config file and the user-level tasks file live here and
travel together. Unlike cache_dir() and data_dir() this one is
not created on demand: an empty config directory says something
different from a missing one, and inventing it would be footman
writing where only you should.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.config_file ¶
config_file() -> Path
The user-level config file — ~/.config/<brand>/config.toml by
default. May not exist; a runner with no config is the ordinary case.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.user_tasks_file ¶
user_tasks_file() -> Path
The user-level tasks file: the cascade's outermost writable rung, riding every project. May not exist.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.project_root ¶
project_root() -> Path | None
The top of this invocation's task cascade, or None outside a
project.
The same answer --json reports and the root cwd policy resolves
against — never a guess from the current directory, which may be
anywhere beneath it.
Source code in packages/footman/src/livery/footman/_context.py
Which CLI is running¶
For output that has to call the CLI back — a generated CI workflow, a README line — so a branded runner emits its own name instead of fm. prog() is the command someone types, dist() the package that ships it (None when the brand never declared one). Inside a task body ctx.prog says the same and is the better reach: it is the invocation's own answer rather than process state.
livery.footman.prog ¶
prog() -> str
The command this CLI is invoked as — fm, or a branded CLI's own.
For output that has to call the CLI back: a generated CI workflow, a README line, a task that writes prose naming the command someone will type. A branded runner must emit its own name, or the file it writes tells the reader to run a command they do not have.
Inside a task body, prefer ctx.prog — declare a ctx: Context
parameter and read it. That is the invocation's own answer rather than
process state, and it is what footman's own taskdocs plugin uses. This
accessor exists for the code that never receives a context: a plugin
building its tree at mount time, a helper called from anywhere.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.dist ¶
dist() -> str | None
The distribution that ships this CLI, or None if it never said.
The name someone would pip install — what the uv handoffs reason
about, and what self.install puts on a PATH. App(dist=…) sets it;
stock footman answers "footman".
None is a real answer, not a gap: declaring a distribution is opt-in
for a branded CLI, and saying "footman" for a brand that never
declared one would name the wrong package.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.builtins ¶
The plugin families this footman mounts in every project, by entry point name.
A branded app declares them (App(builtin=…)); stock footman declares
none.
Source code in packages/footman/src/livery/footman/_paths.py
livery.footman.directory_variable ¶
The environment variable a footman directory is read from.
directory_variable("DATA_DIR") is FOOTMAN_DATA_DIR for stock footman
and ACME_DATA_DIR for a brand whose prefix is ACME.
Source code in packages/footman/src/livery/footman/_paths.py
livery.footman.tasks_file_name ¶
tasks_file_name() -> str
The brand's tasks filename, as configure/configure_child set it.
The refresh child reads it here: child_args hands the resolved value
over on spawn, so a branded default IS knowable in the child — the old
peek at the cached manifest's baked tasks_file predated that handoff.
Source code in packages/footman/src/livery/footman/_paths.py
Fetching¶
livery.footman.fetch ¶
fetch(url: str, *, into: Path | str | None = None, sha256: str = '', backend: str = '', refresh: bool = False) -> Path
Download url (cached), returning the path to the local file.
A second call for the same URL revalidates with the server (ETag /
Last-Modified) rather than re-downloading; a 304 Not Modified
costs one round trip and keeps "cached" honest. Pass refresh to
skip revalidation and fetch unconditionally.
@task
def deps():
"Fetch the toolchain."
archive = fetch(TOOLCHAIN_URL, sha256="9f86d0…")
run(["tar", "-xzf", archive, "-C", "vendor"])
into copies the cached file to a path of your choosing (and returns that path). sha256 verifies what arrived and refuses a mismatch — the way to make a build reproducible. backend overrides the configured one for this call.
Under --dry-run nothing is downloaded: the step is recorded and
the would-be cache path returned, so a plan can be inspected safely.
Source code in packages/footman/src/livery/footman/_fetch.py
342 343 344 345 346 347 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 431 432 433 434 435 436 437 438 439 440 441 | |
livery.footman.FetchError ¶
Bases: Exception
A download failed, or arrived wrong (checksum, missing backend).
The task context¶
given() answers whether the caller supplied a parameter or footman filled it in — the difference between asking for the default and having no opinion, which the value alone cannot tell you.
livery.footman.Context
dataclass
¶
Context(address: str = '', _labels: dict[str, int] = dict(), notes: list[Any] = list(), env: dict[str, str] = (lambda: base_env())(), cwd: Path | None = None, cwd_policy: str = '', root_dir: str = '', invoked_dir: str = '', cwd_unmanaged: bool = False, serial_active: bool = False, dry_run: bool = False, quiet: bool = False, verbose: bool = False, no_color: bool = False, force_color: bool = False, machine_read: bool = False, prog: str = 'fm', sequential: bool = False, assume_yes: bool = False, no_input: bool = False, fetch_backend: str = '', shell_default: str = '', jobs: int = 0, task: str = '', fn: Any = None, given: frozenset[str] = frozenset(), name_width: int = 0, passthrough: list[str] = list(), tty: bool = False, terminal: bool = False, sink: TextIO | None = None, err_sink: TextIO | None = None, interactive: bool = False, atomic: bool = False, keep_going: bool = False, deadline: float | None = None, timeout_declared: float | None = None, shared: bool = True, in_task: bool = False, unit_pending: bool = False, answers: Any = None, steps: list[Result] = list(), sections: list[Section] = list())
State for one running task: environment, flags, passthrough, output.
Methods:
| Name | Description |
|---|---|
time_left |
Seconds until this task's deadline, or |
overdue |
Has this task's deadline passed? False when there is no deadline. |
child |
One birth for every child context — a body callee's, a |
Attributes:
| Name | Type | Description |
|---|---|---|
address |
str
|
This context's place in the run's tree — the path of requests that |
notes |
list[Any]
|
The notes this task fired ( |
env |
dict[str, str]
|
This task's environment — a complete one, not a diff. |
cwd |
Path | None
|
Where |
cwd_policy |
str
|
|
root_dir |
str
|
The |
invoked_dir |
str
|
The |
cwd_unmanaged |
bool
|
|
serial_active |
bool
|
This task holds (or inherited, through a fan-out) the serial or |
dry_run |
bool
|
|
quiet |
bool
|
|
verbose |
bool
|
|
no_color |
bool
|
|
force_color |
bool
|
|
machine_read |
bool
|
|
prog |
str
|
The invoking CLI's command name — a branded CLI's own |
sequential |
bool
|
The user asked for one-at-a-time ( |
assume_yes |
bool
|
|
no_input |
bool
|
|
fetch_backend |
str
|
|
shell_default |
str
|
|
jobs |
int
|
The effective parallel width ( |
task |
str
|
Who is running, for the step lines' name column: the scheduler |
fn |
Any
|
The running task's own function — what |
given |
frozenset[str]
|
The parameter names the caller supplied — named on the command line, |
name_width |
int
|
The widest sibling task name, so step-line columns align. |
passthrough |
list[str]
|
Everything after |
tty |
bool
|
Output dresses for a terminal (colour, marks). Live in-place |
terminal |
bool
|
The run's real stdout is a terminal (on Windows, one that interprets |
sink |
TextIO | None
|
Where this task's stdout goes: a capture buffer in buffered |
err_sink |
TextIO | None
|
Where this task's stderr goes. At task level it is the same buffer as |
interactive |
bool
|
|
atomic |
bool
|
|
keep_going |
bool
|
This task's resolved (per-subtree) failure policy, tagged onto the |
deadline |
float | None
|
|
timeout_declared |
float | None
|
The seconds the author wrote in |
shared |
bool
|
Whether an execution the run has already performed may satisfy this |
in_task |
bool
|
True while a task body runs (the scheduler sets it around the call), |
unit_pending |
bool
|
A live-progress unit is already counted for this call, and unclaimed: |
answers |
Any
|
The scripted answers a |
steps |
list[Result]
|
Every |
sections |
list[Section]
|
Task-authored profiling: what |
address
class-attribute
instance-attribute
¶
address: str = ''
This context's place in the run's tree — the path of requests that led here. Every record made under it derives its own address from this one.
notes
class-attribute
instance-attribute
¶
The notes this task fired (_notes.Note records) — what the level
system resolved, where each came from, and what the boundary verdict
and the --json envelope read. A task's own, never inherited.
env
class-attribute
instance-attribute
¶
This task's environment — a complete one, not a diff.
Starts as a copy of the run's pinned environment, and is what os.environ
answers from inside the task, what every child footman spawns receives,
and what run(env=…) replaces. Because it is a whole value rather than an
overlay, del os.environ["FOO"] is ordinary: it removes the key from this
task's environment and from the children it goes on to spawn, while a
sibling's copy is untouched.
cwd
class-attribute
instance-attribute
¶
cwd: Path | None = None
Where run() executes — resolved once per task by the policy ladder
(.opts(cwd=) / @task(cwd=) / config cwd, default taskfile), so it
is concrete inside a run. A preset value (tests, use_context) wins.
None means unresolved (plain calls outside a footman run).
cwd_policy
class-attribute
instance-attribute
¶
cwd_policy: str = ''
[tool.footman] cwd — the run-wide default policy token (or absolute
path) the ladder bottoms out on. Empty means taskfile.
root_dir
class-attribute
instance-attribute
¶
root_dir: str = ''
The root token's target: the highest cascade task file's directory
(files[0].parent), pinned by discovery. Empty outside a real run.
invoked_dir
class-attribute
instance-attribute
¶
invoked_dir: str = ''
The asinvoked token's target: the process cwd where fm was
launched, pinned as a snapshot at startup.
cwd_unmanaged
class-attribute
instance-attribute
¶
cwd_unmanaged: bool = False
cwd="unmanaged": footman stays out — subprocesses spawn with
cwd=None (inherit the live process cwd) even though ctx.cwd records
the process cwd at task start for the body to read.
serial_active
class-attribute
instance-attribute
¶
serial_active: bool = False
This task holds (or inherited, through a fan-out) the serial or
exclusive lane: it owns the real process globals — the environ router,
the Popen injection, and the os guards all pass through. Set by the
executor around a serial=/exclusive= body; parallel() children
inherit it, because a lineage extends a hold.
dry_run
class-attribute
instance-attribute
¶
dry_run: bool = False
--dry-run: run() prints and records the command, executes
nothing, and reports success.
quiet
class-attribute
instance-attribute
¶
quiet: bool = False
--quiet: suppress step lines and the per-task summary.
verbose
class-attribute
instance-attribute
¶
verbose: bool = False
--verbose: replay captured run() output even on success.
no_color
class-attribute
instance-attribute
¶
no_color: bool = False
--no-color / --color=never (or NO_COLOR): never emit ANSI styling.
force_color
class-attribute
instance-attribute
¶
force_color: bool = False
--color=always (or FORCE_COLOR): colour even when output is not a
terminal — so run() forces the tools it spawns to colour and the shown
command line paints, for a pipe into less -R. Gated off under capture
(--json), where ANSI would corrupt the envelope. Never sets the live
cursor affordances tty governs — those still need a real terminal.
machine_read
class-attribute
instance-attribute
¶
machine_read: bool = False
--json: the envelope is the report. footman's own receipt chrome —
the step line, the replayed output block, the audit trail — is left out
of the buffer, because every one of those already has a field on the
step's own row. Task output still lands there: a body's prints are
what the buffer is for.
prog
class-attribute
instance-attribute
¶
prog: str = 'fm'
The invoking CLI's command name — a branded CLI's own prog, so
tasks (the taskdocs plugin, say) can speak the brand's name.
sequential
class-attribute
instance-attribute
¶
sequential: bool = False
The user asked for one-at-a-time (-s or config) — parallel()
honours it too. Deliberately not set by the scheduler's own
single-node routing, which is presentation, not a request to
serialise task bodies.
assume_yes
class-attribute
instance-attribute
¶
assume_yes: bool = False
--yes: every confirm() gate auto-answers yes, for CI and scripts.
no_input
class-attribute
instance-attribute
¶
no_input: bool = False
--no-input: never prompt — a required prompt errors instead of
asking, so an unattended run fails loudly rather than hanging.
fetch_backend
class-attribute
instance-attribute
¶
fetch_backend: str = ''
[fetch] backend from the config ladder — which engine fetch()
downloads with. Empty means the default (stdlib urllib).
shell_default
class-attribute
instance-attribute
¶
shell_default: str = ''
[shell] default from the config ladder — what run(shell=True) resolves
to. Empty means posix (a POSIX shell everywhere: bash, then sh).
jobs
class-attribute
instance-attribute
¶
jobs: int = 0
The effective parallel width (-j/--jobs, config jobs, or the
cores-minus-one default) — caps parallel() pools in task bodies.
0 means unset (plain calls outside a run): no cap.
task
class-attribute
instance-attribute
¶
task: str = ''
Who is running, for the step lines' name column: the scheduler
sets the dotted task name, parallel() its child's name. Empty
outside runs.
fn
class-attribute
instance-attribute
¶
fn: Any = None
The running task's own function — what inherited() reads to find
the task this one shadows. None outside a run.
given
class-attribute
instance-attribute
¶
The parameter names the caller supplied — named on the command line,
passed as a keyword by a body call, or answered at an ask() prompt. What
the given() function reads.
Its complement is everything footman inferred rather than was told: an
env() fallback, a default(fn), the declared default. That split is the
whole point — a value and the fact that someone asked for it are two
different things, and only the second can distinguish --profile (write
the default file) from no --profile at all (write nothing).
Empty outside a run, and never inherited: a child task's set is its own, stamped where its context is built.
name_width
class-attribute
instance-attribute
¶
name_width: int = 0
The widest sibling task name, so step-line columns align.
passthrough
class-attribute
instance-attribute
¶
Everything after -- on the command line, verbatim.
tty
class-attribute
instance-attribute
¶
tty: bool = False
Output dresses for a terminal (colour, marks). Live in-place rewrites additionally require output to be uncaptured.
terminal
class-attribute
instance-attribute
¶
terminal: bool = False
The run's real stdout is a terminal (on Windows, one that interprets
ANSI) and output is not captured into a --json envelope — tty with
the colour policy left out. What the tty() reader answers: NO_COLOR
turns tty off because dressed output would be wrong, but the person
is still there.
sink
class-attribute
instance-attribute
¶
sink: TextIO | None = None
Where this task's stdout goes: a capture buffer in buffered
(parallel) mode, None for the real stdout (live mode).
err_sink
class-attribute
instance-attribute
¶
err_sink: TextIO | None = None
Where this task's stderr goes. At task level it is the same buffer as
sink (so the atomic parallel flush keeps stdout/stderr in order); a
run() capturing an in-process callable temporarily points the two at
separate buffers to split the step's streams for its Result.
interactive
class-attribute
instance-attribute
¶
interactive: bool = False
@task(interactive=True): the task owns the real terminal — output is
not captured and it holds sole stdio, so its body may prompt or run a
REPL. Mid-body prompt()/confirm()/select() are allowed only here.
atomic
class-attribute
instance-attribute
¶
atomic: bool = False
@task(atomic=True): this task's subprocesses opt out of fail-fast's
kill — they run to completion so a mid-write can't be truncated. Total
on purpose: the child is unregistered and not group-isolated, so a stop
signal to footman's own pid (timeout, docker stop) ends the run and
leaves the child to finish; a terminal's Ctrl-C reaches it only because
the kernel signals the whole foreground group itself.
keep_going
class-attribute
instance-attribute
¶
keep_going: bool = False
This task's resolved (per-subtree) failure policy, tagged onto the subprocesses it spawns so a fail-fast failure elsewhere reaps only the fail-fast trees in a mixed run, sparing a keep-going task's.
deadline
class-attribute
instance-attribute
¶
deadline: float | None = None
@task(timeout=…), resolved to a time.perf_counter() instant when
the body starts — an instant rather than a duration because everything
downstream asks "how long is left?", and a duration would have to be
re-based at each hand-off.
It is the fail-fast event scoped to one task: past it, no new work
starts, in-flight subprocess trees are terminated, and generator steps
unwind at their next checkpoint. Inherited by the steps and run()
calls a body makes, so a subprocess is bounded by whatever the task has
left rather than by its own timeout alone.
timeout_declared
class-attribute
instance-attribute
¶
timeout_declared: float | None = None
The seconds the author wrote in @task(timeout=…), kept beside the
resolved deadline so a failure line can name the declared number
rather than the remainder that happened to be left when a call
started.
shared
class-attribute
instance-attribute
¶
shared: bool = True
Whether an execution the run has already performed may satisfy this
request. False means it gets its own run, and so does everything it asks
for, unless that task declares its own answer. Resolved per node by the
scheduler and per call by the cell layer — the sharing twin of
keep_going's per-subtree policy.
in_task
class-attribute
instance-attribute
¶
in_task: bool = False
True while a task body runs (the scheduler sets it around the call),
so the interactive primitives tell a guarded mid-body call from the
framework's own up-front ask() resolution.
unit_pending
class-attribute
instance-attribute
¶
unit_pending: bool = False
A live-progress unit is already counted for this call, and unclaimed:
parallel() counts every child it is handed, then the first task request
inside that child claims the unit instead of counting a second one. A
thunk that runs no task keeps it; a thunk that is only a wrapper around
one call (the lambda: build("web") spelling) shows as the single piece
of work it is. Cleared on claim, so the requests after it — and anything
the callee itself asks for — count their own.
answers
class-attribute
instance-attribute
¶
answers: Any = None
The scripted answers a recording(answers=…) block carries — the
normalised table, shared by reference with every child context so an
ordered sequence is consumed in one place. None outside a scripted
recording; a raw mapping handed to Context(answers=…) is normalised
on first use.
steps
class-attribute
instance-attribute
¶
Every run() this task made, in order — what recording() and
the --json envelope read.
sections
class-attribute
instance-attribute
¶
Task-authored profiling: what section(), stream() and mark()
recorded while this task ran, on the run's clock. Rides the task's
result row; a parallel() child's records fold into its requester's,
the way steps do.
time_left ¶
time_left() -> float | None
Seconds until this task's deadline, or None when it has none.
Clamped at zero rather than going negative: callers hand it to
subprocess.communicate(timeout=…) and to their own comparisons,
and a negative bound reads as "no bound" to some of them. Zero means
the deadline has passed and the caller should not start the work.
Source code in packages/footman/src/livery/footman/_context.py
child ¶
One birth for every child context — a body callee's, a
parallel() child's — so the sites can never drift on which fields
reset.
Identity is fresh: the address and sibling labels, the step and
section records, the unit flag. The environment is a COPY — a
child's writes are its own, which is the router's "children see it,
siblings don't" made structural. Everything else inherits until
overrides says otherwise. given deliberately inherits here: the
futures layer stamps the callee's own set where binding computes
it, and a step child has no binding to compute one.
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.current ¶
current() -> Context
The context of the running task (a fresh default one outside a run).
livery.footman.given ¶
Whether the caller supplied name, as opposed to footman inferring it.
@task
def build(*, profile: Path = Path("build-profile.json")):
if given("profile"): # `fm build --profile` writes the default file;
trace_to(profile) # `fm build` writes nothing at all
True when the parameter was named on the command line (with or without a
value — --profile alone means its default, and means it on purpose),
passed as a keyword by a body call, or answered at an ask() prompt. False
when the value came from an env() fallback, a default(fn), or the
declared default, because nobody asked for those.
That distinction is the only way to tell "the default one, please" from "no opinion", which a value alone cannot express: both hand you the same path.
name is the parameter name, not its flag spelling — dry_run, not
--dry-run. Naming something the running task has no parameter for is an
error rather than a silent False, since a typo would otherwise read as a
perfectly ordinary "not given".
Source code in packages/footman/src/livery/footman/_context.py
livery.footman.use_context ¶
Install ctx as the current run context for the duration of the block.
The public seam for calling tasks from other Python code — tests included:
run() and hosted toolroom calls inside the block read this context
instead of a fresh default. footman.testing.recording builds on it.
Source code in packages/footman/src/livery/footman/_context.py
Composing tasks¶
livery.footman.include ¶
include(source: str | ModuleType | Group, /, *, into: str | Group | None = None, only: tuple[str, ...] | list[str] = (), exclude: tuple[str, ...] | list[str] = (), override: bool = False) -> Group
Mount a task tree from an importable module — modules only; for an
installed package's advertised tasks use plugin().
include("shared_tasks") # everything, at root
include("shared_tasks", only=["lint"]) # cherry-pick a child
include("mytasks.lint") # one group out of a module
include("mkdocs_helpers.tasks", into="docs") # namespaced: fm docs.…
The longest importable prefix is imported under a registry capture (the
provider's decorators can't leak into your tree); the rest of the string
walks the captured tree. Collisions are loud (RegistrationError)
unless override=True; your own definitions silently win. Included
tasks run from your file's directory — a shared lint task lints this
project. A Group or imported module may be passed programmatically
(tests, generated trees). Returns the group grafted into.
Source code in packages/footman/src/livery/footman/_compose.py
livery.footman.plugin ¶
plugin(source: str, /, *, into: str | Group | None = None, only: tuple[str, ...] | list[str] = (), exclude: tuple[str, ...] | list[str] = (), override: bool = False) -> Group
Mount a task tree from an installed package's footman.tasks entry
point — entry points only; for your own modules use include().
plugin("acme.devkit") # the import *: every group, top level
plugin("acme.devkit.lint") # from acme_devkit import lint
plugin("acme.ci", exclude=["deploy"]) # everything but one child
plugin("footman.docs", into="footman") # built-ins are ordinary plugins
plugin("acme.linters.default", into="lint") # adopt a provider's default
The longest installed entry-point name is the identity (consumed at
resolve time, retained as provenance); the rest of the string walks the
advertised tree. The mounted node lands under its own name — into=
(a dotted address, created on demand) is the consumer's placement, and
there is no rename. Returns the group grafted into.
Source code in packages/footman/src/livery/footman/_compose.py
livery.footman.capture ¶
Redirect module-level @task/group registration into a fresh tree.
The seam include() uses to import a provider module without letting its
decorators land in the current registry: root.tasks/root.groups are
swapped for fresh dicts for the duration and the captured tree is yielded.
Reentrant — a provider may itself include() another provider.
Source code in packages/footman/src/livery/footman/_registry.py
Installed entry points¶
One scan of every installed distribution per process, shared by footman's plugin loader and anything built on footman.
livery.footman.installed_entry_points ¶
installed_entry_points(group: str | None = None) -> tuple[EntryPoint, ...]
The installed entry points of group, or of every group when None.
The first call scans every installed distribution; every later call in the process answers from that scan. A process that installs a distribution and must see it calls livery.footman.rescan_entry_points first.
Source code in packages/footman/src/livery/footman/_entries.py
livery.footman.rescan_entry_points ¶
livery.footman.project_builtins ¶
The plugin families root's own dependencies offer, by entry point name.
The footman.builtin names of the distributions root's
pyproject.toml depends on directly, in its [project]
dependencies and its [dependency-groups]; a dependency of a
dependency offers nothing.
Source code in packages/footman/src/livery/footman/_config.py
Shell completion¶
Completion answers from a manifest cached per directory. A program that changes which tasks a directory offers, by installing a distribution that brings new ones, calls refresh_completion to start the rebuild of that directory's manifest, so the next Tab there offers them. See Shell completion.
livery.footman.refresh_completion ¶
Start the detached rebuild of directory's completion manifest and return.
A program that has just changed which tasks directory offers calls this,
for example after it installed a distribution that brings new tasks.
Without it, the next Tab there answers from the manifest the last
run wrote, until another run there or until the manifest is older than
completion.max-age. The rebuild is the one a stale manifest starts after a
Tab press: the same detached child, run in directory, builds
the tree a run there serves, in this CLI's own cache.
Starts nothing when no person is there to press Tab, as in CI
or a run without a terminal: livery.footman.attended answers, and it
knows --no-input and --dry-run too. Nobody completes there, and on
Windows a detached child can hold files of the environment open while a
later step replaces them. Starts nothing when the configuration that
applies in directory sets completion.max-age to off, which asks for
no background rebuilds, and nothing when that configuration cannot be
read. Prints nothing and never raises: when the child cannot start,
nothing starts, and the caller's own outcome stands.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str | Path
|
The directory whose manifest to rebuild. A manifest is keyed by the directory a person presses Tab in. |
required |
Source code in packages/footman/src/livery/footman/_refresh.py
Libraries that run tools¶
A library that runs tools, toolroom among them, asks host() for the run it is called in, and gets None outside one, so it keeps its standalone behaviour there. It hands run(view=…) a CommandView, so the command line a run shows is the readable one while the call runs whatever the tool needs.
livery.footman.host ¶
host() -> Host | None
The footman run this call is made in; None when no run is in flight.
One is answered while footman's routers are installed or a task's context is current. A library that only imports footman, outside any run, gets None and keeps its standalone behaviour.
Source code in packages/footman/src/livery/footman/_host.py
livery.footman.Host ¶
The footman run a call is made in, as a tool wrapper asks of it.
A run is in flight when footman's routers are installed
(active), and a task is running when a task's context is current
(in_task); either makes livery.footman.host answer one.
Methods:
| Name | Description |
|---|---|
real_cwd |
The process's own working directory, which a parallel task never moves. |
target_cwd |
The directory a call runs in: cwd or the task's, relative under it. |
argv_override |
A block in which this thread alone sees args as |
Attributes:
| Name | Type | Description |
|---|---|---|
active |
bool
|
Whether footman's routers are installed: a run is in flight. |
in_task |
bool
|
Whether a task's context is current: a call joins its directory. |
real_cwd ¶
real_cwd() -> str
The process's own working directory, which a parallel task never moves.
target_cwd ¶
The directory a call runs in: cwd or the task's, relative under it.
None when the task runs unmanaged, or for cwd="unmanaged": the
call then inherits the process's directory.
Raises:
| Type | Description |
|---|---|
ValueError
|
when relative is absolute, or is given with
|
Source code in packages/footman/src/livery/footman/_host.py
argv_override ¶
argv_override(args: list[str]) -> AbstractContextManager[None]
A block in which this thread alone sees args as sys.argv.
A wrapper runs a tool's zero-argument main() in-process inside
one, so parallel calls do not share one sys.argv.
Source code in packages/footman/src/livery/footman/_host.py
livery.footman.CommandView
dataclass
¶
What a run() call is, apart from how it's spelled to execute.
A tool wrapper, toolroom's bridge among them, hands one to run(view=…)
so the run shows a readable, syntax-highlighted command line — options
in separated form, tagged by role — while executing whatever the tool
actually needs (attached flags, or an in-process callable). parts is
the normalised, human form, each a role and its text; exact is the
literal argv, shown under --verbose and always copy-pasteable.
Passing it is how the two are kept from drifting: both come from one
translation of one call.
Attributes:
| Name | Type | Description |
|---|---|---|
parts |
tuple[tuple[str, str], ...]
|
The command line's normalised form, each part a role and its text. |
exact |
tuple[str, ...]
|
The literal argv the call runs. |
Methods:
| Name | Description |
|---|---|
text |
The plain command line — the width-measured, non-colour form. |
painted |
The shown command line, role-coloured when the stream wants it. |
text ¶
The plain command line — the width-measured, non-colour form.
Source code in packages/footman/src/livery/footman/_context.py
painted ¶
The shown command line, role-coloured when the stream wants it.
Source code in packages/footman/src/livery/footman/_context.py
The invocation, and editing the discovered tree¶
@pre_tasks runs a hook once per invocation, over the fully-merged cascade and before anything else — see Hooks & plugin options. It is handed the Invocation, whose tasks is a Tasks view; iterating or indexing that yields a TaskView that reads and edits one task. The per-task pair — @pre_task and @post_task — runs around every execution; see Around every task.
livery.footman.handing_off ¶
Hand this run's state to the process about to replace it.
A verb that re-runs its own command line in a new process wraps the
replacing in this, and hands what it yields to execve or to
subprocess.run(env=…) where there is no exec:
with footman.handing_off() as handed:
os.execve(exe, cmd, {**os.environ, **handed})
Every pre_reexec hook the run mounted is entered, and what they yield
is merged into one mapping of environment entries for the successor.
Nothing mounted, or nothing with state to carry, yields an empty mapping
and costs one attribute read.
The block ends by not returning, so returning normally means the replacement did not happen: every hook is then closed the ordinary way and takes its own state back. An exception means the replacement happened — a handoff that waits for its child exits with its code — and the hooks see it, so what they wrote down stands.
A hook that raises on the way in is named on stderr and skipped. A plugin's bookkeeping never stops a repair that was already under way.
Source code in packages/footman/src/livery/footman/_executor.py
livery.footman.GlobalOption ¶
GlobalOption(name: str, annotation: Any = bool, *, default: Any = None, config: bool | str = False, help: str = '')
A plugin's own global option — --env-file=PATH beside --jobs=N.
Constructing one is registering it: a module-level singleton in the
provider, stamped with the module that defined it, riding the same
carriage as lifecycle hooks — so it reaches a run only when its owner is
mounted, and an unmounted owner's option is an unknown option, taught.
Long-form only, and the value is =-attached like every option's.
ENV_FILE = GlobalOption("env-file", Path, help="load this .env file")
A bool annotation makes it a flag; anything else takes a value, coerced
and validated through the same pipeline as a task parameter — Literal
choices, Path file completion, Annotated[..., suggest(...)] all work,
because the manifest describes it with the same machinery. Read it
anywhere in-run as OPT.value (frozen after parse); cross-plugin use is
an ordinary import of the singleton.
A mention with no value is legal — --profile beside --profile=out.json
— and carries presence rather than a value: .value is then whatever the
option would have had anyway, and .given says someone asked. That is what
lets one declared value cover three outcomes (off, the default file, a named
file) where a second declared value used to be needed.
config=True gives the option a project-config rung — the one ladder,
CLI > env() > config > default(fn) > declared — reading the key
named like the option from this provider's own section under the brand
table's reserved plugins. child: [tool.footman.plugins.acme-devkit]
for the acme.devkit entry point (the dot becomes a hyphen, because
TOML's dot is its nesting operator). config="key" names the key
instead, for a flag renamed around a collision — flag and key are
different namespaces, and only the flag's is shared. The section is the
entry point's, de-dotted; footman.config_section("...") names it
explicitly where there is nothing to derive from (an include()d
module) or the derivation reads wrong.
Methods:
| Name | Description |
|---|---|
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
name |
str
|
|
annotation |
Any
|
|
default |
Any
|
|
config |
bool | str
|
|
help |
str
|
|
owner |
str
|
|
value |
Any
|
The parsed value for this run — the flag's presence, the option's |
given |
bool
|
Whether this option was named on the command line, with or without a |
Source code in packages/footman/src/livery/footman/_registry.py
__slots__
class-attribute
instance-attribute
¶
__slots__ = ('_frozen', '_given', '_mounted', '_reads', '_section', '_value', 'annotation', 'config', 'default', 'help', 'name', 'owner')
value
property
¶
value: Any
The parsed value for this run — the flag's presence, the option's coerced value, or the default when the line didn't carry it. Frozen after parse; reading it outside a run is a taught error, because there is no invocation to have carried it.
given
property
¶
given: bool
Whether this option was named on the command line, with or without a
value — the twin of value, and the half a value cannot express.
PROFILE = GlobalOption("profile", Path, default=Path("fm-profile.json"))
if PROFILE.given: # `--profile` writes the default file,
write_trace(PROFILE.value) # no `--profile` writes nothing
Three outcomes from one declared value: absent, named, named with a
value. value answers what, given answers whether anyone asked —
and an env fallback fills the first without ever touching the second,
so a caller who wants the environment alone to count can say so, and one
who does not can say that instead.
livery.footman.config_section ¶
config_section(name: str) -> None
Name this provider module's config section — the <name> of
[tool.footman.plugins.<name>] — instead of the entry-point derivation.
Module-level, beside the module's GlobalOptions. For an include()d
module (no entry point to derive from), or a derivation that reads
wrong or ugly. The name is claimed at discovery, so two providers
naming one section refuse loudly, never resolve by order.
Source code in packages/footman/src/livery/footman/_registry.py
livery.footman.Invocation ¶
Invocation(*, cli: dict[str, Any] | None = None, config: dict[str, Any] | None = None, root: str = '', cwd: str = '', tasks: Tasks | None = None, docs_url: str | None = None)
What one fm line is doing, handed to every lifecycle hook.
Editable only at pre_tasks; every later moment sees the same object with
writes refused, so what a task-time hook reads is what the run decided.
Methods:
| Name | Description |
|---|---|
freeze |
Close the invocation for writes — called once, before tasks run. |
__setattr__ |
|
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
cli |
dict[str, Any]
|
The global options this line carried. Empty in the manifest refresh |
config |
dict[str, Any]
|
The merged |
root |
str
|
The cascade root: the directory of the highest |
cwd |
str
|
Where |
tasks |
Tasks | None
|
The merged command tree, as a |
docs_url |
str | None
|
The URL template task names link to, or None for no links. |
results |
tuple[Any, ...]
|
The run's rows, in the order the work was created, as result |
skipped |
tuple[Any, ...]
|
The |
total_ms |
float
|
Wall-clock for the whole run, the envelope's |
Source code in packages/footman/src/livery/footman/_invocation.py
__slots__
class-attribute
instance-attribute
¶
__slots__ = ('_docs_url', '_frozen', 'cli', 'config', 'cwd', 'results', 'root', 'skipped', 'tasks', 'total_ms')
cli
instance-attribute
¶
The global options this line carried. Empty in the manifest refresh child, which has no command line — so a tree edit that reads this would be reading nothing there, which is exactly why it must not.
config
instance-attribute
¶
The merged [tool.footman] configuration.
tasks
instance-attribute
¶
tasks: Tasks | None = tasks
The merged command tree, as a Tasks view — the same surface a
TaskView edit uses. Editable at pre_tasks, when a hook may disable a
task, add a prerequisite, or read provenance.
docs_url
property
writable
¶
docs_url: str | None
The URL template task names link to, or None for no links.
Task names in --list, --tree and --help link to it, and each
--json row carries the URL as docs_url: {path} is the task's
address joined by slashes, {slug} joined by dashes. It starts as
the configured docs-url. A pre_tasks hook may set it, for a
plugin that knows where its task pages are; one that sets it only
while it is None keeps a configured docs-url first. A hook runs
on every invocation, so a template set there holds for each one,
where a value set while a module imports would not, since a
provider module imports once per process.
Raises:
| Type | Description |
|---|---|
ValueError
|
on a write, a template footman cannot fill. |
results
instance-attribute
¶
The run's rows, in the order the work was created, as result
views — filled for
post_tasks (the run itself writes past the freeze; hooks read).
Executions, shared rows, refusals and skipped nodes alike.
skipped
instance-attribute
¶
The skipped subset of results — what never ran because
something it needed failed.
total_ms
instance-attribute
¶
total_ms: float = 0.0
Wall-clock for the whole run, the envelope's total_ms — filled
for post_tasks.
freeze ¶
__setattr__ ¶
Source code in packages/footman/src/livery/footman/_invocation.py
livery.footman.Tasks ¶
Tasks(root: Group)
A hook's view of the merged command tree: iterate every task, or
look one up by its address, each as a TaskView.
Methods:
| Name | Description |
|---|---|
__iter__ |
|
get |
The task at name — its full dotted address — or |
__getitem__ |
|
__contains__ |
|
Source code in packages/footman/src/livery/footman/_registry.py
__iter__ ¶
get ¶
The task at name — its full dotted address — or None.
Addresses are unique by construction (a name is a task or a group
at each level, never both), so this either finds one task or finds
none: there is nothing here to be ambiguous about. A bare leaf is
not an address — get("build") finds a top-level build, never
docs.build. To search by leaf, iterate: two tasks may answer to
one, and picking between them is the caller's to make, not
footman's to guess.
A runnable group answers whatever its default answers, so
get("lint") is get("lint.default") — the bare group name is
that action's other spelling on the command line, and lookup would
otherwise be the one place that isn't true.
Source code in packages/footman/src/livery/footman/_registry.py
__getitem__ ¶
livery.footman.TaskView ¶
A hook's handle on one task: read its wiring, its policy flags, and
its cascade provenance (where it was defined, what it overrode), and edit it
here — never through the private _footman_* attributes.
Methods:
| Name | Description |
|---|---|
add_pre |
Prepend prerequisites (views or functions), skipping any already set. |
add_post |
Append post-tasks (views or functions), skipping any already set. |
disable |
Mark the task unavailable — listed with reason, refused if run. |
set_opts |
Set orchestration options on the task permanently, for every use — |
Attributes:
| Name | Type | Description |
|---|---|---|
fn |
The task function itself — the escape hatch past the view. |
|
name |
The task's leaf name, e.g. |
|
group |
The group this task lives in, or |
|
path |
tuple[str, ...]
|
Every segment of the task's address, leaf last — `("forge", "dev", |
address |
str
|
The task's full dotted address, exactly as the command line spells |
mounted_from |
str | None
|
Which provider this task came from — the |
pre |
tuple[Task, ...]
|
The prerequisites that run before this task. |
post |
tuple[Task, ...]
|
The tasks that run after this one. |
disabled |
str | None
|
Why the task is unavailable here, or |
keep_going |
bool | None
|
The task's declared failure policy ( |
atomic |
bool
|
Whether the task's subprocesses opt out of fail-fast's kill. |
infinite |
bool
|
Whether the task runs until stopped ( |
interactive |
bool
|
Whether the task owns the real terminal ( |
hidden |
bool | None
|
The task's own |
timed |
bool
|
Whether the task records timing history / shows a determinate bar — |
confirm |
str
|
The |
defining_dir |
str | None
|
The folder the task was defined in, or |
shadowed |
Task | None
|
The task this one overrides — same name, one cascade level up — or |
shadow_chain |
tuple[Task, ...]
|
This task and every task it shadows, nearest (this one) first. |
source_file |
str | None
|
The file the task's function is defined in, or |
Source code in packages/footman/src/livery/footman/_registry.py
name
instance-attribute
¶
The task's leaf name, e.g. build. The whole spelling is
address — two tasks in different groups share this one.
group
instance-attribute
¶
The group this task lives in, or None for a top-level task — its
.name is the group's command-line spelling (e.g. docs).
path
property
¶
Every segment of the task's address, leaf last — ("forge", "dev",
"up"). address is the same thing as one string.
address
property
¶
address: str
The task's full dotted address, exactly as the command line spells
it: forge.dev.up. Unique across the tree — a name is a task or a
group at each level, never both — so this is the key to hold a task
by, and what Tasks.get looks up.
mounted_from
property
¶
mounted_from: str | None
Which provider this task came from — the footman.tasks
entry-point identity for plugin(), the module name for
include() — or None when the tasks file defines it itself,
which is the honest answer: the project owns it.
Language-neutral by construction: it names a provider, not a file,
so it keeps answering for a task that is one day not a Python
function. A group carries the same field only when it was grafted
whole; the moment a mount composes into a group that already
exists, the group is shared and answers None while every task
under it still answers exactly. Read ownership here.
keep_going
property
¶
keep_going: bool | None
The task's declared failure policy (@task(keep_going=…)), or None
when it left the choice to the command line / the built-in default.
interactive
property
¶
interactive: bool
Whether the task owns the real terminal (@task(interactive=True)).
hidden
property
¶
hidden: bool | None
The task's own hidden= answer, or None when it inherits one.
Read the declaration, not the resolved answer: a hook that hides a group wants to know whether this task overrode it.
timed
property
¶
timed: bool
Whether the task records timing history / shows a determinate bar —
@task(progress=False) (and infinite/interactive) opt out.
defining_dir
property
¶
defining_dir: str | None
The folder the task was defined in, or None when the cascade did
not tag it (a plugin- or include()-composed task, not a cascade file).
Use it to act on tasks from one subtree of a monorepo.
shadowed
property
¶
The task this one overrides — same name, one cascade level up — or
None if it shadows nothing.
shadow_chain
property
¶
shadow_chain: tuple[Task, ...]
This task and every task it shadows, nearest (this one) first.
source_file
property
¶
source_file: str | None
The file the task's function is defined in, or None when it can't
be located (a built-in or dynamically constructed function).
add_pre ¶
add_pre(*tasks: TaskView | Task) -> None
Prepend prerequisites (views or functions), skipping any already set.
Source code in packages/footman/src/livery/footman/_registry.py
add_post ¶
add_post(*tasks: TaskView | Task) -> None
Append post-tasks (views or functions), skipping any already set.
Source code in packages/footman/src/livery/footman/_registry.py
set_opts ¶
set_opts(**overrides: Unpack[TaskOpts]) -> None
Set orchestration options on the task permanently, for every use —
the discovery-time counterpart to a per-use .opts(). Takes the same
options (TaskOpts, the whole .opts() set) and rejects a task
parameter with the same taught error; the difference is that it edits
the registered task rather than a per-use proxy, so a hook can set a
policy across a whole class of tasks. A command-line -k/--fail-fast
still wins over a set keep_going.
Source code in packages/footman/src/livery/footman/_registry.py
Custom CLI¶
livery.footman.App ¶
App(name: str = 'footman', prog: str = 'fm', version: str | None = None, tasks_file: str = 'tasks.py', dist: str | None = None, cache_dir: Path | str | None = None, data_dir: Path | str | None = None, env_prefix: str | None = None, config_name: str | None = None, builtin: Sequence[str] = ())
A branded footman CLI — call run from your console-script entry.
One App serves a process: run points module-level state (the brand,
its locations) at this brand and deliberately never restores it — a
process runs one brand, and run may not return at all (the uv handoff
re-execs). Driving two brands from one process is supported only through
footman.testing.Runner, which saves and restores around each
invocation.
Methods:
| Name | Description |
|---|---|
run |
Resolve and run the CLI, returning the process exit code. |
Attributes:
| Name | Type | Description |
|---|---|---|
brand |
Brand
|
|
Source code in packages/footman/src/livery/footman/_application.py
brand
instance-attribute
¶
brand: Brand = Brand(name=name, prog=prog, version=version or __version__, tasks_file=tasks_file, dist=dist, cache_dir=Path(cache_dir).expanduser() if cache_dir is not None else None, data_dir=Path(data_dir).expanduser() if data_dir is not None else None, env_prefix=env_prefix, config_name=config_name, builtin=tuple(builtin))
run ¶
Resolve and run the CLI, returning the process exit code.
Handles the stdlib-only --complete hot path before importing the
framework, so completion stays fast even through a custom entry point.
Source code in packages/footman/src/livery/footman/_application.py
livery.footman.Brand
dataclass
¶
Brand(name: str = 'footman', prog: str = 'fm', version: str = __version__, tasks_file: str = 'tasks.py', dist: str | None = 'livery-footman', cache_dir: Path | None = None, data_dir: Path | None = None, env_prefix: str | None = None, config_name: str | None = None, builtin: tuple[str, ...] = ())
The names a CLI shows the user, and where it keeps its things.
name is the long / display name (the --version banner); prog is
the short command name (the error prefix and hints); version is your
version string; tasks_file is the filename your users write tasks in
(config tasks still overrides it per project).
dist is the distribution that ships your CLI — the name a user would
pip install. It is what the handoffs reason about: which package a
project's lockfile must pin, and which one a tasks file carrying its
own PEP 723 dependencies must declare. Left None (the default for a
custom brand), both handoffs simply stay out of your way.
cache_dir and data_dir are the two folders this CLI keeps things
in, and you place them, so footman never guesses at your product's
layout:
acme_home = Path(os.environ.get("ACME_HOME", Path.home() / ".acme"))
cache_dir=acme_home / ".cache" / "acme-cli",
data_dir=acme_home / "acme-cli",
They are not anchored to each other — put them wherever each belongs in your world. Cache is derived data, safe to delete, and the collector sweeps it; data is durable and machine-local (credentials, tokens, generated assets) and is never collected. footman refuses to start if the two name the same directory, because that would point the collector at things it must not delete.
<PREFIX>_CACHE_DIR and <PREFIX>_DATA_DIR override them at run time,
which is how two installations run side by side under different
identities. Left unset with those variables unset, both fall back to
XDG — ~/.cache/acme and ~/.local/share/acme.
Task authors never see any of this: they call footman.cache_dir() and
footman.data_dir() and get a directory that exists.
env_prefix is the namespace for every variable this CLI reads, and
defaults to prog uppercased: the command is acme, so the variables
are ACME_*. A branded CLI reads only its own prefix, so a stray
FOOTMAN_CACHE_DIR can never move someone else's product.
Set it explicitly for either of two reasons. A terse command makes a
poor variable: footman's own is fm, but its variables are
FOOTMAN_*, because FOOTMAN_CACHE_DIR tells a reader who has never
heard of the tool what it belongs to and FM_CACHE_DIR tells them
nothing. Or the namespace collides with your product's own —
keeping it clear is yours to arrange.
config_name names the standalone config file (acme.toml), the table
inside pyproject.toml ([tool.acme]), and the user-level config
corner (~/.config/acme/), from one field so the three cannot drift
apart. It defaults to prog — the machine word your users already type,
the same rule the env prefix follows — never the display name, which is
free text ([tool."Acme DevKit"] is nothing anyone would write, and a
capitalised table is one nobody would find). Set it when the identity
your users should write isn't the command: footman's own command is
fm, but its config is footman.toml, pinned for the same reason its
variables are FOOTMAN_*. The user-level config file is not placed
by the brand: it stays at ~/.config/acme/config.toml, where a user
looks for their own settings, with <PREFIX>_CONFIG naming another.
Methods:
| Name | Description |
|---|---|
env |
This brand's spelling of an environment variable: |
config_file |
This brand's standalone config filename — |
install |
Point the process's locations at this brand — the one call the |
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
prog |
str
|
|
version |
str
|
|
tasks_file |
str
|
|
dist |
str | None
|
|
cache_dir |
Path | None
|
|
data_dir |
Path | None
|
|
env_prefix |
str | None
|
|
config_name |
str | None
|
|
builtin |
tuple[str, ...]
|
The brand's own task surface where there is no project — a tuple of |
prefix |
str
|
The environment-variable namespace — |
config_stem |
str
|
The config identity — |
builtin
class-attribute
instance-attribute
¶
The brand's own task surface where there is no project — a tuple of
footman.tasks entry-point names, mounted as the base of the tree
exactly when discovery finds no project task files. The ladder is
project > user > built-in: a project ignores the base outright (its
tasks file mounts what it wants — nothing is privileged, nothing lost),
and the user tasks file overlays it. Strings, never live objects: the
detached refresh child rebuilds manifests in a bare process, and a name
rides argv where an object cannot. Curate a small global surface — what
does this CLI offer someone with no project? — rather than aiming it at
the everyday tasks, which belong where their probes work.
config_stem
property
¶
config_stem: str
The config identity — config_name, else prog: the acme of
acme.toml, [tool.acme] and ~/.config/acme/.
env ¶
install ¶
Point the process's locations at this brand — the one call the
real entry (App.run) and the embedded harness (Runner.invoke)
both make, so the two can never configure different worlds (they
once each listed the fields by hand, and grew apart by three).
Source code in packages/footman/src/livery/footman/_application.py
livery.footman.main ¶
main(tasks_file: str | None = None) -> None
Console-script entry for footman and fm.
tasks_file makes a tasks file its own command. Ending a file with
if __name__ == "__main__":
footman.main(__file__)
turns it into a runnable script — ./deploy.py build — reading its own
tasks whatever the directory, which is what pairs with a PEP 723
header and a #!/usr/bin/env -S uv run --script shebang. An explicit
-f on the command line still wins.
Source code in packages/footman/src/livery/footman/__init__.py
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 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | |
Typed-parameter helpers¶
livery.footman.Arg
module-attribute
¶
Arg = Annotated[_T, _arg]
An optional trailing positional, via Annotated-alias:
fm files src fills the positional; a bare fm files runs on the default.
The grammar is deterministic and greedy: when a bare word follows, it is
the value — never re-interpreted as the next task, no name-peeking — and
capped at one token. To run the task argument-less ahead of another, say so
with the explicit boundary: fm files + build. An Arg needs a default
(absence must mean something), takes at most one token (use a list
parameter for many), and must trail every required positional.
Arg is the one exception to the rule that sorts every other parameter:
the default decides — no default makes a required positional, a default
makes an option you pass by name. Arg says "keep me a positional even
though I have a default", which is why it needs the greedy-but-capped
grammar above. The rules it is bending are laid out in the
typing guide.
livery.footman.Forward
module-attribute
¶
livery.footman.forward
module-attribute
¶
forward: Final[ForwardMarker] = ForwardMarker()
Forward this parameter to the tasks this task dispatches, via Annotated:
A forward-marked parameter's value is passed to every task this one
dispatches — its pre/post prerequisites, and a runnable group's fan-out —
that declares a parameter of the same name; tasks that don't declare it run on
their own defaults. The forwarded value overrides the callee's default, chains
through callees that re-declare the marker, and may satisfy a defaultless
parameter — the same courtesy ask() and stdin extend, so a receiver never
needs a fake default just to be reachable. Presence travels beside the value,
so given() reads the same sentence in the dispatcher and in what it
dispatched.
livery.footman.NoSplit
module-attribute
¶
Shorthand for Annotated[T, nosplit]: NoSplit[list[str]] opts a collection
out of comma-splitting (see nosplit).
livery.footman.nosplit
module-attribute
¶
nosplit: Final[NoSplitMarker] = NoSplitMarker()
Opt a list/dict parameter OUT of comma-splitting, via Annotated:
By default a collection parameter splits a single token on commas
(--tag a,b,c -> ["a", "b", "c"]) in addition to the repeatable form
(--tag a --tag b). Mark it nosplit when a value may itself contain a comma:
then only the repeated flag adds items and --name "a,b" stays the literal
"a,b". NoSplit[list[str]] is the terser spelling of the same thing.
livery.footman.Hidden
module-attribute
¶
Shorthand for Annotated[T, hidden]: Hidden[str] keeps a parameter out of
the listings while it still binds and completes (see hidden).
livery.footman.hidden
module-attribute
¶
hidden: Final[HiddenMarker] = HiddenMarker()
Keep a parameter out of the listings a human reads, via Annotated:
It means on a parameter what hidden=True means on a task. --help does not
list it and the synthesised example does not use it, but it still binds, still
completes, and --all reveals it. The manifest marks it rather than dropping
it, so an agent reading --describe still learns it exists — hiding and
completing are different questions, and a long machine-facing flag is the one
you most want spelled for you.
For a deprecated flag kept working but unadvertised, a debug switch, or a flag
a wrapper script passes. Hidden[str] is the terser spelling.
livery.footman.suggest ¶
Attach a dynamic completer to a parameter, via Annotated:
list_projects() -> list[str] returns the candidate values. footman runs
it on the execution path — refreshing a cache the completion hot path serves
— and, when strict (the default), validates the supplied value against a
fresh call. The wrapper is required: a bare callable in Annotated is
refused, so a marker that happens to be callable can never be mistaken
for a completer.
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
fn |
Callable[[], Any]
|
|
strict |
bool
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.exists
module-attribute
¶
exists: Final[PathRequirement] = PathRequirement('exists', 'exists')
livery.footman.isfile
module-attribute
¶
isfile: Final[PathRequirement] = PathRequirement('file', 'isfile')
Require a Path parameter to name an existing file (see exists).
livery.footman.isdir
module-attribute
¶
isdir: Final[PathRequirement] = PathRequirement('dir', 'isdir')
Require a Path parameter to name an existing directory (see exists).
livery.footman.Exists
module-attribute
¶
Shorthand for Annotated[Path, exists] — target: Exists requires the path
to exist. Type-fixed to Path; use Annotated directly for a list[Path].
livery.footman.IsFile
module-attribute
¶
Shorthand for Annotated[Path, isfile]: require an existing file.
livery.footman.IsDir
module-attribute
¶
Shorthand for Annotated[Path, isdir]: require an existing directory.
livery.footman.matching ¶
matching(pattern: str)
Narrow a Path parameter's Tab completion to a glob:
footman cannot complete paths itself — it answers from a cached manifest
and never touches the filesystem — so a path value is handed to the
shell's own file completion. This is what it hands along: the pattern
the shell filters by, so --env-file offers .env and .env.local
rather than every file in the directory.
Directories are always offered whatever the pattern says, or a match one
level down would be unreachable. The glob matches the file's name
(*.json, not **/*.json) — the vocabulary all five shells share.
Completion only. It narrows what Tab shows; it does not
reject a value typed anyway — that is check()'s job, or
exists/isfile's. A completion filter that quietly became validation
would refuse the perfectly good path someone pasted.
Methods:
| Name | Description |
|---|---|
__repr__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
pattern |
str
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.between ¶
Inclusive numeric bounds for an int/float parameter:
Validated eagerly with a taught error (--jobs must be between 1 and 32).
Either bound may be None for open-ended ranges. A bare range in
Annotated also works for ints, with Python's half-open semantics
(range(0, 8) accepts 0 through 7).
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
lo |
float | None
|
|
hi |
float | None
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.env ¶
env(var: str)
Fall back to an environment variable when the option isn't given:
Precedence is CLI > $DEPLOY_ENV > default. The env value flows through
the same coercion and validation as a command-line token. Only valid on a
parameter with a default — an env fallback makes it optional, so it
needs somewhere to fall. A body call that omits the parameter reads the
same ladder; a value passed explicitly wins over env, however the task
was asked for.
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
var |
str
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.check ¶
A custom validator, run after coercion; raise ValueError to reject:
The callable receives the coerced value (each element, for collections).
Its ValueError message is shown to the user, so write it for them.
Declare a second parameter to also receive the siblings — the parameters to this one's left at their effective values (a provided value, else the parameter's own default), coerced and read-only (empty for the first parameter) — so a check can validate against another input:
def newer(v, params):
current = current_version(params["name"]) # the package named earlier
if Version(v) <= current:
raise ValueError(f"must be newer than {current}")
def release(name: str, version: Annotated[str, check(newer)]): ...
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
fn |
Callable[..., Any]
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.default ¶
Compute a parameter's default when the task runs, via Annotated:
A Python default is evaluated once, at import — fine for a constant, wrong
for anything that depends on the machine, the environment or the clock.
default(fn) calls fn() at bind time instead, so --help and the run
agree and both are current.
It sits in the ladder just above the Python default — CLI value > env >
default(fn) > the declared default — and, like env(), it needs a
declared default to sit on: a plain Python call of the task, outside any
run, has to keep working.
Declare one positional argument and it receives the sibling parameters
resolved so far — the same courtesy check(fn) gets, and for the same
reason: a default is often a function of the inputs beside it.
def cast(*, shell: str = "zsh",
title: Annotated[str, default(lambda p: f"{p['shell']} · x")] = ""): ...
Read-only, and only what is to its left in the signature. The view holds
effective values — what each parameter will actually be — and only a left
one has that yet, which is also why a cycle cannot be written down: the
signature fixes a total order and binding walks it. Reaching rightwards is
a taught error, through p["x"] and p.get("x") alike. --help cannot
show such a default — there is no invocation to read — so it shows none
rather than one it would have to invent.
The value is used as it comes back, not coerced: fn() returns a real
object, and coercion exists because the command line only has strings. It
still runs the annotation's validators, so a default(fn) that would be
refused as a typed value is refused here too rather than smuggled in.
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
fn |
Callable[..., Any]
|
|
reads_siblings |
bool
|
Whether fn takes the sibling view. Decided once, here, because both the |
Source code in packages/footman/src/livery/footman/_params.py
reads_siblings
instance-attribute
¶
reads_siblings: bool = _takes_an_argument(fn)
Whether fn takes the sibling view. Decided once, here, because both the binder and the manifest need the answer and the manifest cannot import the binder — asking the marker beats asking the same question twice in two modules. Inspected rather than probed by call, so a real arity error raised inside fn is never mistaken for the no-argument form.
livery.footman.doc ¶
doc(text: str)
Help text for one parameter, via Annotated:
One line, written for the person at the prompt. It shows in
fm --help <task>, as the option's description in shells that render
one (zsh, fish, nushell, PowerShell tooltips), and in the
fm --json --list catalog.
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
text |
str
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.ask ¶
Prompt for a parameter's value when it isn't supplied, via Annotated:
A parameter marked ask() is prompted for when the command line does not
give it and no env fills it — the answer runs through the same coercion
and validation as a CLI token, re-asking on a bad value. Precedence is
CLI > env > prompt (offering the default) > the default.
A declared default becomes the offer: the prompt shows it, Enter accepts
it, and where nobody can be asked — off a terminal, under --no-input, in
--json — it is simply used. So ask() is safe on any parameter: a person
gets asked, an unattended run gets the default. Without a default there is
no other answer, so those cases error naming the flag rather than hanging.
Naming the option bare (--version) skips the question: the caller has
already said "the declared one", and asking again would be footman not
listening.
secret=True hides the input (getpass) and never shows the default, though
Enter still accepts it; prompt="…" overrides the question text.
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
|
prompt |
str | None
|
|
secret |
bool
|
|
Source code in packages/footman/src/livery/footman/_params.py
livery.footman.Secret ¶
Bases: str
A string that redacts everywhere it is shown.
Answers to ask(secret=True) and prompt(secret=True) arrive as
Secret, and a parameter annotated Secret coerces into one whatever
its value came from — a flag, an env() fallback, a default. It is a
real str for the body (comparisons, formatting — the caller's
business), but its repr — what tracebacks, logs, and debuggers print —
is Secret('***'), and structured surfaces serialise it as ***: the
--json envelope, a Stdout[…] document, baked manifest defaults.
Redaction covers the places footman shows a value, not the bytes a
task deliberately writes. print(token) and f"TOKEN={token}" emit the
real thing, because every string operation on a Secret yields a plain
str — which is what makes a task that must print a secret (an
export … line for eval) work without a switch to disarm.
reveal() is that unwrap said out loud, for where it isn't implicit:
@task
def creds(token: Secret) -> Stdout[dict]:
return {"token": token.reveal()} # meant to leave; not redacted
Because it is a method, every intentional exposure is greppable — an audit list a run-wide "don't redact" flag could never give you.
Methods:
| Name | Description |
|---|---|
__repr__ |
|
reveal |
The real value as a plain |
Attributes:
| Name | Type | Description |
|---|---|---|
__slots__ |
|
reveal ¶
reveal() -> str
The real value as a plain str, deliberately un-redacted.
Reach for it where a Secret would otherwise survive into a
structured surface that redacts — a dict, a dataclass field, a
Stdout[…] document — and you mean the value to be there.
Source code in packages/footman/src/livery/footman/_params.py
Docstrings¶
Standalone (stdlib-only, no footman imports) — reusable outside footman.
livery.footman.docstrings.parse ¶
Parse text (a raw or already-cleaned docstring) into its pieces.
Source code in packages/footman/src/livery/footman/docstrings.py
livery.footman.docstrings.Docstring
dataclass
¶
The parsed pieces of one docstring.
Shaped to grow additively (returns, raises, …) without breaking
reusers; absent pieces are empty, never None.
Attributes:
| Name | Type | Description |
|---|---|---|
summary |
str
|
The first line — the one-liner listings and completion menus show. |
long |
str
|
Prose between the summary and the first section ( |
params |
dict[str, str]
|
Per-parameter help, keyed by the Python parameter name (not the |
returns |
str
|
The |
summary
class-attribute
instance-attribute
¶
summary: str = ''
The first line — the one-liner listings and completion menus show.
long
class-attribute
instance-attribute
¶
long: str = ''
Prose between the summary and the first section (Args: and
friends), structure preserved; empty when there is none.
params
class-attribute
instance-attribute
¶
Per-parameter help, keyed by the Python parameter name (not the
CLI spelling): {"fix": "apply safe fixes in place"}.
Markdown export¶
Pure functions over manifest tree nodes — see Your tasks, documented for the task-level surface.
livery.footman.markdown.render_page ¶
render_page(tree: dict[str, Any], *, path: tuple[str, ...] = (), heading: int = 1, flavor: str = 'plain', prog: str = 'fm') -> str
One markdown document for the node at path (empty = whole tree).
Source code in packages/footman/src/livery/footman/markdown.py
livery.footman.markdown.render_site ¶
render_site(tree: dict[str, Any], *, path: tuple[str, ...] = (), flavor: str = 'plain', prog: str = 'fm') -> dict[str, str]
A linked set of files for the node at path: index.md per group
(name, help, a table of children with relative links), one file per task.
Keys are POSIX-relative paths.
Source code in packages/footman/src/livery/footman/markdown.py
The docs plugin¶
What plugin("footman.docs") mounts, as functions a tasks file calls to write its task reference — see Your tasks, documented.
livery.footman.docs.page ¶
page(target: Annotated[str, doc('dotted task/group to scope to; empty = all')] = '', heading: Annotated[int, between(1, 6), doc('top heading level')] = 1, flavor: Annotated[Literal['plain', 'material'], doc('plain CommonMark, or material/zensical extras')] = 'plain', out: Annotated[Path | None, doc('file to write the page into; omitted = stdout')] = None, prog: Annotated[str, _invoking_cli, doc('command name in usage and examples')] = '', all: Annotated[bool, doc("include footman's own mounted tasks")] = False) -> list[str] | None
Render the task tree (or one group/task) as one markdown page.
Without --out the page is the task's stdout, ready to redirect or pipe (into pandoc, say); with --out it is written to the file. The heading level makes the page nest under a host site's own structure, so it drops into zensical/mkdocs via a snippet include.
Source code in packages/footman/src/livery/footman/docs.py
livery.footman.docs.site ¶
site(out: Annotated[Path, doc('directory to write the pages into')], target: Annotated[str, doc('dotted group to scope to; empty = all')] = '', flavor: Annotated[Literal['plain', 'material'], doc('material fits zensical/mkdocs; plain is portable')] = 'material', prog: Annotated[str, _invoking_cli, doc('command name in usage and examples')] = '', all: Annotated[bool, doc("include footman's own mounted tasks")] = False) -> list[str]
Render the task tree as linked pages: index.md per group, one file per task.
Made for docs sites — point
Source code in packages/footman/src/livery/footman/docs.py
livery.footman.docs.globals_ ¶
globals_(out: Annotated[Path | None, doc('file to write the table into; omitted = stdout')] = None, prog: Annotated[str, _invoking_cli, doc('command name in the table')] = '') -> list[str] | None
Render the runner's global options as a markdown table.
The rows come straight from the CLI grammar — the same table --help
prints — so a reference page that regenerates this on each docs build
can never drift from the runner. Without --out the table is the task's
stdout; with --out it is written to the file.
Source code in packages/footman/src/livery/footman/docs.py
Trace fragments¶
A profiled run exports FM_PROFILE_DIR; any process drops Chrome-trace fragments there, and the run sweeps them onto its timeline. These are the protocol's two ends, for a process that writes fragments or a tool that reads a run's trace.
livery.footman.profile.DROP
module-attribute
¶
The drop box, named in every task's environment so that every child
inherits it. A child may leave Chrome-trace fragments there. One directory
per profiled run, under profiles/ in footman's cache.
The name is the same for every runner built on footman, brand and all, because it is a convention foreign tools speak: a test runner, a build, a converter for another program's timings. None of them can know a brand's prefix.
livery.footman.profile.box ¶
A drop box for the children of this block, removed when it ends.
For a runner that spawns work and wants one timeline of it, whether or not its own run is profiled: a CI job's verbs, a build's compilers.
The directory is yielded and nothing else happens: naming it to the children is the caller's, because a caller that spawns already builds their environment, and writing this process's own environment from inside a task is ambient and footman notes it. Name it under livery.footman.profile.DROP in the environment you hand them.
Yields:
| Type | Description |
|---|---|
Generator[Path]
|
The directory to name, which exists for the block's duration. |
Source code in packages/footman/src/livery/footman/profile.py
livery.footman.profile.keeping ¶
keeping() -> bool
Whether this run keeps a trace, so a caller can skip building one.
The cheap question, for a caller whose timeline costs something to assemble: a run's worth of jobs read from a forge, a tool's report parsed. One environment read, and no answer here is ever a reason to fail: nothing is profiling in the ordinary case.
Source code in packages/footman/src/livery/footman/profile.py
livery.footman.profile.dropped ¶
Leave events in this run's drop box as a fragment of its own.
For a caller with a timeline to add that this process did not live: a CI run it watched from here, a tool's own report. The stamps are epoch microseconds, the convention every fragment follows, and the writer lays the fragment on the run's clock like any other.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events
|
list[dict[str, Any]]
|
Chrome-trace events, stamped in epoch microseconds. |
required |
Returns:
| Type | Description |
|---|---|
Path | None
|
The file, or |
Path | None
|
to drop into, which is the ordinary case. |
Source code in packages/footman/src/livery/footman/profile.py
livery.footman.profile.swept ¶
Every fragment in where, on one clock; the events and that clock.
A fragment is stamped in epoch microseconds, so reading a box is subtracting one moment from every stamp. zero is that moment, in wall-clock microseconds; the earliest stamp in the box by default, which makes a file that starts at zero rather than at fifty thousand years. A fragment that will not parse is named on stderr and skipped, never fatal, because the run it rode in is the point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
where
|
Path | str
|
The directory the fragments are in. |
required |
zero
|
float | None
|
The wall-clock moment to measure from, or |
None
|
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
The events, and the moment they are measured from. No fragments at |
float
|
all is no events and the zero asked for, or zero. |
Source code in packages/footman/src/livery/footman/profile.py
livery.footman.profile.as_trace ¶
events as the text of a trace file, for a reader to open.
One place builds the shape: the events, the unit a reader shows by default, and where this trace's zero sits on the wall clock, so another timeline can be laid on it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events
|
list[dict[str, Any]]
|
Chrome-trace events, stamped relative to origin. |
required |
origin
|
float
|
That zero, in wall-clock microseconds. Zero when the stamps are already the wall clock's. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The file's text. |
Source code in packages/footman/src/livery/footman/profile.py
livery.footman.profile.laid_on ¶
laid_on(text: str, *, zero: float, pids: Iterator[int], label: str = '') -> tuple[list[dict[str, Any]], str]
One trace's events laid on another clock; the events, or why not.
A trace records the wall-clock moment its own zero sits at, and every stamp in it is relative to that. So two traces written anywhere, by anything, can be read on one timeline: each one's stamps shift by its own origin against the reading clock's. The alignment comes from what each side wrote down, never from the order anything arrived in.
The process groups are renumbered from pids, because every run's own group carries the same number and two traces would otherwise read as one process. A group's name keeps label in front of it, so a reader can tell which trace a group came from.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text
|
str
|
The trace, as its writer wrote it. |
required |
zero
|
float
|
Where the reading clock's zero sits on the wall clock, in
microseconds, as this module records it under |
required |
pids
|
Iterator[int]
|
Process ids to claim, one per group the trace holds. |
required |
label
|
str
|
What to put in front of each group's name. |
''
|
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
The events on the reading clock, and a reason when there are none: |
str
|
a trace that does not parse, or one that records no origin and so |
tuple[list[dict[str, Any]], str]
|
cannot be placed at all. |
Source code in packages/footman/src/livery/footman/profile.py
Testing¶
livery.footman.Runner ¶
Runner(app: App | None = None)
Drive a footman CLI in-process, capturing output and results.
Pass a branded App to test a custom CLI (Runner(App(prog="acme"))) —
error prefixes, --version, and hints then use that brand, exactly as
they would for real users.
Methods:
| Name | Description |
|---|---|
invoke |
Run one command line and return everything it produced. |
Attributes:
| Name | Type | Description |
|---|---|---|
app |
App
|
|
Source code in packages/footman/src/livery/footman/testing.py
invoke ¶
invoke(args: str | list[str], *, tasks: Path | Group | None = None, cwd: Path | None = None, stdin: str | bytes | None = None, answers: Mapping[Any, Any] | None = None) -> InvokeResult
Run one command line and return everything it produced.
args is a string (shlex-split) or an argv list. tasks overrides
discovery: a Path routes through --tasks-file, a Group skips
discovery entirely (an in-memory tree, no files needed). Without it,
the normal tasks.py cascade from cwd applies. stdin is what a
pipe would have delivered — a str is encoded UTF-8 — and its
absence means "a terminal": the invocation never reads the test
harness's real stream, so stdin-bound parameters see exactly what
the test says and nothing else. answers scripts the world the
invocation rehearses in — the same table recording(answers=…)
takes — and implies --dry-run, so the CLI runs end to end against
scripted commands. Never raises on task failure — the code is in
the Result; KeyboardInterrupt passes through.
Source code in packages/footman/src/livery/footman/testing.py
livery.footman.testing.InvokeResult
dataclass
¶
Everything one Runner.invoke produced.
Named apart from the run-step Result (footman.Result, what run()
returns): this is the outcome of a whole CLI invocation — its exit code,
captured streams, and per-task TaskResults.
Attributes:
| Name | Type | Description |
|---|---|---|
exit_code |
int
|
|
stdout |
str
|
|
stderr |
str
|
|
results |
list[TaskResult]
|
|
ok |
bool
|
|
livery.footman.recording ¶
Capture the commands a block would run() — silently, not executing.
Yields the live step list; each run() call inside the block — hosted
toolroom calls included — appends a Result instead of executing, and
answers with a blank success. Keyword overrides go to the underlying
Context (e.g. env={...}).
answers= scripts the answers instead. Keys are command prefixes —
"uv tool list", or a tuple of tokens — matched against the recorded
command (Result.command), longest match first. Values: a str is
stdout with exit 0, an int is an exit code, a Result sets code and
both streams, an exception instance is raised by the call (a missing
binary), and a list answers consecutive matches in order and refuses by
name when it runs dry. Unmatched calls keep the blank success. A
non-zero answer takes the real failing lane — returned under
nofail=True, raised as RunFailed otherwise — and a matched call is
answered even when it opted out of the record with recorded=False.
A recorded step also keeps the env and cwd it would have run with.
toolroom's answers() is the same table applied one layer down, at the
bridge's own seam; nested inside a recording, it wins and the record
sees nothing.