Format¶
This page describes the
invoke_tasklib.formatting module, which provides tasks for checking
and fixing code, docstring, and shell script formatting.
Overview¶
Tasks follow a check_<target> / fix_<target> naming convention:
check_<target>tasks are read-only: they fail with a non-zero exit code if formatting is wrong, but never modify files.fix_<target>tasks modify files in place to match the expected format.
| Task | Behavior |
|---|---|
format.check-python |
Checks Python formatting with ruff (read-only) |
format.fix-python |
Formats Python code with ruff (in place) |
format.check-docstrings |
Checks docstring formatting with docformatter (read-only) |
format.fix-docstrings |
Formats docstrings with docformatter (in place) |
format.check-shell |
Checks shell scripts with shellcheck (read-only) |
format.check-shell-format |
Checks shell script formatting with shfmt (read-only) |
format.fix-shell |
Formats shell scripts with shfmt (in place) |
Checking Format¶
invoke format.check-python
invoke format.check-docstrings
invoke format.check-shell
invoke format.check-shell-format
These are safe to run anywhere, including in CI, since they never modify files.
Fixing Format¶
invoke format.fix-python
invoke format.fix-docstrings
invoke format.fix-shell
Warning
fix_* tasks modify files in place. Ensure your work is committed before running them.
Docstring Style¶
format.check-docstrings and format.fix-docstrings run docformatter against paths.src from
the resolved config, using the [tool.docformatter] section of the consuming
project's pyproject.toml (via --config ./pyproject.toml). If paths.src does not exist (and
--paths is not set), the tasks exit with 2 and name tasklib.paths.src, before running anything.
Shell Scripts¶
format.check-shell, format.check-shell-format and format.fix-shell operate on every *.sh
file in the project. In a git work tree the files are the ones that git lists
(git ls-files --cached --others --exclude-standard):
the tracked files and the untracked files that are not ignored, so the rules of .gitignore are
followed, like ruff, codespell and pre-commit do, and third-party scripts (for example the
activation scripts of a virtual environment, whatever its name) are never checked or rewritten as
long as the environment is ignored. A tracked file is kept, even in a build directory. The
directories of the environments (.git, .venv, node_modules) and of the caches of the tools
(.pytest_cache, .ruff_cache, .mypy_cache, .tox, .nox, ...) are always left out.
Outside a git work tree, or without git, the files are found by a walk in Python (no find or
xargs) that does not search those directories nor build, dist, site and htmlcov. The files
are given to the tool as arguments; if there is no *.sh file, the tool is not run, the task
prints a ⏭️ line and exits with 0.
Note
shellcheck and shfmt are not Python packages, so they aren't installed by
env.install. Install them with your system package manager, e.g.
brew install shellcheck shfmt on macOS or apt install shellcheck on Debian/Ubuntu
(shfmt there comes from the golang-go toolchain or a
release binary).
The three tasks take --args for the tool (placed before a -- separator, so a script name that
starts with a dash is not read as an option) and --paths to run on given scripts instead of every
*.sh file of the project. format.check-shell-format runs shfmt -d (it prints a diff and never
changes a file) and format.fix-shell runs shfmt -l -w (it lists the files that it rewrites).
See Also¶
- Config: where
paths.src(used by the docstring tasks) comes from. - Lint: the companion
lint.check-pythontask. invoke_tasklib.formattingreference- Troubleshooting: fixes for "command not found" errors.