Docs: Document the original attribute access to the task object

[etc/taskwarrior.git] / tasklib / task.py

diff --git a/tasklib/task.py b/tasklib/task.py
index ca21b2bec2caa25f6683f9d1f511ce297e7affbf..537c79291363edee5e2dec8679c2873af936fe17 100644 (file)
--- a/tasklib/task.py
+++ b/tasklib/task.py
@@ -28,6 +28,40 @@ class TaskWarriorException(Exception):
     pass
 
 
     pass
 
 

+class ReadOnlyDictView(object):
+    """
+    Provides simplified read-only view upon dict object.
+    """
+
+    def __init__(self, viewed_dict):
+        self.viewed_dict = viewed_dict
+
+    def __getitem__(self, key):
+        return copy.deepcopy(self.viewed_dict.__getitem__(key))
+
+    def __contains__(self, k):
+        return self.viewed_dict.__contains__(k)
+
+    def __iter__(self):
+        for value in self.viewed_dict:
+            yield copy.deepcopy(value)
+
+    def __len__(self):
+        return len(self.viewed_dict)
+
+    def get(self, key, default=None):
+        return copy.deepcopy(self.viewed_dict.get(key, default))
+
+    def has_key(self, key):
+        return self.viewed_dict.has_key(key)
+
+    def items(self):
+        return [copy.deepcopy(v) for v in self.viewed_dict.items()]
+
+    def values(self):
+        return [copy.deepcopy(v) for v in self.viewed_dict.values()]
+
+

 class SerializingObject(object):
     """
     Common ancestor for TaskResource & TaskFilter, since they both
 class SerializingObject(object):
     """
     Common ancestor for TaskResource & TaskFilter, since they both


@@ -44,6 +78,15 @@ class SerializingObject(object):
         not export empty-valued attributes) if the attribute
         is not iterable (e.g. list or set), in which case
         a empty iterable should be used.
         not export empty-valued attributes) if the attribute
         is not iterable (e.g. list or set), in which case
         a empty iterable should be used.

+
+    Normalizing methods should hold the following contract:
+      - They are used to validate and normalize the user input.
+        Any attribute value that comes from the user (during Task
+        initialization, assignign values to Task attributes, or
+        filtering by user-provided values of attributes) is first
+        validated and normalized using the normalize_{key} method.
+      - If validation or normalization fails, normalizer is expected
+        to raise ValueError.

     """
 
     def _deserialize(self, key, value):
     """
 
     def _deserialize(self, key, value):


@@ -93,36 +136,54 @@ class SerializingObject(object):
     def deserialize_entry(self, value):
         return self.timestamp_deserializer(value)
 
     def deserialize_entry(self, value):
         return self.timestamp_deserializer(value)
 

+    def normalize_entry(self, value):
+        return self.datetime_normalizer(value)
+

     def serialize_modified(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_modified(self, value):
         return self.timestamp_deserializer(value)
 
     def serialize_modified(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_modified(self, value):
         return self.timestamp_deserializer(value)
 

+    def normalize_modified(self, value):
+        return self.datetime_normalizer(value)
+

     def serialize_due(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_due(self, value):
         return self.timestamp_deserializer(value)
 
     def serialize_due(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_due(self, value):
         return self.timestamp_deserializer(value)
 

+    def normalize_due(self, value):
+        return self.datetime_normalizer(value)
+

     def serialize_scheduled(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_scheduled(self, value):
         return self.timestamp_deserializer(value)
 
     def serialize_scheduled(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_scheduled(self, value):
         return self.timestamp_deserializer(value)
 

+    def normalize_scheduled(self, value):
+        return self.datetime_normalizer(value)
+

     def serialize_until(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_until(self, value):
         return self.timestamp_deserializer(value)
 
     def serialize_until(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_until(self, value):
         return self.timestamp_deserializer(value)
 

+    def normalize_until(self, value):
+        return self.datetime_normalizer(value)
+

     def serialize_wait(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_wait(self, value):
         return self.timestamp_deserializer(value)
 
     def serialize_wait(self, value):
         return self.timestamp_serializer(value)
 
     def deserialize_wait(self, value):
         return self.timestamp_deserializer(value)
 

+    def normalize_wait(self, value):
+        return self.datetime_normalizer(value)
+

     def serialize_annotations(self, value):
         value = value if value is not None else []
 
     def serialize_annotations(self, value):
         value = value if value is not None else []
 


@@ -153,7 +214,7 @@ class SerializingObject(object):
         uuids = raw_uuids.split(',')
         return set(self.warrior.tasks.get(uuid=uuid) for uuid in uuids if uuid)
 
         uuids = raw_uuids.split(',')
         return set(self.warrior.tasks.get(uuid=uuid) for uuid in uuids if uuid)
 

-    def normalize_datetime(self, value):
+    def datetime_normalizer(self, value):

         """
         Normalizes date/datetime value (considered to come from user input)
         to localized datetime value. Following conversions happen:
         """
         Normalizes date/datetime value (considered to come from user input)
         to localized datetime value. Following conversions happen:


@@ -177,7 +238,13 @@ class SerializingObject(object):
             localized = value
         
         return localized
             localized = value
         
         return localized

-            
+
+    def normalize_uuid(self, value):
+        # Enforce sane UUID
+        if not isinstance(value, six.text_type) or value == '':
+            raise ValueError("UUID must be a valid non-empty string.")
+
+        return value

 
 
 class TaskResource(SerializingObject):
 
 
 class TaskResource(SerializingObject):


@@ -221,11 +288,8 @@ class TaskResource(SerializingObject):
         if key in self.read_only_fields:
             raise RuntimeError('Field \'%s\' is read-only' % key)
 
         if key in self.read_only_fields:
             raise RuntimeError('Field \'%s\' is read-only' % key)
 

-        # Localize any naive date/datetime to the detected timezone
-        if (isinstance(value, datetime.datetime) or
-            isinstance(value, datetime.date)):
-            value = self.normalize_datetime(value)
-
+        # Normalize the user input before saving it
+        value = self._normalize(key, value)

         self._data[key] = value
 
     def __str__(self):
         self._data[key] = value
 
     def __str__(self):


@@ -369,6 +433,9 @@ class Task(TaskResource):
                           for (key, value) in six.iteritems(kwargs))
         self._original_data = copy.deepcopy(self._data)
 
                           for (key, value) in six.iteritems(kwargs))
         self._original_data = copy.deepcopy(self._data)
 

+        # Provide read only access to the original data
+        self.original = ReadOnlyDictView(self._original_data)
+

     def __unicode__(self):
         return self['description']
 
     def __unicode__(self):
         return self['description']
 


@@ -593,12 +660,8 @@ class TaskFilter(SerializingObject):
         # convention in TW for empty values
         attribute_key = key.split('.')[0]
 
         # convention in TW for empty values
         attribute_key = key.split('.')[0]
 

-        # Since this is user input, we need to normalize datetime
-        # objects
-        if (isinstance(value, datetime.datetime) or
-            isinstance(value, datetime.date)):
-            value = self.normalize_datetime(value)
-
+        # Since this is user input, we need to normalize before we serialize
+        value = self._normalize(key, value)

         value = self._serialize(attribute_key, value)
 
         # If we are filtering by uuid:, do not use uuid keyword
         value = self._serialize(attribute_key, value)
 
         # If we are filtering by uuid:, do not use uuid keyword


@@ -766,14 +829,14 @@ class TaskWarrior(object):
         stdout, stderr = [x.decode('utf-8') for x in p.communicate()]
         return stdout.strip('\n')
 
         stdout, stderr = [x.decode('utf-8') for x in p.communicate()]
         return stdout.strip('\n')
 

-    def execute_command(self, args, config_override={}):
+    def execute_command(self, args, config_override={}, allow_failure=True):

         command_args = self._get_command_args(
             args, config_override=config_override)
         logger.debug(' '.join(command_args))
         p = subprocess.Popen(command_args, stdout=subprocess.PIPE,
                              stderr=subprocess.PIPE)
         stdout, stderr = [x.decode('utf-8') for x in p.communicate()]
         command_args = self._get_command_args(
             args, config_override=config_override)
         logger.debug(' '.join(command_args))
         p = subprocess.Popen(command_args, stdout=subprocess.PIPE,
                              stderr=subprocess.PIPE)
         stdout, stderr = [x.decode('utf-8') for x in p.communicate()]

-        if p.returncode:
+        if p.returncode and allow_failure:

             if stderr.strip():
                 error_msg = stderr.strip().splitlines()[-1]
             else:
             if stderr.strip():
                 error_msg = stderr.strip().splitlines()[-1]
             else:


@@ -781,7 +844,15 @@ class TaskWarrior(object):
             raise TaskWarriorException(error_msg)
         return stdout.strip().split('\n')
 
             raise TaskWarriorException(error_msg)
         return stdout.strip().split('\n')
 

+    def enforce_recurrence(self):
+        # Run arbitrary report command which will trigger generation
+        # of recurrent tasks.
+        # TODO: Make a version dependant enforcement once
+        #       TW-1531 is handled
+        self.execute_command(['next'], allow_failure=False)
+

     def filter_tasks(self, filter_obj):
     def filter_tasks(self, filter_obj):

+        self.enforce_recurrence()

         args = ['export', '--'] + filter_obj.get_filter_params()
         tasks = []
         for line in self.execute_command(args):
         args = ['export', '--'] + filter_obj.get_filter_params()
         tasks = []
         for line in self.execute_command(args):