documentation update and docstrings

tiramisu/setting.py

@@ -184,6 +184,15 @@ class Settings(object):
     __slots__ = ('context', '_owner', '_p_')
 
     def __init__(self, context, storage):
+        """
+        initializer 
+        
+        :param context: the root config
+        :param storage: the storage type 
+                        
+                        - dictionnary -> in memory 
+                        - sqlite3 -> persistent
+        """
         # generic owner
         self._owner = owners.user
         self.context = context
@@ -203,6 +212,7 @@ class Settings(object):
     #____________________________________________________________
     # properties methods
     def __contains__(self, propname):
+        "enables the pythonic 'in' syntaxic sugar" 
         return propname in self._getproperties()
 
     def __repr__(self):
@@ -280,11 +290,11 @@ class Settings(object):
                          the behavior can be different (typically with the `frozen`
                          property)
         """
-        #opt properties
+        # opt properties
         properties = copy(self._getproperties(opt_or_descr))
-        #remove opt permissive
+        # remove opt permissive
         properties -= self._p_.getpermissive(self._getkey(opt_or_descr))
-        #remove global permissive if need
+        # remove global permissive if need
         self_properties = copy(self._getproperties())
         if force_permissive is True or 'permissive' in self_properties:
             properties -= self._p_.getpermissive()
@@ -322,7 +332,7 @@ class Settings(object):
                                               "").format(opt_or_descr._name,
                                                          str(props)), props)
 
-    #FIXME should be setpermissive
+    # XXX should rename it to setpermissive, but kept for retro compatibility 
     def set_permissive(self, permissive, opt=None):
         if not isinstance(permissive, tuple):
             raise TypeError(_('permissive must be a tuple'))
@@ -392,7 +402,7 @@ class Settings(object):
                                                  "{1} {2}").format(opt._name,
                                                                    path,
                                                                    properties))
-                    #transitive action, force expected
+                    # transitive action, force expected
                     value = expected[0]
                     inverse = False
                 except AttributeError:
@@ -403,7 +413,7 @@ class Settings(object):
                         inverse and value not in expected):
                     matches = True
                     setting.append(action)
-                    ## the calculation cannot be carried out
+                    # the calculation cannot be carried out
                     break
             # no requirement has been triggered, then just reverse the action
             if not matches: