Metadata-Version: 2.4
Name: pytaskwarrior
Version: 3.0.1
Summary: Automate TaskWarrior from Python: type-safe Pydantic DTOs, virtual tags, and sync
Author-email: sznicolas <sznicolas@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://pytaskwarrior.readthedocs.io/en/latest/
Project-URL: Documentation, https://pytaskwarrior.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/sznicolas/pytaskwarrior/
Project-URL: Issues, https://github.com/sznicolas/pytaskwarrior/issues
Project-URL: Changelog, https://github.com/sznicolas/pytaskwarrior/blob/main/CHANGELOG.md
Project-URL: TaskMajor, https://github.com/sznicolas/taskmajor
Keywords: taskwarrior,taskchampion,task-management,gtd,todo,productivity,automation,pydantic,type-safe
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.11.7
Requires-Dist: taskchampion3-py-dev<3.1,>=3.0.1.3
Dynamic: license-file

# pytaskwarrior

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Tests](https://github.com/sznicolas/pytaskwarrior/workflows/CI/badge.svg)](https://github.com/sznicolas/pytaskwarrior/actions)
[![PyPI version](https://img.shields.io/pypi/v/pytaskwarrior.svg)](https://pypi.org/project/pytaskwarrior/)

A modern Python library for [TaskWarrior](https://taskwarrior.org/) v3.x task management.

**No `task` binary required.** pytaskwarrior uses
[taskchampion3-py-dev](https://github.com/sznicolas/taskchampion-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

```bash
pip install pytaskwarrior
```

## Quick Start

```python
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](https://pytaskwarrior.readthedocs.io/en/latest/)

## See Also

- **[TaskMajor](https://github.com/sznicolas/taskmajor)** — MCP server providing TaskWarrior integration for AI assistants. Built entirely on pytaskwarrior.
