pytaskwarrior 3.0.2

Automate TaskWarrior from Python: type-safe Pydantic DTOs, virtual tags, and sync

pytaskwarrior

A modern Python library for TaskWarrior v3.x task management.

No task binary required. pytaskwarrior uses taskchampion3-py-dev — Rust bindings to the taskchampion storage engine — for direct, high-performance SQLite access.

Features

• No external binary — reads/writes TaskWarrior's SQLite database directly
• Full CRUD operations — Create, read, update, delete tasks
• Type-safe — Pydantic models with full type hints
• Context management — Define, apply, and switch contexts (reads/writes .taskrc)
• UDA support — User Defined Attributes
• Virtual tags — +OVERDUE, +DUE, +TODAY, +WEEK, +BLOCKED, +READY, and 20+ more
• Date expressions — due.before:tomorrow, due.after:eom, compound expressions (now + P3D)
• Recurring tasks — Full recurrence support
• Annotations — Add notes to tasks
• Sync — Remote and local directory sync via taskchampion protocol
• Optional CLI fallback — Pass task_cmd="task" to use the classic CLI adapter

Requirements

• Python 3.9+
• taskchampion3-py-dev >= 3.0.1.3 (installed automatically)

The task binary is not required for the default adapter.

Installation

pip install pytaskwarrior

Quick Start

from taskwarrior import TaskWarrior, TaskInputDTO, Priority

# No binary needed — uses taskchampion SQLite backend directly
tw = TaskWarrior()

# Create a task
task = tw.add_task(TaskInputDTO(
    description="Finish project report",
    priority=Priority.HIGH,
    project="work",
    tags=["urgent"],
    due="friday",
))

# Query tasks
for t in tw.get_tasks("project:work +READY"):
    print(f"[{t.priority or '-'}] {t.description}")

# Virtual tag filtering
overdue = tw.get_tasks("+OVERDUE")
due_soon = tw.get_tasks("due.before:eow")

# Complete a task
tw.done_task(task.uuid)

Documentation

Full documentation: pytaskwarrior.readthedocs.io

See Also

• TaskMajor — MCP server providing TaskWarrior integration for AI assistants. Built entirely on pytaskwarrior.