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