pytaskwarrior 2.0.7__tar.gz → 3.0.0a1__tar.gz

{pytaskwarrior-2.0.7 → pytaskwarrior-3.0.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytaskwarrior
-Version: 2.0.7
+Version: 3.0.0a1
 Summary: Taskwarrior wrapper python module
 Author-email: sznicolas <sznicolas@users.noreply.github.com>
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2.11.7
+Requires-Dist: taskchampion3-py-dev>=3.0.1.1a0
 Dynamic: license-file
 
 # pytaskwarrior

pytaskwarrior-3.0.0a1/README.md

@@ -0,0 +1,123 @@
+# pytaskwarrior
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-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)
+
+A modern Python library for [TaskWarrior](https://taskwarrior.org/) v3.x task management.
+
+**No `task` binary required.** pytaskwarrior uses
+[taskchampion-py](https://github.com/GothenburgBitFactory/taskchampion-py) — 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
+- **Optional CLI fallback** — Pass `task_cmd="task"` to use the classic CLI adapter
+
+## Requirements
+
+- Python 3.12+
+- `taskchampion-py` >= 3.0.1.1 (installed automatically)
+
+The `task` binary is **not required** for the default adapter.
+
+## Installation
+
+```bash
+pip install pytaskwarrior
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sznicolas/pytaskwarrior.git
+cd pytaskwarrior
+uv sync
+```
+
+## 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",
+))
+print(f"Created: {task.uuid}")
+
+# Query tasks
+for t in tw.get_tasks("project:work"):
+    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)
+```
+
+### Using the CLI adapter (optional)
+
+```python
+# Explicit CLI mode — requires the task binary
+tw = TaskWarrior(task_cmd="task")
+
+# Custom paths
+tw = TaskWarrior(
+    taskrc_file="/path/to/.taskrc",
+    data_location="/path/to/task/data",
+)
+```
+
+## Architecture
+
+```
+TaskWarrior (facade)
+├── TaskChampionAdapter  ← default: direct SQLite via taskchampion-py
+│   ├── CRUD operations (add/get/modify/delete tasks)
+│   ├── Filtering (tc_filter.py — Python reimplementation of TW filters)
+│   └── Date resolution (date_resolver.py — Python reimplementation of TW dates)
+├── ConfigStore          ← reads/writes ~/.taskrc
+│   ├── ContextService   ← define/apply/delete contexts
+│   └── UdaService       ← define/delete UDAs
+└── TaskWarriorAdapter   ← optional CLI fallback (task_cmd="task")
+```
+
+## Supported Filter Syntax
+
+| Token | Example | Description |
+|-------|---------|-------------|
+| `+tag` / `-tag` | `+urgent -someday` | Include / exclude by tag |
+| `+VIRTUAL` | `+OVERDUE`, `+DUE`, `+TODAY` | Virtual tags (computed) |
+| `status:X` | `status:pending` | Status filter |
+| `project:X` | `project:work` | Project (hierarchical) |
+| `priority:X` | `priority:H` | Priority |
+| `due.before:X` | `due.before:tomorrow` | Date range |
+| `due.after:X` | `due.after:eom` | Date range |
+| `due.by:X` | `due.by:friday` | Date range (inclusive) |
+
+## Next Steps
+
+- [Getting Started](docs/getting-started.md) — Installation and setup
+- [TaskChampion Adapter](docs/taskchampion-adapter.md) — Technical details
+- [API Reference](docs/api/taskwarrior.md) — Full API documentation
+- [Examples](docs/examples/basic.md) — More usage examples

{pytaskwarrior-2.0.7 → pytaskwarrior-3.0.0a1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytaskwarrior"
-version = "2.0.7"
+version = "3.0.0a1"
 description = "Taskwarrior wrapper python module"
 readme = "PYPI_README.md"
 requires-python = ">=3.12"
@@ -21,6 +21,8 @@ classifiers = [
 ]
 dependencies = [
     "pydantic>=2.11.7",
+    #    "taskchampion-py-dev>=3.0.1.1a1"
+    "taskchampion3-py-dev>=3.0.1.1a0",
 ]
 
 [dependency-groups]
@@ -94,3 +96,19 @@ strict_equality = true
 [[tool.mypy.overrides]]
 module = "tests.*"
 disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q --ignore=tests/integration"
+
+[tool.coverage.run]
+source = ["src/taskwarrior"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

{pytaskwarrior-2.0.7 → pytaskwarrior-3.0.0a1}/src/pytaskwarrior.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytaskwarrior
-Version: 2.0.7
+Version: 3.0.0a1
 Summary: Taskwarrior wrapper python module
 Author-email: sznicolas <sznicolas@users.noreply.github.com>
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2.11.7
+Requires-Dist: taskchampion3-py-dev>=3.0.1.1a0
 Dynamic: license-file
 
 # pytaskwarrior

{pytaskwarrior-2.0.7 → pytaskwarrior-3.0.0a1}/src/pytaskwarrior.egg-info/SOURCES.txt

@@ -14,7 +14,10 @@ src/taskwarrior/exceptions.py
 src/taskwarrior/main.py
 src/taskwarrior/py.typed
 src/taskwarrior/adapters/__init__.py
+src/taskwarrior/adapters/taskchampion_adapter.py
 src/taskwarrior/adapters/taskwarrior_adapter.py
+src/taskwarrior/adapters/tc_converter.py
+src/taskwarrior/adapters/tc_filter.py
 src/taskwarrior/config/config_store.py
 src/taskwarrior/config/uda_parser.py
 src/taskwarrior/dto/__init__.py
@@ -30,5 +33,7 @@ src/taskwarrior/services/context_service.py
 src/taskwarrior/services/uda_service.py
 src/taskwarrior/utils/__init__.py
 src/taskwarrior/utils/conversions.py
+src/taskwarrior/utils/date_resolver.py
 src/taskwarrior/utils/dto_converter.py
+src/taskwarrior/utils/virtual_tags.py
 tests/test_main_get_udas.py

pytaskwarrior-3.0.0a1/src/pytaskwarrior.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pydantic>=2.11.7
+taskchampion3-py-dev>=3.0.1.1a0

{pytaskwarrior-2.0.7 → pytaskwarrior-3.0.0a1}/src/taskwarrior/__init__.py

@@ -29,7 +29,9 @@ Example:
 
 Requirements:
     - Python 3.12+
-    - TaskWarrior 3.4+ installed and accessible via `task` command
+    - The ``task`` binary is only required when passing ``task_cmd`` to
+      :class:`~taskwarrior.TaskWarrior`; the default backend (TaskChampion)
+      works without it.
 """
 
 import importlib.metadata
@@ -53,13 +55,10 @@ from .registry.uda_registry import UdaRegistry
 from .utils.dto_converter import task_output_to_input
 
 __version__ = importlib.metadata.version("pytaskwarrior")
-# Backwards-compatible alias
-version = __version__
 
 __all__ = [
     "AnnotationDTO",
     "ContextDTO",
-    "version",
     "Priority",
     "RecurrencePeriod",
     "TaskID",

pytaskwarrior-3.0.0a1/src/taskwarrior/adapters/__init__.py

@@ -0,0 +1,79 @@
+"""Adapter interfaces for pytaskwarrior.
+
+This module exposes the :class:`AdapterProtocol` that any backend adapter
+must satisfy, enabling dependency injection and testability.
+
+It also re-exports :class:`~taskchampion.AccessMode` for convenience, so
+callers do not need to import directly from ``taskchampion``.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from taskchampion import AccessMode
+
+from ..dto.task_dto import TaskInputDTO, TaskOutputDTO
+from ..dto.task_id import TaskRef
+
+__all__ = ["AdapterProtocol", "AccessMode"]
+
+
+@runtime_checkable
+class AdapterProtocol(Protocol):
+    """Structural protocol satisfied by every pytaskwarrior adapter.
+
+    Both :class:`~taskwarrior.adapters.taskwarrior_adapter.TaskWarriorAdapter`
+    (subprocess-based) and
+    :class:`~taskwarrior.adapters.taskchampion_adapter.TaskChampionAdapter`
+    (direct SQLite via taskchampion-py) implement this protocol.
+    """
+
+    def add_task(self, task: TaskInputDTO) -> TaskOutputDTO: ...
+
+    def modify_task(self, task: TaskInputDTO, task_id: TaskRef) -> TaskOutputDTO: ...
+
+    def get_task(self, task_id: TaskRef) -> TaskOutputDTO: ...
+
+    def get_tasks(
+        self,
+        filter: str = "",
+        include_completed: bool = False,
+        include_deleted: bool = False,
+    ) -> list[TaskOutputDTO]: ...
+
+    def get_recurring_task(self, task_id: TaskRef) -> TaskOutputDTO: ...
+
+    def get_recurring_instances(self, task_id: TaskRef) -> list[TaskOutputDTO]: ...
+
+    def delete_task(self, task_id: TaskRef) -> None: ...
+
+    def purge_task(self, task_id: TaskRef) -> None: ...
+
+    def done_task(self, task_id: TaskRef) -> None: ...
+
+    def start_task(self, task_id: TaskRef) -> None: ...
+
+    def stop_task(self, task_id: TaskRef) -> None: ...
+
+    def annotate_task(self, task_id: TaskRef, annotation: str) -> None: ...
+
+    def synchronize(self) -> None: ...
+
+    def is_sync_configured(self) -> bool: ...
+
+    def has_local_changes(self) -> bool: ...
+
+    def pending_local_ops_count(self) -> int: ...
+
+    def task_calc(self, date_str: str) -> str: ...
+
+    def task_date_validator(self, date_str: str) -> bool: ...
+
+    def get_data_location(self) -> str | None: ...
+
+    def get_version(self) -> str: ...
+
+    def get_projects(self) -> list[str]: ...
+
+    def get_tags(self, include_virtual_tags: bool = False) -> list[str]: ...