documentation update and docstrings

tiramisu/value.py

@@ -67,7 +67,7 @@ class Values(object):
         "return value or default value if not set"
         key = self._getkey(opt)
         if not self._p_.hasvalue(key):
-            #if no value
+            # if no value
             value = self._getdefault(opt)
             if opt.impl_is_multi():
                 value = Multi(value, self.context, opt, validate)
@@ -75,7 +75,7 @@ class Values(object):
             #if value
             value = self._p_.getvalue(key)
             if opt.impl_is_multi() and not isinstance(value, Multi):
-                #load value so don't need to validate if is not a Multi
+                # load value so don't need to validate if is not a Multi
                 value = Multi(value, self.context, opt, validate=False)
         return value
 
@@ -86,6 +86,10 @@ class Values(object):
         return self._p_.hasvalue('value', self._getkey(opt))
 
     def __delitem__(self, opt):
+        """overrides the builtins `del()` instructions 
+        
+        if you use this you are responsible for all bad things happening
+        """
         self.reset(opt)
 
     def reset(self, opt):
@@ -173,7 +177,7 @@ class Values(object):
                         value = [value for i in range(lenmaster)]
             if opt.impl_is_multi():
                 value = Multi(value, self.context, opt, validate)
-            #suppress value if already set
+            # suppress value if already set
             self.reset(opt)
         # frozen and force default
         elif is_frozen and 'force_default_on_freeze' in setting[opt]:
@@ -197,9 +201,9 @@ class Values(object):
         self.setitem(opt, value)
 
     def setitem(self, opt, value, force_permissive=False, is_write=True):
-        #is_write is, for example, used with "force_store_value"
-        #user didn't change value, so not write
-        #valid opt
+        # is_write is, for example, used with "force_store_value"
+        # user didn't change value, so not write
+        # valid opt
         opt.impl_validate(value, self.context,
                           'validator' in self.context.cfgimpl_get_settings())
         if opt.impl_is_multi() and not isinstance(value, Multi):
@@ -221,6 +225,12 @@ class Values(object):
         self._p_.setvalue(self._getkey(opt), value, owner)
 
     def getowner(self, opt):
+        """
+        retrieves the option's owner
+        
+        :param opt: the `option.Option` object 
+        :returns: a `setting.owners.Owner` object
+        """
         if isinstance(opt, SymLinkOption):
             opt = opt._opt
         owner = self._p_.getowner(self._getkey(opt), owners.default)
@@ -230,6 +240,12 @@ class Values(object):
         return owner
 
     def setowner(self, opt, owner):
+        """
+        sets a owner to an option
+        
+        :param opt: the `option.Option` object 
+        :param owner: a valid owner, that is a `setting.owners.Owner` object
+        """
         if not isinstance(owner, owners.Owner):
             raise TypeError(_("invalid generic owner {0}").format(str(owner)))
         if self.getowner(opt) == owners.default:
@@ -246,12 +262,21 @@ class Values(object):
         return self.getowner(opt) == owners.default
 
     def reset_cache(self, only_expired):
+        """
+        clears the cache if necessary
+        """
         if only_expired:
             self._p_.reset_expired_cache('value', time())
         else:
             self._p_.reset_all_cache('value')
 
     def _get_opt_path(self, opt):
+        """
+        retrieve the option's path in the config 
+        
+        :param opt: the `option.Option` object 
+        :returns: a string with points like "gc.dummy.my_option"
+        """
         return self.context.cfgimpl_get_description().impl_get_path_by_opt(opt)
 
 # ____________________________________________________________