Skip to content

wrknv Task Reference

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

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Quick Reference

# List all tasks
we tasks

# Run a task
we run <task>

# Task information
we run <task> --info

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

Task Categories

Testing

we run test

Run all tests using pytest.

we run test

Subtasks:

we run test.parallel

Run tests in parallel using pytest-xdist.

we run test.parallel

Equivalent to: uv run pytest -n auto

we run test.verbose

Run tests with verbose output.

we run test.verbose

Equivalent to: uv run pytest -vvv

we run test.unit

Run only unit tests (requires pytest markers).

we run test.unit

Equivalent to: uv run pytest -m unit

we run test.integration

Run only integration tests (requires pytest markers).

we run test.integration

Equivalent to: uv run pytest -m integration

Coverage

we run test.coverage

Run tests with coverage report (HTML + terminal).

we run test.coverage

Coverage report is generated in htmlcov/ directory.

we run 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 run lint

Run ruff linter to check code quality.

we run lint

Equivalent to: uv run ruff check .

we run lint.fix

Run linter with auto-fix enabled.

we run lint.fix

Fixes automatically fixable issues.

Formatting

we run format

Format code using ruff formatter.

we run format

Modifies files in-place.

we run format.check

Check code formatting without modifying files.

we run format.check

Returns non-zero exit code if formatting needed.

Type Checking

we run typecheck

Run mypy type checker on source code.

we run 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 run docs

Default: docs.serve

Serve documentation locally (default action).

we run docs
# or explicitly:
we run docs.serve

we run docs.setup

Extract base MkDocs configuration from provide-foundry.

we run docs.setup

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

we run docs.build

Build documentation site.

we run docs.build

Builds to site/ directory.

we run docs.serve

Serve documentation locally with auto-reload.

we run docs.serve

Typically serves on http://127.0.0.1:11000/

we run docs.clean

Remove documentation build artifacts.

we run docs.clean

Removes site/ and .provide/ directories.

we run docs.links.check

Default: docs.links.check

Check internal documentation links (fast).

we run docs.links.check

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

Performance: <1 second for internal links

we run docs.links.local

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

we run docs.links.local

Runs offline mode (no external URL checking).

we run docs.links.external

Check all links including external URLs.

we run 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 run 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"

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.