footman
A task runner with the soul of duty and the UX of typer: typed function signatures become real flags and positionals, modules become nested command groups, independent tasks run in parallel by default, and shell completion answers from a cached manifest — without importing your code. Building that cache does import it, once, in a detached subprocess: the first Tab in a fresh directory pays for it, and no keystroke after that.
Ships two console scripts, footman and the two-letter fm — one program,
both names, so a PATH that already has an fm still gets the long
spelling. Zero runtime dependencies. Python 3.11+ (the first Python with
stdlib TOML reading — that floor is what buys the zero).
Beta. footman is pre-1.0: the surface is settling, but minor versions may still include breaking changes — always called out in the changelog, never in a patch release. Pin the minor (
footman~=0.50.0) if you build on it. What is covered, what is internal, and what has to be true before 1.0 are written down in the stability promise.
Why
duty gets a lot right — the run() capture model, the decorator
ergonomics — and footman keeps those ideas. It tries to improve on the parts
you meet every day: completion served from a cache instead of re-importing your
project on every Tab, eager type and choice
validation with errors that teach, a DAG scheduler that runs independent
tasks concurrently — four steps that each wait on something finish in the
time of the longest, not the sum — with true fail-fast that kills in-flight work on the
first failure, runnable command groups and parameter forwarding that make
composite commands like fm lint and check real commands, a monorepo task
cascade that merges a tasks.py per directory, and a first-party story for
testing your tasks. The receipts live
in the comparison —
every number reproducible from
comparison/.
Taste
uv add --dev footman # or: pip install footman
# tasks.py
from typing import Literal
from footman import task, group, run
from toolroom import pytest, ruff
@task
def lint(fix: bool = False):
"Run ruff over the project."
ruff.check("src", fix=fix)
@task
def typecheck():
"Type-check the project."
run("basedpyright src")
@task(pre=[lint])
def test(*pytest_args):
"Run the test suite (extra args after --)."
pytest(*pytest_args)
@task
def deploy(target: Literal["dev", "staging", "prod"]):
"Deploy to a target."
run(f"./deploy.sh {target}")
docs = group("docs", help="Documentation")
@docs.task(infinite=True)
def serve(port: int = 8000):
"Serve the docs locally."
run(f"mkdocs serve -a localhost:{port}")
$ fm lint --fix
$ fm lint typecheck test # one chain; independent tasks run in parallel
$ fm docs.serve --port=8001 # options go right after their task
$ fm test -- -k grammar -x # everything after -- goes to pytest
$ fm deploy produ
fm: deploy: <target> must be one of dev|staging|prod (got 'produ') — did you mean 'prod'?
$ fm --install-completion # detects your shell; TAB answers from the cache
That
from toolroom import …is optional. toolroom makes command-line calls Python: it wraps any program, not a fixed list, with keyword arguments becoming flags —toolroom.terraform("plan")runs whether or not toolroom has heard of terraform. For common tools it also ships type hints generated from each tool's own metadata, so your editor knows the flags and what they do; the hints only decide whether your editor can help, never whether a call works.It began as part of footman and was spun out for two reasons: it releases on its own schedule, and other people might want type hinted, documented command-line calls without using footman. footman does not depend on it and never imports it — plain
run("…")is always there.
One file, dependencies included
A tasks file can declare what it needs inline (PEP 723), and then it needs no project at all — drop it in any directory and run it:
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["footman", "httpx"]
# ///
import footman
from footman import task
@task
def health(url: str = "https://example.com"):
"Check a deployment is up."
import httpx
print(httpx.get(url).status_code)
if __name__ == "__main__":
footman.main(__file__)
fm health builds that environment once and runs inside it — name any
other file with -f=deploy.py and the same rule applies. chmod +x
and ./deploy.py health works with no runner installed at all. Checked
into a project that pins footman, the header is simply ignored and the
file runs on the project's dependencies — portable and at home.
Learn more
Documentation — start with Getting started, then the good parts: typed signatures · chaining & parallelism · monorepos · composing tasks · running tools · testing your tasks · completion · CI & automation · comparison with duty / invoke / poe / typer
MIT licensed. The road to 1.0 lives in ROADMAP.md.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file footman-0.50.0.tar.gz.
File metadata
- Download URL: footman-0.50.0.tar.gz
- Upload date:
- Size: 444.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
765022e7953d78e5ccfd373cd006079529c7a2b9c24dc4fbc31654fb9e43e6f0
|
|
| MD5 |
2f1f2b2c32692fe3adb0c4ff656a46bd
|
|
| BLAKE2b-256 |
0a55eb8f79868c198a0b1311311d66bb4c0f76e39e625dcced145ef18eec690f
|
Provenance
The following attestation bundles were made for footman-0.50.0.tar.gz:
Publisher:
release.yml on willemkokke/footman
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
footman-0.50.0.tar.gz -
Subject digest:
765022e7953d78e5ccfd373cd006079529c7a2b9c24dc4fbc31654fb9e43e6f0 - Sigstore transparency entry: 2687685609
- Sigstore integration time:
-
Permalink:
willemkokke/footman@06a3e6524bed9a95a86c427e0484fd4e01b11021 -
Branch / Tag:
refs/tags/v0.50.0 - Owner: https://github.com/willemkokke
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@06a3e6524bed9a95a86c427e0484fd4e01b11021 -
Trigger Event:
push
-
Statement type:
File details
Details for the file footman-0.50.0-py3-none-any.whl.
File metadata
- Download URL: footman-0.50.0-py3-none-any.whl
- Upload date:
- Size: 467.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6df0050150e0386c5ef7c8fc5fa38b62ce741b78237d1421388a9f64935d0c0a
|
|
| MD5 |
8f9625d955f438eea0424223bc37d4f4
|
|
| BLAKE2b-256 |
87d4cb02247f87259b5a93fc2ae899ae1d2668959d2d6a25cbb546c845383092
|
Provenance
The following attestation bundles were made for footman-0.50.0-py3-none-any.whl:
Publisher:
release.yml on willemkokke/footman
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
footman-0.50.0-py3-none-any.whl -
Subject digest:
6df0050150e0386c5ef7c8fc5fa38b62ce741b78237d1421388a9f64935d0c0a - Sigstore transparency entry: 2687685820
- Sigstore integration time:
-
Permalink:
willemkokke/footman@06a3e6524bed9a95a86c427e0484fd4e01b11021 -
Branch / Tag:
refs/tags/v0.50.0 - Owner: https://github.com/willemkokke
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@06a3e6524bed9a95a86c427e0484fd4e01b11021 -
Trigger Event:
push
-
Statement type:
