update doc
[tiramisu.git] / doc / config.txt
index 2118f4c..3c6d9bc 100644 (file)
@@ -6,15 +6,17 @@ Options handling basics
 
 Tiramisu is made of almost three main objects :
 
-- :class:`tiramisu.config.Config` which is the whole configuration entry point
 - :class:`tiramisu.option.Option` stands for the option types
 - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
+- :class:`tiramisu.config.Config` which is the whole configuration entry point
+
+.. image:: config.png
 
 Accessing the `Option`'s
 -------------------------
 
 The :class:`~tiramisu.config.Config` object attribute access notation stands for 
-the value of the configuration's :class:`~tiramisu.option.Option`. That is, the 
+the value of the configuration's :class:`~tiramisu.option.Option`.
 :class:`~tiramisu.config.Config`'s object attribute is the name of the option, 
 and the value is the value accessed by the `__getattr__` attribute access 
 mechanism.
@@ -49,7 +51,7 @@ are organized into a tree into nested
 as does every option group. The parts of the full name of the option are 
 separated by dots: e.g. ``cfg.optgroup.optname``.
 
-Let's make the protocol of accessing a config's attribute explicit
+Let's make the protocol of accessing a `Config`'s attribute explicit
 (because explicit is better than implicit):
 
 1. If the option has not been declared, an `AttributeError` is raised,
@@ -67,11 +69,11 @@ But there are special exceptions. We will see later on that an option can be a
 :term:`mandatory option`. A mandatory option is an option that must have a value 
 defined.
 
-Setting the values of the options
-----------------------------------------
+Setting the value of an option
+------------------------------
 
-An important part of the setting of the configuration consists of setting the
-values of the configuration options. There are different ways of setting values,
+An important part of the setting's configuration consists of setting the
+value's option. There are different ways of setting values,
 the first one is of course the `__setattr__` method
 
 ::
@@ -103,10 +105,10 @@ Let's perform some common manipulation on some options
 
 >>> from tiramisu.config import Config
 >>> from tiramisu.option import UnicodeOption, OptionDescription
->>>
+>>> #
 >>> var1 = UnicodeOption('var1', 'first variable')
 >>> var2 = UnicodeOption('var2', '', u'value')
->>>
+>>> #
 >>> od1 = OptionDescription('od1', 'first OD', [var1, var2])
 >>> rootod = OptionDescription('rootod', '', [od1])
 
@@ -127,10 +129,11 @@ None
 >>> print c.od1.var2
 value
 
-let's modify a value (careful to the value's type...)
+let's modify a value (be careful to the value's type...)
 
 >>> c.od1.var1 = 'value'
-Traceback (most recent call last): ValueError: invalid value value for option var1
+Traceback (most recent call last):
+ValueError: invalid value value for option var1
 >>> c.od1.var1 = u'value'
 >>> print c.od1.var1
 value
@@ -153,7 +156,8 @@ On the other side, in the `read_only` mode, it is not possible to modify the val
 >>> c.read_only()
 >>> c.od1.var2 = u'value2'
 Traceback (most recent call last):
-tiramisu.error.PropertiesOptionError: cannot change the value to var2 for option ['frozen'] this option is frozen
+tiramisu.error.PropertiesOptionError: cannot change the value for option var2 this option is frozen
+
 
 let's retrieve the option `var1` description
 
@@ -184,7 +188,7 @@ That's why a tree of options can easily be searched. First, let's build such a t
 >>> c = Config(rootod)
 >>> c.read_write()
 
-Second, let's find an option by his name::
+Second, let's find an option by it's name::
 
     >>> print c.find(byname='var1')
     [<tiramisu.option.UnicodeOption object at 0x7ff1bf7d6ef0>, 
@@ -232,7 +236,7 @@ If the organisation in a tree is not important,
 {'var5': None, 'var4': None, 'var6': None, 'var1': u'value', 'var3': None, 
 'var2': None}
 
-.. note:: carefull with this `flatten` parameter, here we have just lost 
+.. note:: be carefull with this `flatten` parameter, here we have just lost 
                two options named `var1`
 
 One can export only interesting parts of a tree of options into a dict, for 
@@ -249,7 +253,7 @@ and of course, :meth:`~config.SubConfig.make_dict()` can be called in a subtree:
 >>> print c.od1.make_dict(withoption='var1')
 {'var1': None, 'var3': None, 'var2': None}
 
-the owners
+The owners
 ~~~~~~~~~~~
 
 .. glossary::
@@ -267,24 +271,36 @@ the owners
             
 Then let's retrieve the owner associated to an option::
 
-    >>> print c.getowner('var1')
-    default
-    >>> c.od1.var1 = u'non'
-    >>> print c.getowner('var1')
-    user
-    >>> del(c.var1)
-    >>> print c.getowner('var1')
-    default
-    
-the properties
-~~~~~~~~~~~~~~~~
+   >>> print c.getowner(var1)
+   default
+   >>> c.od1.var1 = u'no'
+   >>> print c.getowner(var1)
+   user
+   >>> del(c.var1)
+   >>> print c.getowner(var1)
+   default
+
+You can create your own owner, for example to distinguish modification made by
+one user to an other one's.
+
+   >>> from tiramisu.setting import owners
+   >>> owners.addowner('toto')
+   >>> c.cfgimpl_get_settings().setowner(owners.toto)
+   >>> print c.getowner(var1)
+   default
+   >>> c.od1.var1 = u'no'
+   >>> print c.getowner(var1)
+   toto
+The properties
+~~~~~~~~~~~~~~
 
 A property is an information on an option's state. 
 Let's create options with properties::
 
     >>> var1 = UnicodeOption('var1', '', u'value', properties=('hidden',))
     >>> var2 = UnicodeOption('var2', '', properties=('mandatory',))
-    >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'inconnu'))
+    >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'unknown'))
     >>> var4 = UnicodeOption('var4', '', u'value')
     >>> od1 = OptionDescription('od1', '', [var1, var2, var3])
     >>> od2 = OptionDescription('od2', '', [var4], properties=('hidden',))
@@ -338,17 +354,17 @@ Let's try to modify a frozen option::
 Tiramisu allows us to use user defined properties. Let's define and use one in 
 read/write or read only mode::
 
-    >>> c.cfgimpl_get_settings().append('inconnu')
+    >>> c.cfgimpl_get_settings().append('unknown')
     >>> print c.od1.var3
     Traceback (most recent call last):
     tiramisu.error.PropertiesOptionError: trying to access to an option named: 
-    var3 with properties ['inconnu']
-    >>> c.cfgimpl_get_settings().remove('inconnu')
+    var3 with properties ['unknown']
+    >>> c.cfgimpl_get_settings().remove('unknown')
     >>> print c.od1.var3
     value 
     
-Properties can also be defined on an option group, (that is, on an 
-:term:`option description`), let's hide a group and try to access to it::
+Properties can also be defined on an option group (that is, on an 
+:term:`option description`) let's hide a group and try to access to it::
 
     >>> c.read_write()
     >>> print c.od2.var4