SerializingObject: Document purpose of normalizing methods

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

diff --git a/tasklib/task.py b/tasklib/task.py
index dc2746020e8a98bf62df91ceb4d35fd3bea1757a..537c79291363edee5e2dec8679c2873af936fe17 100644 (file)
--- a/tasklib/task.py
+++ b/tasklib/task.py
@@ -78,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.
+
+    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):
@@ -424,6 +433,9 @@ class Task(TaskResource):
                           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']