tasklib

Tasklib integrates with TaskWarrior UDAs defined in your .taskrc. If a UDA is defined (e.g., uda.estimate.type = numeric), you can use it immediately when creating tasks, saving them, or filtering.

tw = TaskWarrior()

# Create a task with a UDA
task = Task(tw, description="Long task", estimate=1000)
task.save()

# Filter tasks by a UDA
long_tasks = tw.tasks.filter(estimate=1000)

To sync your tasks with a TaskWarrior server, use tw.execute_command(['sync']).

If you need to use non-standard server credentials or certificates, update the tw.config dictionary with the required settings before running the sync command.

tw = TaskWarrior()

# Standard sync
tw.execute_command(['sync'])

# Sync with custom configuration
tw.config.update({
    'taskd.certificate': '/path/to/cert.pem',
    'taskd.server': 'task.server.com:53589',
    'taskd.ca': '/path/to/ca.pem'
})
tw.execute_command(['sync'])

You can install tasklib using pip (recommended) or by cloning the repository from GitHub and running the setup script.

# Via pip
pip install tasklib

# Via GitHub
git clone https://github.com/robgolding/tasklib.git
cd tasklib
python setup.py install

To use tasklib, ensure your environment meets the following requirements:

• Python: version 3.5 or above.
• Taskwarrior: version 2.4.x or above. (Note: Older versions are untested and may not function correctly).

Install the tasklib library using pip to interact with Taskwarrior databases using a Django-like queryset API.

pip install tasklib

Tasklib provides helpers to write TaskWarrior hook scripts (e.g., for on-add or on-modify events).

Implementation Pattern

1. Use Task.from_input() to load the task being processed by the hook.
2. Perform your logic.
3. Use task.export_data() to print the modified task data to stdout.

Handling on-modify events

In on-modify events, Tasklib loads both the original and the modified task. You can access the read-only original data using the original dict-like attribute on the Task object.

#!/usr/bin/python
from tasklib.task import Task

task = Task.from_input()

# Access original data in on-modify events
if task.original.get('description') != task['description']:
    print("Description changed!")

# Modify task
if "!!!" in task['description']:
    task['priority'] = "H"

# Export for TaskWarrior
print(task.export_data())

Annotations are represented by TaskAnnotation objects. They are simplified versions of Task objects containing only entry (a datetime) and description (a string).

Managing Annotations

1. Retrieve: Access them via the annotations key on a task.
2. Add: Use task.add_annotation("description"). Note: You must call task.save() before adding an annotation to a new task.
3. Remove: Use task.remove_annotation("description") or pass the TaskAnnotation object itself.

# Adding an annotation
task = Task(tw, description="new task")
task.save()
task.add_annotation("we can annotate saved tasks")

# Removing an annotation by description
task.remove_annotation("we can annotate saved tasks")

# Removing an annotation by object
annotation = task['annotations'][0]
task.remove_annotation(annotation)

To interact with TaskWarrior, initialize a TaskWarrior instance. By default, it uses the standard TaskWarrior data location and your .taskrc configuration.

• Use data_location to specify the database directory. If it doesn't exist, it will be created unless create=False is passed.
• Use taskrc_location to override the location of the .taskrc configuration file.

>>> tw = TaskWarrior(data_location='~/.task', create=True)

Modify tasks using dictionary-like access. Changes are only written to the TaskWarrior database after calling the .save() method.

homework = tw.tasks.get(tags=['chores'])
homework['project'] = 'Home'
homework.save()