Development Guide¶
This guide covers setting up your development environment and common development tasks for
invoke-tasklib itself.
Prerequisites¶
- Python 3.11 or higher
uvfor dependency management- Git for version control
Initial Setup¶
1. Fork and Clone¶
git clone https://github.com/YOUR-USERNAME/invoke-tasklib.git
cd invoke-tasklib
2. Set Up a Virtual Environment¶
uv venv --clear
source .venv/bin/activate
3. Install Dependencies¶
uv sync --group dev --group docs
The docs group is needed to build the documentation (mkdocs, mike).
4. Set Up Pre-commit Hooks¶
pre-commit install
Development Workflow¶
Running Tests¶
.venv/bin/pytest tests -q
With coverage:
.venv/bin/pytest tests --cov=invoke_tasklib --cov-report=term-missing
Since invoke-tasklib itself uses invoke as its build tool, the project's own tasks.py (which
composes tasks from invoke_tasklib) can also be used once the package is installed in editable
mode - see the Makefile and
invoke --list for the available tasks.
Code Quality¶
.venv/bin/ruff format --check src tests # format.check-python equivalent
.venv/bin/ruff check src tests # lint.check-python equivalent
.venv/bin/ty check
The doctests of the source and of the Markdown files are run with .venv/bin/inv test.doctest.
Or, once the package is installed:
invoke format.check-python
invoke lint.check-python
invoke types.check
invoke check # the main checks in one command
Documentation¶
Build documentation locally:
mkdocs serve -f docs/mkdocs.yml
Then open http://127.0.0.1:8000 in your browser.
Build without serving:
mkdocs build -f docs/mkdocs.yml
Project Structure¶
invoke-tasklib/
├── .github/ # GitHub configuration (workflows, etc.)
├── dev/ # Scripts used by the repository itself
├── docs/ # Documentation
│ ├── docs/ # Documentation source (`uguide/`, `refs/`, `dev/`, `schema.json`)
│ └── mkdocs.yml # MkDocs configuration
├── src/
│ └── invoke_tasklib/
│ ├── __init__.py # Public API: `make_ns` and individual task modules
│ ├── config/ # Config resolution: `_schema.py` (`SCHEMA`, dataclasses, JSON schema),
│ │ # `_validate.py`, `_derive.py`, `_resolve.py` (`get_config`, `load_config`),
│ │ # `_invoke.py` (the only reader of the Invoke privates), `__main__.py`
│ ├── runner.py # Command runner (`run`, `capture`, `build_command`)
│ ├── tools.py # Tool lookup and install hints (`find_tool`, `check_program`)
│ ├── output.py # Progress messages (`say`, `step`, `report_failure`)
│ ├── _steps.py # Step runner shared by `check.all` and `fix.all`
│ ├── _files.py # File lookup of the format and test tasks
│ ├── _pyproject.py # Reader of `pyproject.toml` (`read_pyproject`)
│ ├── _coverage.py # Where the coverage reports are written
│ ├── _graph.py # Static import graph of `imports.check-cycles`
│ ├── _discover.py # Module discovery and `import_each` of `imports.check-isolated`
│ ├── formatting.py # format.* tasks
│ ├── lint.py # lint.* tasks
│ ├── imports.py # imports.* tasks
│ ├── typecheck.py # types.* tasks
│ ├── testing.py # test.* tasks
│ ├── env.py # env.* tasks
│ ├── release.py # release.* tasks
│ ├── doc.py # doc.* tasks
│ ├── security.py # security.* tasks
│ ├── clean.py # clean.* tasks
│ ├── check.py # check.* tasks
│ ├── fix.py # fix.* tasks
│ └── show.py # config.* tasks
├── tests/
│ ├── helpers.py # `make_context` and `commands`, shared by the tests
│ ├── unit/ # Unit tests, one module per source module (`config/` for `config/`)
│ ├── integration/ # Tests that run the real tools (`helpers.py`: `subprocess_context`)
│ └── benchmarks/ # Benchmarks (`inv test.benchmark`), run once by `pytest tests`
├── review/ # Review notes of the repository
├── tasks.py # invoke-tasklib's own tasks.py (dogfoods `make_ns`)
├── invoke.yaml # invoke-tasklib's own tasklib config
├── pyproject.toml # Project configuration
└── README.md
Adding a New Task¶
- Pick the right module (
formatting.py,lint.py,imports.py,typecheck.py,testing.py,env.py,release.py,doc.py,security.py,clean.py,check.py,fix.pyorshow.py), or create a new one if the task doesn't fit an existing namespace (give it aNAMESPACEconstant, and add it to_MODULESof__init__.py). - Follow the
check_<target>/fix_<target>naming convention when applicable (see Format). - Call
load_config(c)if the task needs project-specific paths or the package name, rather than hardcoding them. Run the external commands withinvoke_tasklib.runner.runand build them withbuild_command(a list of words thatrunquotes), and print the progress withinvoke_tasklib.output.say; do not callc.runorprintin a task. - Write a docstring (Google style) describing the task; its first line, one sentence, is the
summary shown by
invoke --list. Give each option ahelpentry in@task, and add--args(ARGS_HELP) and--paths(PATHS_HELP) when the tool accepts extra arguments or paths. The docstring is also used by the reference docs. - Add unit tests using
invoke.context.MockContext(see existing tests for the pattern), and an integration test intests/integration/for what the unit tests patch. - If the module is new, register it in
src/invoke_tasklib/__init__.py(_MODULESand__all__). - Update the README task
table,
uguide/index.md,docs/index.mdand the corresponding user guide page.
Conventions¶
CLAUDE.md at the root of the repository is the complete list of the rules for code, tests and
pull requests. The main ones:
- Every function, public or private, has a Google-style docstring (at most 72 characters wide) and
its own unit tests; the coverage of
src/is 100%. Keep the docstrings and the documentation up to date when the behaviour, the signature or the options of the code change. - A test checks one behaviour (one
assertor onepytest.raiseswith amatch). A test that patches a collaborator has a matching integration test intests/integration/that runs the real thing. - Lint, format and type check before committing:
.venv/bin/ruff check src tests,.venv/bin/ruff format src testsand.venv/bin/ty check, then run the tests and the doctests (.venv/bin/pytest tests -qand.venv/bin/inv test.doctest). - One branch and one pull request per logical change, named
<type>/<short-description>(for examplefeat/add-cache-option), branched from an up to datemain.
Testing Guidelines¶
Tests use invoke.context.MockContext to capture the shell commands a task would run, without
actually running them. Two helpers of tests/helpers.py are shared by the test modules:
make_context builds a MockContext with an optional tasklib config, and commands returns the
commands passed to c.run (run=True makes MockContext record the calls in a Mock). Import
them instead of defining a copy in the test module:
from tests.helpers import commands, make_context
from invoke_tasklib import lint
def test_check_python() -> None:
c = make_context({"package": {"name": "mypkg"}})
lint.check_python(c)
assert commands(c) == ["ruff check ."]
The tests/unit/conftest.py fixture makes every program look available on the PATH, so the unit
tests do not depend on the tools installed on the machine. Tests that run the real tools go in
tests/integration/.
Continuous Integration¶
CI runs on every push and PR: linting, type checking, and the test suite. Documentation is built
on every push and deployed via doc.publish-dev/doc.publish-latest from a release workflow.