README.rst

   1 tasklib
   2 =======
   3
   4 .. image:: https://travis-ci.org/robgolding63/tasklib.png
   5     :target: http://travis-ci.org/robgolding63/tasklib
   6
   7 A Python library for interacting with taskwarrior_ databases, using a queryset
   8 API similar to that of Django's ORM.
   9
  10 Supports Python 2.6, 2.7, 3.2 and 3.3 with taskwarrior 2.2.0. Older versions of
  11 taskwarrior are untested and probably won't work.
  12
  13 Requirements
  14 ------------
  15
  16 * taskwarrior_ v2.2.0
  17
  18 Installation
  19 ------------
  20
  21 Install via pip::
  22
  23     pip install tasklib
  24
  25 Usage
  26 -----
  27
  28 .. source-code:
  29
  30     >>> from tasklib.task import TaskWarrior
  31
  32     >>> tw = TaskWarrior('/home/rob/.task')
  33     >>> tasks = tw.tasks.pending()
  34     >>> tasks
  35     ['Tidy the house', 'Learn German']
  36     >>> tasks.filter(tags__contain='chores')
  37     ['Tidy the house']
  38     >>> type(tasks[0])
  39     <class 'tasklib.task.Task'>
  40     >>> task[0].done()
  41
  42 Filtering Tasks
  43 ---------------
  44
  45 Tasks can be filtered using the ``TaskQuerySet`` API which emulates the
  46 Django ORM::
  47
  48     >>> tw.tasks.filter(status='pending', tags__contain='work')
  49     ['Upgrade Ubuntu Server']
  50
  51 Filter arguments are passed to the ``task`` command (``__`` is replaced by
  52 a period); so the above example is equivalent to the following command::
  53
  54     $ task status:pending tags.contain=work
  55
  56 .. _taskwarrior: http://taskwarrior.org
  57
  58 Tasks can also be filtered using raw commands, like so::
  59
  60     >>> tw.tasks.filter('status:pending +work')
  61     ['Upgrade Ubuntu Server']