tasklib/task.py

   1 from __future__ import print_function
   2 import copy
   3 import importlib
   4 import json
   5 import logging
   6 import os
   7 import six
   8 import sys
   9
  10 from .serializing import SerializingObject
  11
  12 DATE_FORMAT = '%Y%m%dT%H%M%SZ'
  13 REPR_OUTPUT_SIZE = 10
  14 PENDING = 'pending'
  15 COMPLETED = 'completed'
  16 DELETED = 'deleted'
  17 WAITING = 'waiting'
  18 RECURRING = 'recurring'
  19
  20 logger = logging.getLogger(__name__)
  21
  22
  23 class ReadOnlyDictView(object):
  24     """
  25     Provides simplified read-only view upon dict object.
  26     """
  27
  28     def __init__(self, viewed_dict):
  29         self.viewed_dict = viewed_dict
  30
  31     def __getitem__(self, key):
  32         return copy.deepcopy(self.viewed_dict.__getitem__(key))
  33
  34     def __contains__(self, k):
  35         return self.viewed_dict.__contains__(k)
  36
  37     def __iter__(self):
  38         for value in self.viewed_dict:
  39             yield copy.deepcopy(value)
  40
  41     def __len__(self):
  42         return len(self.viewed_dict)
  43
  44     def __unicode__(self):
  45         return six.u('ReadOnlyDictView: {0}'.format(repr(self.viewed_dict)))
  46
  47     __repr__ = __unicode__
  48
  49     def get(self, key, default=None):
  50         return copy.deepcopy(self.viewed_dict.get(key, default))
  51
  52     def items(self):
  53         return [copy.deepcopy(v) for v in self.viewed_dict.items()]
  54
  55     def values(self):
  56         return [copy.deepcopy(v) for v in self.viewed_dict.values()]
  57
  58
  59 class TaskResource(SerializingObject):
  60     read_only_fields = []
  61
  62     def _load_data(self, data):
  63         self._data = dict((key, self._deserialize(key, value))
  64                           for key, value in data.items())
  65         # We need to use a copy for original data, so that changes
  66         # are not propagated.
  67         self._original_data = copy.deepcopy(self._data)
  68
  69     def _update_data(self, data, update_original=False, remove_missing=False):
  70         """
  71         Low level update of the internal _data dict. Data which are coming as
  72         updates should already be serialized. If update_original is True, the
  73         original_data dict is updated as well.
  74         """
  75         self._data.update(dict((key, self._deserialize(key, value))
  76                                for key, value in data.items()))
  77
  78         # In certain situations, we want to treat missing keys as removals
  79         if remove_missing:
  80             for key in set(self._data.keys()) - set(data.keys()):
  81                 self._data[key] = None
  82
  83         if update_original:
  84             self._original_data = copy.deepcopy(self._data)
  85
  86     def __getitem__(self, key):
  87         # This is a workaround to make TaskResource non-iterable
  88         # over simple index-based iteration
  89         try:
  90             int(key)
  91             raise StopIteration
  92         except ValueError:
  93             pass
  94
  95         if key not in self._data:
  96             self._data[key] = self._deserialize(key, None)
  97
  98         return self._data.get(key)
  99
 100     def __setitem__(self, key, value):
 101         if key in self.read_only_fields:
 102             raise RuntimeError('Field \'%s\' is read-only' % key)
 103
 104         # Normalize the user input before saving it
 105         value = self._normalize(key, value)
 106         self._data[key] = value
 107
 108     def __str__(self):
 109         s = six.text_type(self.__unicode__())
 110         if not six.PY3:
 111             s = s.encode('utf-8')
 112         return s
 113
 114     def __repr__(self):
 115         return str(self)
 116
 117     def export_data(self):
 118         """
 119         Exports current data contained in the Task as JSON
 120         """
 121
 122         # We need to remove spaces for TW-1504, use custom separators
 123         data_tuples = ((key, self._serialize(key, value))
 124                        for key, value in six.iteritems(self._data))
 125
 126         # Empty string denotes empty serialized value, we do not want
 127         # to pass that to TaskWarrior.
 128         data_tuples = filter(lambda t: t[1] is not '', data_tuples)
 129         data = dict(data_tuples)
 130         return json.dumps(data, separators=(',', ':'))
 131
 132     @property
 133     def _modified_fields(self):
 134         writable_fields = set(self._data.keys()) - set(self.read_only_fields)
 135         for key in writable_fields:
 136             new_value = self._data.get(key)
 137             old_value = self._original_data.get(key)
 138
 139             # Make sure not to mark data removal as modified field if the
 140             # field originally had some empty value
 141             if key in self._data and not new_value and not old_value:
 142                 continue
 143
 144             if new_value != old_value:
 145                 yield key
 146
 147     @property
 148     def modified(self):
 149         return bool(list(self._modified_fields))
 150
 151
 152 class TaskAnnotation(TaskResource):
 153     read_only_fields = ['entry', 'description']
 154
 155     def __init__(self, task, data=None):
 156         self.task = task
 157         self._load_data(data or dict())
 158         super(TaskAnnotation, self).__init__(task.backend)
 159
 160     def remove(self):
 161         self.task.remove_annotation(self)
 162
 163     def __unicode__(self):
 164         return self['description']
 165
 166     def __eq__(self, other):
 167         # consider 2 annotations equal if they belong to the same task, and
 168         # their data dics are the same
 169         return self.task == other.task and self._data == other._data
 170
 171     def __ne__(self, other):
 172         return not self.__eq__(other)
 173
 174     __repr__ = __unicode__
 175
 176
 177 class Task(TaskResource):
 178     read_only_fields = ['id', 'entry', 'urgency', 'uuid', 'modified']
 179
 180     class DoesNotExist(Exception):
 181         pass
 182
 183     class CompletedTask(Exception):
 184         """
 185         Raised when the operation cannot be performed on the completed task.
 186         """
 187         pass
 188
 189     class DeletedTask(Exception):
 190         """
 191         Raised when the operation cannot be performed on the deleted task.
 192         """
 193         pass
 194
 195     class ActiveTask(Exception):
 196         """
 197         Raised when the operation cannot be performed on the active task.
 198         """
 199         pass
 200
 201     class InactiveTask(Exception):
 202         """
 203         Raised when the operation cannot be performed on an inactive task.
 204         """
 205         pass
 206
 207     class NotSaved(Exception):
 208         """
 209         Raised when the operation cannot be performed on the task, because
 210         it has not been saved to TaskWarrior yet.
 211         """
 212         pass
 213
 214     @classmethod
 215     def from_input(cls, input_file=sys.stdin, modify=None, backend=None):
 216         """
 217         Creates a Task object, directly from the stdin, by reading one line.
 218         If modify=True, two lines are used, first line interpreted as the
 219         original state of the Task object, and second line as its new,
 220         modified value. This is consistent with the TaskWarrior's hook
 221         system.
 222
 223         Object created by this method should not be saved, deleted
 224         or refreshed, as t could create a infinite loop. For this
 225         reason, TaskWarrior instance is set to None.
 226
 227         Input_file argument can be used to specify the input file,
 228         but defaults to sys.stdin.
 229         """
 230
 231         # Detect the hook type if not given directly
 232         name = os.path.basename(sys.argv[0])
 233         modify = name.startswith('on-modify') if modify is None else modify
 234
 235         # Create the TaskWarrior instance if none passed
 236         if backend is None:
 237             backends = importlib.import_module('tasklib.backends')
 238             hook_parent_dir = os.path.dirname(os.path.dirname(sys.argv[0]))
 239             backend = backends.TaskWarrior(data_location=hook_parent_dir)
 240
 241         # TaskWarrior instance is set to None
 242         task = cls(backend)
 243
 244         # Load the data from the input
 245         task._load_data(json.loads(input_file.readline().strip()))
 246
 247         # If this is a on-modify event, we are provided with additional
 248         # line of input, which provides updated data
 249         if modify:
 250             task._update_data(json.loads(input_file.readline().strip()),
 251                               remove_missing=True)
 252
 253         return task
 254
 255     def __init__(self, backend, **kwargs):
 256         super(Task, self).__init__(backend)
 257
 258         # Check that user is not able to set read-only value in __init__
 259         for key in kwargs.keys():
 260             if key in self.read_only_fields:
 261                 raise RuntimeError('Field \'%s\' is read-only' % key)
 262
 263         # We serialize the data in kwargs so that users of the library
 264         # do not have to pass different data formats via __setitem__ and
 265         # __init__ methods, that would be confusing
 266
 267         # Rather unfortunate syntax due to python2.6 comaptiblity
 268         self._data = dict((key, self._normalize(key, value))
 269                           for (key, value) in six.iteritems(kwargs))
 270         self._original_data = copy.deepcopy(self._data)
 271
 272         # Provide read only access to the original data
 273         self.original = ReadOnlyDictView(self._original_data)
 274
 275     def __unicode__(self):
 276         return self['description']
 277
 278     def __eq__(self, other):
 279         if self['uuid'] and other['uuid']:
 280             # For saved Tasks, just define equality by equality of uuids
 281             return self['uuid'] == other['uuid']
 282         else:
 283             # If the tasks are not saved, compare the actual instances
 284             return id(self) == id(other)
 285
 286     def __ne__(self, other):
 287         return not self.__eq__(other)
 288
 289     def __hash__(self):
 290         if self['uuid']:
 291             # For saved Tasks, just define equality by equality of uuids
 292             return self['uuid'].__hash__()
 293         else:
 294             # If the tasks are not saved, return hash of instance id
 295             return id(self).__hash__()
 296
 297     @property
 298     def completed(self):
 299         return self['status'] == six.text_type('completed')
 300
 301     @property
 302     def deleted(self):
 303         return self['status'] == six.text_type('deleted')
 304
 305     @property
 306     def waiting(self):
 307         return self['status'] == six.text_type('waiting')
 308
 309     @property
 310     def pending(self):
 311         return self['status'] == six.text_type('pending')
 312
 313     @property
 314     def recurring(self):
 315         return self['status'] == six.text_type('recurring')
 316
 317     @property
 318     def active(self):
 319         return self['start'] is not None
 320
 321     @property
 322     def saved(self):
 323         return self['uuid'] is not None or self['id'] is not None
 324
 325     def serialize_depends(self, cur_dependencies):
 326         # Check that all the tasks are saved
 327         for task in (cur_dependencies or set()):
 328             if not task.saved:
 329                 raise Task.NotSaved(
 330                     'Task \'%s\' needs to be saved before '
 331                     'it can be set as dependency.' % task,
 332                 )
 333
 334         return super(Task, self).serialize_depends(cur_dependencies)
 335
 336     def delete(self):
 337         if not self.saved:
 338             raise Task.NotSaved(
 339                 'Task needs to be saved before it can be deleted',
 340             )
 341
 342         # Refresh the status, and raise exception if the task is deleted
 343         self.refresh(only_fields=['status'])
 344
 345         if self.deleted:
 346             raise Task.DeletedTask('Task was already deleted')
 347
 348         self.backend.delete_task(self)
 349
 350         # Refresh the status again, so that we have updated info stored
 351         self.refresh(only_fields=['status', 'start', 'end'])
 352
 353     def start(self):
 354         if not self.saved:
 355             raise Task.NotSaved(
 356                 'Task needs to be saved before it can be started',
 357             )
 358
 359         # Refresh, and raise exception if task is already completed/deleted
 360         self.refresh(only_fields=['status'])
 361
 362         if self.completed:
 363             raise Task.CompletedTask('Cannot start a completed task')
 364         elif self.deleted:
 365             raise Task.DeletedTask('Deleted task cannot be started')
 366         elif self.active:
 367             raise Task.ActiveTask('Task is already active')
 368
 369         self.backend.start_task(self)
 370
 371         # Refresh the status again, so that we have updated info stored
 372         self.refresh(only_fields=['status', 'start'])
 373
 374     def stop(self):
 375         if not self.saved:
 376             raise Task.NotSaved(
 377                 'Task needs to be saved before it can be stopped',
 378             )
 379
 380         # Refresh, and raise exception if task is already completed/deleted
 381         self.refresh(only_fields=['status'])
 382
 383         if not self.active:
 384             raise Task.InactiveTask('Cannot stop an inactive task')
 385
 386         self.backend.stop_task(self)
 387
 388         # Refresh the status again, so that we have updated info stored
 389         self.refresh(only_fields=['status', 'start'])
 390
 391     def done(self):
 392         if not self.saved:
 393             raise Task.NotSaved(
 394                 'Task needs to be saved before it can be completed',
 395             )
 396
 397         # Refresh, and raise exception if task is already completed/deleted
 398         self.refresh(only_fields=['status'])
 399
 400         if self.completed:
 401             raise Task.CompletedTask('Cannot complete a completed task')
 402         elif self.deleted:
 403             raise Task.DeletedTask('Deleted task cannot be completed')
 404
 405         self.backend.complete_task(self)
 406
 407         # Refresh the status again, so that we have updated info stored
 408         self.refresh(only_fields=['status', 'start', 'end'])
 409
 410     def save(self):
 411         if self.saved and not self.modified:
 412             return
 413
 414         # All the actual work is done by the backend
 415         self.backend.save_task(self)
 416
 417     def add_annotation(self, annotation):
 418         if not self.saved:
 419             raise Task.NotSaved('Task needs to be saved to add annotation')
 420
 421         self.backend.annotate_task(self, annotation)
 422         self.refresh(only_fields=['annotations'])
 423
 424     def remove_annotation(self, annotation):
 425         if not self.saved:
 426             raise Task.NotSaved('Task needs to be saved to remove annotation')
 427
 428         if isinstance(annotation, TaskAnnotation):
 429             annotation = annotation['description']
 430
 431         self.backend.denotate_task(self, annotation)
 432         self.refresh(only_fields=['annotations'])
 433
 434     def refresh(self, only_fields=None, after_save=False):
 435         # Raise error when trying to refresh a task that has not been saved
 436         if not self.saved:
 437             raise Task.NotSaved('Task needs to be saved to be refreshed')
 438
 439         new_data = self.backend.refresh_task(self, after_save=after_save)
 440
 441         if only_fields:
 442             to_update = dict(
 443                 [(k, new_data.get(k)) for k in only_fields],
 444             )
 445             self._update_data(to_update, update_original=True)
 446         else:
 447             self._load_data(new_data)
 448
 449
 450 class TaskQuerySet(object):
 451     """
 452     Represents a lazy lookup for a task objects.
 453     """
 454
 455     def __init__(self, backend, filter_obj=None):
 456         self.backend = backend
 457         self._result_cache = None
 458         self.filter_obj = filter_obj or self.backend.filter_class(backend)
 459
 460     def __deepcopy__(self, memo):
 461         """
 462         Deep copy of a QuerySet doesn't populate the cache
 463         """
 464         obj = self.__class__(backend=self.backend)
 465         for k, v in self.__dict__.items():
 466             if k in ('_iter', '_result_cache'):
 467                 obj.__dict__[k] = None
 468             else:
 469                 obj.__dict__[k] = copy.deepcopy(v, memo)
 470         return obj
 471
 472     def __repr__(self):
 473         data = list(self[:REPR_OUTPUT_SIZE + 1])
 474         if len(data) > REPR_OUTPUT_SIZE:
 475             data[-1] = '...(remaining elements truncated)...'
 476         return repr(data)
 477
 478     def __len__(self):
 479         if self._result_cache is None:
 480             self._result_cache = list(self)
 481         return len(self._result_cache)
 482
 483     def __iter__(self):
 484         if self._result_cache is None:
 485             self._result_cache = self._execute()
 486         return iter(self._result_cache)
 487
 488     def __getitem__(self, k):
 489         if self._result_cache is None:
 490             self._result_cache = list(self)
 491         return self._result_cache.__getitem__(k)
 492
 493     def __bool__(self):
 494         if self._result_cache is not None:
 495             return bool(self._result_cache)
 496         try:
 497             next(iter(self))
 498         except StopIteration:
 499             return False
 500         return True
 501
 502     def __nonzero__(self):
 503         return type(self).__bool__(self)
 504
 505     def _clone(self, klass=None, **kwargs):
 506         if klass is None:
 507             klass = self.__class__
 508         filter_obj = self.filter_obj.clone()
 509         c = klass(backend=self.backend, filter_obj=filter_obj)
 510         c.__dict__.update(kwargs)
 511         return c
 512
 513     def _execute(self):
 514         """
 515         Fetch the tasks which match the current filters.
 516         """
 517         return self.backend.filter_tasks(self.filter_obj)
 518
 519     def all(self):
 520         """
 521         Returns a new TaskQuerySet that is a copy of the current one.
 522         """
 523         return self._clone()
 524
 525     def pending(self):
 526         return self.filter(status=PENDING)
 527
 528     def completed(self):
 529         return self.filter(status=COMPLETED)
 530
 531     def deleted(self):
 532         return self.filter(status=DELETED)
 533
 534     def waiting(self):
 535         return self.filter(status=WAITING)
 536
 537     def recurring(self):
 538         return self.filter(status=RECURRING)
 539
 540     def filter(self, *args, **kwargs):
 541         """
 542         Returns a new TaskQuerySet with the given filters added.
 543         """
 544         clone = self._clone()
 545         for f in args:
 546             clone.filter_obj.add_filter(f)
 547         for key, value in kwargs.items():
 548             clone.filter_obj.add_filter_param(key, value)
 549         return clone
 550
 551     def get(self, **kwargs):
 552         """
 553         Performs the query and returns a single object matching the given
 554         keyword arguments.
 555         """
 556         clone = self.filter(**kwargs)
 557         num = len(clone)
 558         if num == 1:
 559             return clone._result_cache[0]
 560         if not num:
 561             raise Task.DoesNotExist(
 562                 'Task matching query does not exist. '
 563                 'Lookup parameters were {0}'.format(kwargs),
 564             )
 565         raise ValueError(
 566             'get() returned more than one Task -- it returned {0}! '
 567             'Lookup parameters were {1}'.format(num, kwargs),
 568         )