wrknv Task Reference¶

Complete reference for all standard tasks provided by the wrknv.python.tmpl template.

Quick Reference¶

# List all tasks
we tasks

# Run a task
we <task>
we run <task>

# Task information
we run <task> --info

# Dry run (show what would execute)
we run <task> --dry-run

Testing¶

`we test`¶

Alias: we run test

Run all tests using pytest.

we test

Subtasks:

`we test parallel`¶

Run tests in parallel using pytest-xdist.

we test parallel

Equivalent to: uv run pytest -n auto

`we test verbose`¶

Run tests with verbose output.

we test verbose

Equivalent to: uv run pytest -vvv

`we test unit`¶

Run only unit tests (requires pytest markers).

we test unit

Equivalent to: uv run pytest -m unit

`we test integration`¶

Run only integration tests (requires pytest markers).

we test integration

Equivalent to: uv run pytest -m integration

Coverage¶

`we test coverage`¶

Alias: we run test.coverage

Run tests with coverage report (HTML + terminal).

we test coverage

Coverage report is generated in htmlcov/ directory.

`we test coverage xml`¶

Run tests with XML coverage output (for CI).

we run test.coverage.xml

Generates coverage.xml for CI systems.

Code Quality¶

Linting¶

`we lint`¶

Run ruff linter to check code quality.

we lint

Equivalent to: uv run ruff check .

`we lint fix`¶

Run linter with auto-fix enabled.

we lint fix

Fixes automatically fixable issues.

Formatting¶

`we format`¶

Format code using ruff formatter.

we format

Modifies files in-place.

`we format check`¶

Check code formatting without modifying files.

we format check

Returns non-zero exit code if formatting needed.

Type Checking¶

`we typecheck`¶

Run mypy type checker on source code.

we typecheck

Equivalent to: uv run mypy src/

Quality Checks¶

`we quality`¶

Run all quality checks (lint + typecheck).

we quality

Composite task that runs: 1. lint - Code linting 2. typecheck - Type checking

`we quality all`¶

Run all quality checks including tests.

we run quality.all

Composite task that runs: 1. format.check - Check formatting 2. lint - Code linting 3. typecheck - Type checking 4. test - Run tests

Documentation¶

`we docs`¶

Alias: we docs serve

Serve documentation locally (default action).

we docs
# or explicitly:
we docs serve

`we docs setup`¶

Extract base MkDocs configuration from provide-foundry.

we docs setup

Extracts to .provide/foundry/: - base-mkdocs.yml - Theme assets - Documentation partials - Generation scripts

`we docs build`¶

Build documentation site.

we docs build

Builds to site/ directory.

`we docs serve`¶

Serve documentation locally with auto-reload.

we docs serve

Typically serves on http://127.0.0.1:8000/

`we docs clean`¶

Remove documentation build artifacts.

we docs clean

Removes site/ and .provide/ directories.

Link Checking¶

`we docs links`¶

Alias: we docs links check

Check internal documentation links (fast).

we docs links
# or explicitly:
we docs links check

Uses lychee to validate: - ./docs/**/*.md - ./src/**/*.md - ./README.md - ./.github/**/*.md - ./CONTRIBUTING.md

Performance: <1 second for internal links

`we docs links local`¶

Same as we docs links check - check internal links only.

we docs links local

Runs offline mode (no external URL checking).

`we docs links external`¶

Check all links including external URLs.

we docs links external

Performance: 2-5 minutes depending on network

Note: Requires lychee to be installed:

brew install lychee
# or see: https://github.com/lycheeverse/lychee#installation

Mutation Testing¶

Mutation testing validates the quality of your tests by introducing bugs and checking if tests catch them.

`we mutation`¶

Run mutation testing with mutmut.

we mutation

Equivalent to: uv run mutmut run

Subtasks¶

`we mutation results`¶

Show mutation testing results summary.

we mutation results

`we mutation browse`¶

Open interactive mutation browser (web UI).

we mutation browse

`we mutation clean`¶

Clean mutation testing artifacts.

we mutation clean

Removes .mutmut-cache and html/ directories.

Build & Package¶

`we build`¶

Build package distributions.

we build

Creates wheel and sdist in dist/ directory.

Equivalent to: uv build

Package Management¶

`we pkg install`¶

Install package in development/editable mode.

we run pkg.install

Equivalent to: uv pip install -e .

`we pkg uninstall`¶

Uninstall package.

we run pkg.uninstall

Auto-detects package name from pyproject.toml.

`we pkg lock`¶

Update dependency lock file.

we run pkg.lock

Equivalent to: uv lock

`we pkg version`¶

Show package version.

we run pkg.version

Reads from VERSION file or pyproject.toml.

Development Shortcuts¶

Quick commands for common development tasks.

`we dev setup`¶

Initialize development environment.

we dev setup

Equivalent to: uv sync

`we dev test`¶

Quick test run (parallel mode).

we dev test

Equivalent to: we test parallel

`we dev check`¶

Quick quality check (format + lint + typecheck).

we dev check

Runs code formatting, linting, and type checking in sequence.

CI/CD Pipelines¶

Composite tasks for complete CI workflows.

`we ci`¶

Complete CI pipeline (quality + test + build).

we ci

Runs in sequence: 1. quality - All quality checks 2. test - Run tests 3. build - Build package

`we ci test`¶

CI testing pipeline with coverage.

we run ci.test

Runs: 1. test.parallel - Parallel test execution 2. test.coverage - Coverage reporting

`we ci quality`¶

CI quality checks pipeline.

we run ci.quality

Runs: 1. format.check - Verify formatting 2. lint - Code linting 3. typecheck - Type checking

Clean¶

`we clean`¶

Remove all build artifacts and caches.

we run clean

Removes: - build/, dist/, *.egg-info - .pytest_cache, .mypy_cache, .ruff_cache - .hypothesis, htmlcov/, .coverage - .mutmut-cache, site/ - All __pycache__ directories - All .pyc and .pyo files

Setup¶

`we setup`¶

Initialize development environment.

we setup

Equivalent to: uv sync

`we setup pre_commit`¶

Install pre-commit hooks.

we run setup.pre_commit

Installs: 1. pre-commit tool (if not installed) 2. Standard pre-commit config from ci-tooling 3. Git hooks for commit and commit-msg

Task Composition¶

Tasks can be combined in your project-specific wrknv.toml:

# Create custom composite tasks
[tasks.all-checks]
run = ["format", "lint", "typecheck", "test"]
description = "Run all checks sequentially"

[tasks.quick]
run = ["format", "lint", "test.fast"]
description = "Quick validation for rapid iteration"

Environment Variables¶

Tasks can use environment variables:

[tasks.test.integration]
run = "uv run pytest tests/integration/"
env = { DATABASE_URL = "postgresql://localhost/test" }
timeout = 300.0

Task Timeouts¶

Set timeouts for long-running tasks:

[tasks.mutation]
_default = "uv run mutmut run"
timeout = 1800.0  # 30 minutes

Working Directories¶

Specify working directory for tasks:

[tasks.docs.api]
run = "python scripts/generate_api_docs.py"
working_dir = "./docs"

Deploying wrknv Tasks - How to deploy these tasks
Link Checking Guide - Link validation details
wrknv Documentation - Full wrknv user guide

Customizing Tasks¶

Projects can customize or extend standard tasks in their wrknv.toml:

# Override standard task
[tasks.test]
_default = "uv run pytest -v --tb=short"

# Add project-specific task
[tasks.benchmark]
run = "uv run pytest benchmarks/ --benchmark-only"
description = "Run performance benchmarks"

# Extend standard task category
[tasks.docs.pdf]
run = "mkdocs build && pandoc site/index.html -o docs.pdf"
description = "Generate PDF documentation"

Custom tasks are preserved when extracting template updates.

wrknv Task Reference¶

Quick Reference¶

Task Categories¶

Testing¶

we test¶

we test parallel¶

we test verbose¶

we test unit¶

we test integration¶

Coverage¶

we test coverage¶

we test coverage xml¶

Code Quality¶

Linting¶

we lint¶

we lint fix¶

Formatting¶

we format¶

we format check¶

Type Checking¶

we typecheck¶

Quality Checks¶

we quality¶

we quality all¶

Documentation¶

we docs¶

we docs setup¶

we docs build¶

we docs serve¶

we docs clean¶