From: Tomas Babej <tomasbabej@gmail.com>
Date: Sat, 7 Feb 2015 12:50:33 +0000 (+0100)
Subject: SerializingObject: Document purpose of normalizing methods
X-Git-Url: https://git.madduck.net/etc/taskwarrior.git/commitdiff_plain/96cd505ef5e22acc9707b3497449a9dfdf6dfc5e

SerializingObject: Document purpose of normalizing methods
---

diff --git a/tasklib/task.py b/tasklib/task.py
index 17af8d4..537c792 100644
--- 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):