documentation update and docstrings

doc/consistency.txt

@@ -47,8 +47,7 @@ third one is the callback's action name (`hide`, `show`...)::
     stroption = StrOption('str', 'Test string option', default="abc",
                           requires=[('int', 1, 'hide')])
 
-Take a look at an example here
+Requirements are validated in :class:`setting.Setting`. 
-`test_option_consistency.test_hidden_if_in()`
 
 Validation upon a whole configuration object
 ----------------------------------------------

doc/glossary.txt

@@ -10,8 +10,6 @@ Glossary
         Global configuration object, wich contains the whole configuration
         options *and* their descriptions (option types and group)
 
-.. glossary::
-
     schema
     option description
 
@@ -24,14 +22,15 @@ Glossary
         - how they are organised in groups or even subgroups, that's why we
           call them **groups** too.
 
-.. glossary::
-
     configuration option
 
         An option object wich has a name and a value and can be accessed
         from the configuration object
 
-.. glossary::
+    access rules
+
+        Global access rules are : :meth:`~config.CommonConfig.read_write()` or
+        :meth:`~config.Config.read_only()`, see :doc:`status`
 
     default value
 
@@ -39,69 +38,49 @@ Glossary
         set at instanciation time, or even at any moment. Remember that if
         you reset the default value, the owner reset to `default`
 
-.. glossary::
-
-    acces rules
-
-        Access rules are : `config.Config.read_write()` or
-        `config.Config.read_only()`, see :doc:`status`
-
-.. glossary::
-
     freeze
 
         A whole configuration can be frozen (used in read only access). See
-        `status#frozenconfig` for details.
+        :ref:`frozen` for details.
 
         A single option can be frozen too.
 
-.. glossary::
-
-    forced on freeze
-
-        A single option is frozen and we want the option to return something
-        else than his value, typically his default value, see
-        `status#frozen`
-
-.. glossary::
-
     value owner
 
         When an option is modified, including at the instanciation, we
         always know who has modified it. It's the owner of the option, see
         :doc:`status` for more details.
 
-.. glossary::
-
     option with properties
 
         an option wich has property like 'hidden' or 'disabled' is an option
         wich has restricted acces rules
 
-.. glossary::
-
     hidden option
 
         a hidden option has a different behaviour on regards to the access
         of the value in the configuration, see :doc:`status` for more details.
 
-.. glossary::
-
     disabled option
 
         a disabled option has a different behaviour on regards to the access
         of the value in the configuration, see :doc:`status` for more details.
 
-.. glossary::
-
     mandatory option
 
         A mandatory option is a configuration option wich value has to be
         set, that is the default value cannot be `None`.
 
-.. glossary::
-
     consistency
 
-        Preserve the consistency in a whole configuration is a tricky thing,
+        Preserving the consistency in a whole configuration is a tricky thing,
         tiramisu takes care of it for you, see :doc:`consistency` for details.
+
+    context
+    
+        The context is a :class:`tiramisu.setting.Setting()` object in the 
+        configuration that enables us to access to the global properties
+        
+        for example the `read_write` or `read_only` :term:`access rules`
+
+        

doc/index.txt

@@ -48,3 +48,8 @@ This work is licensed under a `Creative Commons Attribution-ShareAlike 3.0 Unpor
 .. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US
 
 .. todolist:: 
+
+
+
+
+

doc/status.txt

@@ -40,21 +40,18 @@ method:
     "read only status", `False`, `True`, `True`
     "read-write status", `True`, `False`, `False`
 
-.. _`frozenconfig`:
+.. _`frozen`:
 
 Freezing a configuration
 ---------------------------
 
-.. todo:: freeze at configuration level
+At the configuration level, :class:`~setting.Setting()` enables us to freeze the 
+whole configuration, wich means that the frozen :class:`~option.Option()`'s 
+values cannot be modified.
 
-At the configuration level, `setting.Setting.freeze` freezes
+It is possible to *freeze* a single :class:`~option.Option()` object with
-the whole configuration options.
+:meth:`~config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen 
-
+option, it raises a `TypeError: trying to change a frozen option object`.
-.. _`frozen`:
-
-It is possible to *freeze* a single :class:`option.Option()` object with
-:meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen 
-:option, it raises a `TypeError: trying to change a frozen option object`.
 
 To find out if an option `myoption` is frozen, just make an assertion on the 
 settings like that::
@@ -62,14 +59,22 @@ settings like that::
     'frozen' in cfg.cfgimpl_get_settings()[myoption]
 
 Moreover, frozen option can return their default values if
-`option.Option.force_default()` is called on this option.
+:meth:`~option.Option.force_default()` is called on this option.
+
+.. glossary::
+
+    force default on freeze
+
+        A single option is frozen and we want the option to return something
+        else than his value, typically it is his default value.
+
+        In the option's values, an attribute can be set 
+        :attr:`force_default_on_freeze`, that forces this behavior.
 
 Restricted access to an `Option()`
 -----------------------------------
 
-.. currentmodule:: tiramisu.setting
+.. autoclass:: tiramisu.setting.Property
-
-.. autoclass:: Property
 
 The `properties` attribute is in charge of the access rules' option's value.
 
@@ -97,10 +102,13 @@ to activate, deactivate properties::
     cfg.cfgimpl_get_settings().append('hidden')
     cfg.cfgimpl_get_settings().remove('hidden')
 
+The global properties are living in e :class:`~setting.Setting` object. A 
+`Setting` object also takes care of the way to access option values and the 
+storage in the cache.
+
 Value owners
 -------------
 
-
 Every configuration option has a **owner**. When the option is instanciated, 
 the owner is :obj:`setting.owners.default` because a default value has been set 
 (including `None`, wich means that no value has been set yet).
@@ -144,3 +152,4 @@ various ways.
 If a default value is modified by overriding it, not only the value of
 the option resets to the default that is proposed, but the owner is
 modified too, it is reseted to `owners.default`.
+

tiramisu/value.py

@@ -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):
@@ -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)
 
 # ____________________________________________________________