documentation on the requirements and docstring updates

tiramisu/setting.py

@@ -242,7 +242,8 @@ class Settings(object):
             props = self._p_.getproperties(path, default_properties)
         else:
             if path is None:
-                raise ValueError(_('if opt is not None, path should not be None in _getproperties'))
+                raise ValueError(_('if opt is not None, path should not be'
+                                   ' None in _getproperties'))
             ntime = None
             if self._p_.hascache('property', path):
                 ntime = time()
@@ -287,13 +288,15 @@ class Settings(object):
         validation upon the properties related to `opt_or_descr`
 
         :param opt_or_descr: an option or an option description object
-        :param force_permissive: behaves as if the permissive property was present
+        :param force_permissive: behaves as if the permissive property
+                                 was present
         :param is_descr: we have to know if we are in an option description,
-                         just because the mandatory property doesn't exist there
+                         just because the mandatory property
+                         doesn't exist here
 
         :param is_write: in the validation process, an option is to be modified,
-                         the behavior can be different (typically with the `frozen`
-                         property)
+                         the behavior can be different
+                         (typically with the `frozen` property)
         """
         # opt properties
         properties = copy(self._getproperties(opt_or_descr, path))
@@ -374,12 +377,55 @@ class Settings(object):
             self._p_.reset_all_cache('property')
 
     def apply_requires(self, opt, path):
-        "carries out the jit (just in time requirements between options"
+        """carries out the jit (just in time) requirements between options
+        
+        a requirement is a tuple of this form that comes from the option's 
+        requirements validation::
+
+            (option, expected, action, inverse, transitive, same_action)
+
+        let's have a look at all the tuple's items:
+        
+        - **option** is the target option's name or path
+        
+        - **expected** is the target option's value that is going to trigger an action
+        
+        - **action** is the (property) action to be accomplished if the target option 
+          happens to have the expected value
+        
+        - if **inverse** is `True` and if the target option's value does not 
+          apply, then the property action must be removed from the option's 
+          properties list (wich means that the property is inverted)
+          
+        - **transitive**: but what happens if the target option cannot be 
+          accessed ? We don't kown the target option's value. Actually if some 
+          property in the target option is not present in the permissive, the 
+          target option's value cannot be accessed. In this case, the 
+          **action** have to be applied to the option. (the **action** property 
+          is then added to the option).
+        
+        - **same_action**: actually, if **same_action** is `True`, the 
+          transitivity is not accomplished. The transitivity is accomplished 
+          only if the target option **has the same property** that the demanded 
+          action. If the target option's value is not accessible because of 
+          another reason, because of a property of another type, then an 
+          exception :exc:`~error.RequirementError` is raised.
+
+        And at last, if no target option matches the expected values, the 
+        action must be removed from the option's properties list.
+        
+        :param opt: the option on wich the requirement occurs
+        :type opt: `option.Option()`
+        :param path: the option's path in the config
+        :type path: str
+        """
         if opt._requires is None:
             return
 
         # filters the callbacks
-        setting = Property(self, self._getproperties(opt, path, False), opt, path=path)
+        setting = Property(self,
+                           self._getproperties(opt, path, False),
+                           opt, path=path)
         for requires in opt._requires:
             matches = False
             for require in requires:
@@ -392,7 +438,8 @@ class Settings(object):
                                              " '{0}' with requirement on: "
                                              "'{1}'").format(path, reqpath))
                 try:
-                    value = self.context._getattr(reqpath, force_permissive=True)
+                    value = self.context._getattr(reqpath,
+                                                  force_permissive=True)
                 except PropertiesOptionError, err:
                     if not transitive:
                         continue