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