]> git.madduck.net Git - etc/taskwarrior.git/blob - docs/index.rst

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Merge pull request #21 from tbabej/task_compatibility
[etc/taskwarrior.git] / docs / index.rst
1 Welcome to tasklib's documentation!
2 ===================================
3
4 tasklib is a Python library for interacting with taskwarrior_ databases, using
5 a queryset API similar to that of Django's ORM.
6
7 Supports Python 2.6, 2.7, 3.2, 3.3 and 3.4 with taskwarrior 2.1.x and above.
8 Older versions of taskwarrior are untested and may not work.
9
10 Requirements
11 ------------
12
13 * taskwarrior_ v2.1.x or above.
14
15 Installation
16 ------------
17
18 Install via pip (recommended)::
19
20     pip install tasklib
21
22 Or clone from github::
23
24     git clone https://github.com/robgolding63/tasklib.git
25     cd tasklib
26     python setup.py install
27
28 Initialization
29 --------------
30
31 Optionally initialize the ``TaskWarrior`` instance with ``data_location`` (the
32 database directory). If it doesn't already exist, this will be created
33 automatically unless ``create=False``.
34
35 The default location is the same as taskwarrior's::
36
37     >>> tw = TaskWarrior(data_location='~/.task', create=True)
38
39 Creating Tasks
40 --------------
41
42 To create a task, simply create a new ``Task`` object::
43
44     >>> new_task = Task(tw, description="throw out the trash")
45
46 This task is not yet saved to TaskWarrior (same as in Django), not until
47 you call ``.save()`` method::
48
49     >>> new_task.save()
50
51 You can set any attribute as a keyword argument to the Task object::
52
53     >>> complex_task = Task(tw, description="finally fix the shower", due=datetime(2015,2,14,8,0,0), priority='H')
54
55 or by setting the attributes one by one::
56
57     >>> complex_task = Task(tw)
58     >>> complex_task['description'] = "finally fix the shower"
59     >>> complex_task['due'] = datetime(2015,2,14,8,0,0)
60     >>> complex_task['priority'] = 'H'
61
62 Modifying Task
63 --------------
64
65 To modify a created or retrieved ``Task`` object, use dictionary-like access::
66
67     >>> homework = tw.tasks.get(tags=['chores'])
68     >>> homework['project'] = 'Home'
69
70 The change is not propagated to the TaskWarrior until you run the ``save()`` method::
71
72     >>> homework.save()
73
74 Attributes, which map to native Python objects are converted. See Task Attributes section.
75
76 Task Attributes
77 ---------------
78
79 Attributes of task objects are accessible through indices, like so::
80
81     >>> task = tw.tasks.pending().get(tags__contain='work')  # There is only one pending task with 'work' tag
82     >>> task['description']
83     'Upgrade Ubuntu Server'
84     >>> task['id']
85     15
86     >>> task['due']
87     datetime.datetime(2013, 12, 5, 0, 0)
88     >>> task['tags']
89     ['work', 'servers']
90
91 The following fields are deserialized into Python objects:
92
93 * ``due``, ``wait``, ``scheduled``, ``until``, ``entry``: deserialized to a ``datetime`` object
94 * ``annotations``: deserialized to a list of ``TaskAnnotation`` objects
95 * ``tags``: deserialized to a list of strings
96 * ``depends``: deserialized to a set of ``Task`` objects
97
98 Attributes should be set using the correct Python representation, which will be
99 serialized into the correct format when the task is saved.
100
101 Operations on Tasks
102 -------------------
103
104 After modifying one or more attributes, simple call ``save()`` to write those
105 changes to the database::
106
107     >>> task = tw.tasks.pending().get(tags__contain='work')
108     >>> task['due'] = datetime(year=2014, month=1, day=5)
109     >>> task.save()
110
111 To mark a task as complete, use ``done()``::
112
113     >>> task = tw.tasks.pending().get(tags__contain='work')
114     >>> task.done()
115     >>> len(tw.tasks.pending().filter(tags__contain='work'))
116     0
117
118 To delete a task, use ``delete()``::
119
120     >>> task = tw.tasks.get(description="task added by mistake")
121     >>> task.delete()
122
123 To update a task object with values from TaskWarrior database, use ``refresh()``. Example::
124
125     >>> task = Task(tw, description="learn to cook")
126     >>> task.save()
127     >>> task['id']
128     5
129     >>> task['tags']
130     []
131
132 Now, suppose the we modify the task using the TaskWarrior interface in another terminal::
133
134     $ task 5 modify +someday
135     Task 5 modified.
136
137 Switching back to the open python process::
138
139    >>> task['tags']
140    []
141    >>> task.refresh()
142    >>> task['tags']
143    ['someday']
144
145
146 Retrieving Tasks
147 ----------------
148
149 ``tw.tasks`` is a ``TaskQuerySet`` object which emulates the Django QuerySet
150 API. To get all tasks (including completed ones)::
151
152     >>> tw.tasks.all()
153     ['First task', 'Completed task', 'Deleted task', ...]
154
155 Filtering
156 ---------
157
158 Filter tasks using the same familiar syntax::
159
160     >>> tw.tasks.filter(status='pending', tags__contains=['work'])
161     ['Upgrade Ubuntu Server']
162
163 Filter arguments are passed to the ``task`` command (``__`` is replaced by
164 a period) so the above example is equivalent to the following command::
165
166     $ task status:pending tags.contain=work
167
168 Tasks can also be filtered using raw commands, like so::
169
170     >>> tw.tasks.filter('status:pending +work')
171     ['Upgrade Ubuntu Server']
172
173 Although this practice is discouraged, as by using raw commands you may lose
174 some of the portablility of your commands over different TaskWarrior versions.
175
176 However, you can mix raw commands with keyword filters, as in the given example::
177
178     >>> tw.tasks.filter('+BLOCKING', project='Home')  # Gets all blocking tasks in project Home
179     ['Fix the toilette']
180
181 This can be a neat way how to use syntax not yet supported by tasklib. The above
182 is excellent example, since virtual tags do not work the same way as the ordinary ones, that is::
183
184     >>> tw.tasks.filter(tags=['BLOCKING'])
185     >>> []
186
187 will not work.
188
189 There are built-in functions for retrieving pending & completed tasks::
190
191     >>> tw.tasks.pending().filter(tags__contain='work')
192     ['Upgrade Ubuntu Server']
193     >>> len(tw.tasks.completed())
194     227
195
196 Use ``get()`` to return the only task in a ``TaskQuerySet``, or raise an
197 exception::
198
199     >>> tw.tasks.get(tags__contain='work')['status']
200     'pending'
201     >>> tw.tasks.get(status='completed', tags__contains='work')  # Status of only task with the work tag is pending, so this should fail
202     Traceback (most recent call last):
203       File "<stdin>", line 1, in <module>
204       File "tasklib/task.py", line 224, in get
205         'Lookup parameters were {0}'.format(kwargs))
206     tasklib.task.DoesNotExist: Task matching query does not exist. Lookup parameters were {'status': 'completed', 'tags__contains': ['work']}
207     >>> tw.tasks.get(status='pending')
208     Traceback (most recent call last):
209       File "<stdin>", line 1, in <module>
210       File "tasklib/task.py", line 227, in get
211         'Lookup parameters were {1}'.format(num, kwargs))
212     ValueError: get() returned more than one Task -- it returned 23! Lookup parameters were {'status': 'pending'}
213
214 Additionally, since filters return ``TaskQuerySets`` you can stack filters on top of each other::
215
216     >>> home_tasks = tw.tasks.filter(project='Wife')
217     >>> home_tasks.filter(due__before=datetime(2015,2,14,14,14,14))  # What I have to do until Valentine's day
218     ['Prepare surprise birthday party']
219
220 Equality of Task objects
221 ------------------------
222
223 Two Tasks are considered equal if they have the same UUIDs::
224
225     >>> task1 = Task(tw, description="Pet the dog")
226     >>> task1.save()
227     >>> task2 = tw.tasks.get(description="Pet the dog")
228     >>> task1 == task2
229     True
230
231 If you compare the two unsaved tasks, they are considered equal only if it's the
232 same Python object::
233
234     >>> task1 = Task(tw, description="Pet the cat")
235     >>> task2 = Task(tw, description="Pet the cat")
236     >>> task1 == task2
237     False
238     >>> task3 = task1
239     >>> task3 == task1
240     True
241
242 Working with annotations
243 ------------------------
244
245 Annotations of the tasks are represented in tasklib by ``TaskAnnotation`` objects. These
246 are much like ``Task`` objects, albeit very simplified.
247
248     >>> annotated_task = tw.tasks.get(description='Annotated task')
249     >>> annotated_task['annotations']
250     [Yeah, I am annotated!]
251
252 Annotations have only defined ``entry`` and ``description`` values::
253
254     >>> annotation = annotated_task['annotations'][0]
255     >>> annotation['entry']
256     datetime.datetime(2015, 1, 3, 21, 13, 55)
257     >>> annotation['description']
258     u'Yeah, I am annotated!'
259
260 To add a annotation to a Task, use ``add_annotation()``::
261
262     >>> task = Task(tw, description="new task")
263     >>> task.add_annotation("we can annotate any task")
264     Traceback (most recent call last):
265       File "<stdin>", line 1, in <module>
266         File "build/bdist.linux-x86_64/egg/tasklib/task.py", line 355, in add_annotation
267     tasklib.task.NotSaved: Task needs to be saved to add annotation
268
269 However, Task needs to be saved before you can add a annotation to it::
270
271     >>> task.save()
272     >>> task.add_annotation("we can annotate saved tasks")
273     >>> task['annotations']
274     [we can annotate saved tasks]
275
276 To remove the annotation, pass its description to ``remove_annotation()`` method::
277
278     >>> task.remove_annotation("we can annotate saved tasks")
279
280 Alternatively, you can pass the ``TaskAnnotation`` object itself::
281
282     >>> task.remove_annotation(task['annotations'][0])
283
284
285 Running custom commands
286 -----------------------
287
288 To run a custom commands, use ``execute_command()`` method of ``TaskWarrior`` object::
289
290     >>> tw = TaskWarrior()
291     >>> tw.execute_command(['log', 'Finish high school.'])
292     [u'Logged task.']
293
294 You can use ``config_override`` keyword argument to specify a dictionary of configuration overrides::
295
296     >>> tw.execute_command(['3', 'done'], config_override={'gc': 'off'}) # Will mark 3 as completed and it will retain its ID
297
298 Setting custom configuration values
299 -----------------------------------
300
301 By default, TaskWarrior does not use any of configuration values stored in
302 your .taskrc. To see what configuration values are passed to each executed
303 task command, have a peek into ``config`` attribute of ``TaskWarrior`` object::
304
305     >>> tw.config
306     {'confirmation': 'no', 'data.location': '/home/tbabej/.task'}
307
308 To pass your own configuration, you just need to update this dictionary::
309
310     >>> tw.config.update({'hooks': 'off'})  # tasklib will not trigger hooks
311
312 Working with UDAs
313 -----------------
314
315 Since TaskWarrior does not read your .taskrc, you need to define any UDAs
316 in the TaskWarrior's config dictionary, as described above.
317
318 Let us demonstrate this on the same example as in the TaskWarrior's docs::
319
320     >>> tw = TaskWarrior()
321     >>> tw.config.update({'uda.estimate.type': 'numeric'})
322
323 Now we can filter and create tasks using the estimate UDA::
324
325     >>> task = Task(tw, description="Long task", estimate=1000)
326     >>> task.save()
327     >>> task['id']
328     1
329
330 This is saved as UDA in the TaskWarrior::
331
332     $ task 1 export
333     {"id":1,"description":"Long task","estimate":1000, ...}
334
335 As long as ``TaskWarrior``'s config is updated, we can approach UDAs as built in attributes::
336
337     >>> tw.tasks.filter(estimate=1000)
338     Long task
339
340 Syncing
341 -------
342
343 Syncing is not directly supported by tasklib, but it can be made to work in a similiar way
344 as the UDAs. First we need to update the ``config`` dictionary by the values required for
345 sync to work, and then we can run the sync command using the ``execute_command()`` method::
346
347     >>> tw = TaskWarrior()
348     >>> sync_config = {
349     ...     'taskd.certificate': '/home/tbabej/.task/tbabej.cert.pem',
350     ...     'taskd.credentials': 'Public/tbabej/34af54de-3cb2-4d3d-82be-33ddb8fd3e66',
351     ...     'taskd.server': 'task.server.com:53589',
352     ...     'taskd.ca': '/home/tbabej/.task/ca.cert.pem',
353     ...     'taskd.trust': 'ignore hostname'}
354     >>> tw.config.update(sync_config)
355     >>> tw.execute_command(['sync'])
356
357
358 .. _taskwarrior: http://taskwarrior.org