tasklib/task.py

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