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

8b6b458fe7588089e71c687e145169d01dcc3759
[etc/taskwarrior.git] / docs / index.rst
1 Welcome to tasklib's documentation!
2 ===================================
3
4 Requirements
5 ------------
6
7 * taskwarrior_ v2.2.0 or v2.3.0 beta2
8
9 Installation
10 ------------
11
12 Install via pip (recommended)::
13
14     pip install tasklib
15
16 Or clone from github::
17
18     git clone https://github.com/robgolding63/tasklib.git
19     cd tasklib
20     python setup.py install
21
22 Initialization
23 --------------
24
25 Optionally initialize the ``TaskWarrior`` instance with ``data_location`` (the
26 database directory). If it doesn't already exist, this will be created
27 automatically unless ``create=False``.
28
29 The default location is the same as taskwarrior's::
30
31     >>> tw = TaskWarrior(data_location='~/.task', create=True)
32
33 Retrieving Tasks
34 ----------------
35
36 ``tw.tasks`` is a ``TaskQuerySet`` object which emulates the Django QuerySet
37 API. To get all tasks (including completed ones)::
38
39     >>> tw.tasks.all()
40
41 Filtering
42 ---------
43
44 Filter tasks using the same familiar syntax::
45
46     >>> tw.tasks.filter(status='pending', tags__contain='work')
47     ['Upgrade Ubuntu Server']
48
49 Filter arguments are passed to the ``task`` command (``__`` is replaced by
50 a period) so the above example is equivalent to the following command::
51
52     $ task status:pending tags.contain=work
53
54 Tasks can also be filtered using raw commands, like so::
55
56     >>> tw.tasks.filter('status:pending +work')
57     ['Upgrade Ubuntu Server']
58
59 There are built-in functions for retrieving pending & completed tasks::
60
61     >>> tw.tasks.pending().filter(tags__contain='work')
62     ['Upgrade Ubuntu Server']
63     >>> len(tw.tasks.completed())
64     227
65
66 Use ``get()`` to return the only task in a ``TaskQuerySet``, or raise an
67 exception::
68
69     >>> tw.tasks.filter(status='pending', tags__contain='work').get()
70     'Upgrade Ubuntu Server'
71     >>> tw.tasks.filter(status='pending', tags__contain='work').get(status='completed')
72     Traceback (most recent call last):
73       File "<stdin>", line 1, in <module>
74       File "tasklib/task.py", line 224, in get
75         'Lookup parameters were {0}'.format(kwargs))
76     tasklib.task.DoesNotExist: Task matching query does not exist. Lookup parameters were {'status': 'completed'}
77     >>> tw.tasks.filter(status='pending', tags__contain='home').get()
78     Traceback (most recent call last):
79       File "<stdin>", line 1, in <module>
80       File "tasklib/task.py", line 227, in get
81         'Lookup parameters were {1}'.format(num, kwargs))
82     ValueError: get() returned more than one Task -- it returned 2! Lookup parameters were {}
83
84 Task Attributes
85 ---------------
86
87 Attributes of task objects are accessible through indices, like so::
88
89     >>> task = tw.tasks.pending().filter(tags__contain='work').get()
90     >>> task['description']
91     'Upgrade Ubuntu Server'
92     >>> task['id']
93     15
94     >>> task['due']
95     datetime.datetime(2013, 12, 5, 0, 0)
96     >>> task['tags']
97     ['work', 'servers']
98
99 The following fields are deserialized into Python objects:
100
101 * ``due``: deserialized to a ``datetime`` object
102 * ``annotations``: deserialized to a list of dictionaries, where the ``entry``
103   field is a ``datetime`` object
104 * ``tags``: deserialized to a list
105
106 Attributes should be set using the correct Python representation, which will be
107 serialized into the correct format when the task is saved.
108
109 Saving Tasks
110 ------------
111
112 After modifying one or more attributes, simple call ``save()`` to write those
113 changes to the database::
114
115     >>> task = tw.tasks.pending().filter(tags__contain='work').get()
116     >>> task['due'] = datetime(year=2014, month=1, day=5)
117     >>> task.save()
118
119 To mark a task as complete, use ``done()``::
120
121     >>> task = tw.tasks.pending().filter(tags__contain='work').get()
122     >>> task.done()
123     >>> len(tw.tasks.pending().filter(tags__contain='work'))
124     0