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