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 in ~30 ms — without importing your code.
Ships two console scripts, footman and the two-letter fm. Zero runtime
dependencies. Python 3.11+.
[!NOTE] 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.41.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 (~13× faster, measured), eager type and choice
validation with errors that teach, a DAG scheduler that runs independent
tasks concurrently (the same four-step check lands ~3.5× sooner than duty
or invoke, measured) 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 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(pre=[lint])
def test(*pytest_args):
"Run the test suite (extra args after --)."
pytest(*pytest_args)
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 test docs.serve --port=8001 # one chain; independent tasks run in parallel
$ 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 in ~30 ms
[!NOTE] 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; 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.41.0.tar.gz.
File metadata
- Download URL: footman-0.41.0.tar.gz
- Upload date:
- Size: 367.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d6641551a393575d098e71023f485db4647b42ce33d40166ba8f9774894ef1fe
|
|
| MD5 |
64745ddecc35b03cb2722eb68988bc8e
|
|
| BLAKE2b-256 |
adbcbf4e6a5289bfa66183ea86da30b4ff1a5240b72fc994dc06ae02c2fa0034
|
Provenance
The following attestation bundles were made for footman-0.41.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.41.0.tar.gz -
Subject digest:
d6641551a393575d098e71023f485db4647b42ce33d40166ba8f9774894ef1fe - Sigstore transparency entry: 2482152032
- Sigstore integration time:
-
Permalink:
willemkokke/footman@f3a46cfb6b2e26c864e8b4edb739f91d4f59011b -
Branch / Tag:
refs/tags/v0.41.0 - Owner: https://github.com/willemkokke
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@f3a46cfb6b2e26c864e8b4edb739f91d4f59011b -
Trigger Event:
push
-
Statement type:
File details
Details for the file footman-0.41.0-py3-none-any.whl.
File metadata
- Download URL: footman-0.41.0-py3-none-any.whl
- Upload date:
- Size: 386.7 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 |
5a34b10e915d4f8933237d464ee2cec935289540a23a3ffe93239221024eb62a
|
|
| MD5 |
76cb3d83cf40af02777301969e1a15ab
|
|
| BLAKE2b-256 |
4b227502acc55ffeee6acfb352b2cf834a5d59681fd020db25c50cac3076750d
|
Provenance
The following attestation bundles were made for footman-0.41.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.41.0-py3-none-any.whl -
Subject digest:
5a34b10e915d4f8933237d464ee2cec935289540a23a3ffe93239221024eb62a - Sigstore transparency entry: 2482152097
- Sigstore integration time:
-
Permalink:
willemkokke/footman@f3a46cfb6b2e26c864e8b4edb739f91d4f59011b -
Branch / Tag:
refs/tags/v0.41.0 - Owner: https://github.com/willemkokke
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@f3a46cfb6b2e26c864e8b4edb739f91d4f59011b -
Trigger Event:
push
-
Statement type:
