pytaskwarrior 2.0.3

Taskwarrior wrapper python module

pytaskwarrior

A modern Python wrapper for TaskWarrior, the command-line task management tool.

Production-ready with 164 tests (96% coverage), strict type checking, and professional-grade code quality. Zero linting errors, full async-safe subprocess handling, PEP 561 type hints for IDE support, and a consistent exception hierarchy.

Features

• Full CRUD operations for tasks
• Type-safe with Pydantic models
• Context management
• UDA (User Defined Attributes) support
• Tag discovery and @ context tags
• Recurring tasks and annotations
• Consistent exception hierarchy (TaskNotFound, TaskValidationError, TaskOperationError, TaskConfigurationError, …)

Requirements

• Python 3.12+
• TaskWarrior 3.4+ installed

Installation

pip install pytaskwarrior

Quick Start

from taskwarrior import TaskWarrior, TaskInputDTO, Priority

tw = TaskWarrior()

# Create a task
task = TaskInputDTO(
    description="Important meeting",
    priority=Priority.HIGH,
    project="work",
    due="friday"
)
added = tw.add_task(task)

# Get all pending tasks
for t in tw.get_tasks():
    print(f"[{t.priority or '-'}] {t.description}")

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

Tags

tags = tw.get_tags()  # virtual tags excluded
all_tags = tw.get_tags(include_virtual_tags=True)
context_tags = tw.get_context_tags()  # tags starting with "@"

Documentation

Full documentation: GitHub Repository