]> 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:

Temporarily remove tasklib v2.4.0beta2 from tested versions
[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 2.2.x.
8 Older versions of taskwarrior are untested and may not work.
9
10 Requirements
11 ------------
12
13 * taskwarrior_ v2.1.x or v2.2.x
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 Retrieving Tasks
40 ----------------
41
42 ``tw.tasks`` is a ``TaskQuerySet`` object which emulates the Django QuerySet
43 API. To get all tasks (including completed ones)::
44
45     >>> tw.tasks.all()
46
47 Filtering
48 ---------
49
50 Filter tasks using the same familiar syntax::
51
52     >>> tw.tasks.filter(status='pending', tags__contain='work')
53     ['Upgrade Ubuntu Server']
54
55 Filter arguments are passed to the ``task`` command (``__`` is replaced by
56 a period) so the above example is equivalent to the following command::
57
58     $ task status:pending tags.contain=work
59
60 Tasks can also be filtered using raw commands, like so::
61
62     >>> tw.tasks.filter('status:pending +work')
63     ['Upgrade Ubuntu Server']
64
65 There are built-in functions for retrieving pending & completed tasks::
66
67     >>> tw.tasks.pending().filter(tags__contain='work')
68     ['Upgrade Ubuntu Server']
69     >>> len(tw.tasks.completed())
70     227
71
72 Use ``get()`` to return the only task in a ``TaskQuerySet``, or raise an
73 exception::
74
75     >>> tw.tasks.filter(status='pending', tags__contain='work').get()
76     'Upgrade Ubuntu Server'
77     >>> tw.tasks.filter(status='pending', tags__contain='work').get(status='completed')
78     Traceback (most recent call last):
79       File "<stdin>", line 1, in <module>
80       File "tasklib/task.py", line 224, in get
81         'Lookup parameters were {0}'.format(kwargs))
82     tasklib.task.DoesNotExist: Task matching query does not exist. Lookup parameters were {'status': 'completed'}
83     >>> tw.tasks.filter(status='pending', tags__contain='home').get()
84     Traceback (most recent call last):
85       File "<stdin>", line 1, in <module>
86       File "tasklib/task.py", line 227, in get
87         'Lookup parameters were {1}'.format(num, kwargs))
88     ValueError: get() returned more than one Task -- it returned 2! Lookup parameters were {}
89
90 Task Attributes
91 ---------------
92
93 Attributes of task objects are accessible through indices, like so::
94
95     >>> task = tw.tasks.pending().filter(tags__contain='work').get()
96     >>> task['description']
97     'Upgrade Ubuntu Server'
98     >>> task['id']
99     15
100     >>> task['due']
101     datetime.datetime(2013, 12, 5, 0, 0)
102     >>> task['tags']
103     ['work', 'servers']
104
105 The following fields are deserialized into Python objects:
106
107 * ``due``: deserialized to a ``datetime`` object
108 * ``annotations``: deserialized to a list of dictionaries, where the ``entry``
109   field is a ``datetime`` object
110 * ``tags``: deserialized to a list
111
112 Attributes should be set using the correct Python representation, which will be
113 serialized into the correct format when the task is saved.
114
115 Saving Tasks
116 ------------
117
118 After modifying one or more attributes, simple call ``save()`` to write those
119 changes to the database::
120
121     >>> task = tw.tasks.pending().filter(tags__contain='work').get()
122     >>> task['due'] = datetime(year=2014, month=1, day=5)
123     >>> task.save()
124
125 To mark a task as complete, use ``done()``::
126
127     >>> task = tw.tasks.pending().filter(tags__contain='work').get()
128     >>> task.done()
129     >>> len(tw.tasks.pending().filter(tags__contain='work'))
130     0
131
132 .. _taskwarrior: http://taskwarrior.org