From b3418444505b548077096723a72faf4d63e2a846 Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 27 Aug 2013 15:54:10 +0200 Subject: [PATCH] first steps with tiramisu doc --- doc/config.txt | 141 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 115 insertions(+), 26 deletions(-) diff --git a/doc/config.txt b/doc/config.txt index 5b490ca..d9a1f5a 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -362,8 +362,8 @@ read/write or read only mode:: >>> print c.od1.var3 value -Properties can also be defined on option groups, -(that is, on :ref:`option description`s), 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 @@ -404,24 +404,23 @@ The requirements Let's create an option wich has requirements:: - >>> var1 = UnicodeOption('var1', '', u'value', requires=(('od1.var2', - 'non', 'hidden'),)) + >>> from tiramisu.option import * + >>> from tiramisu.config import * >>> var2 = UnicodeOption('var2', '', u'oui') - >>> var3 = UnicodeOption('var3', '', u'value', requires=(('od1.var2', - 'non', 'hidden'), ('od1.var2', 'non', 'disabled'))) + >>> var1 = UnicodeOption('var1', '', u'value', requires=[{'option':var2, 'expected':u'non', 'action':'hidden'}]) + >>> var3 = UnicodeOption('var3', '', u'value', requires=[{'option':var2, 'expected':u'non', 'action':'hidden'}, {'option':var2, 'expected':u'non', 'action':'disabled'}]) >>> var4 = UnicodeOption('var4', '', u'oui') - >>> >>> od1 = OptionDescription('od1', '', [var1, var2, var3]) - >>> od2 = OptionDescription('od2', '', [var4], requires=(('od1.var2', - 'oui', 'hidden', True),)) + >>> od2 = OptionDescription('od2', '', [var4], requires=[{'option':od1.var2, 'expected':u'oui', 'action':'hidden', 'inverse':True}]) >>> rootod = OptionDescription('rootod', '', [od1, od2]) >>> c = Config(rootod) - >>> c.read_write() + >>> c.read_write() -The requirement here is the tuple `('od1.var2' , 'non', 'hidden')` wich means -that is the option `'od1.var2'` is set to `'non'`, the option `'od1.var1'` is -gonna be hidden. On the other hand, if the option `'od1.var2'` is different -from `'non'`, the option `'od1.var1'` is not hidden any more:: +The requirement here is the dict `{'option':var2, 'expected':u'non', +'action':'hidden'}` wich means that is the option `'od1.var2'` is set to +`'non'`, the option `'od1.var1'` is gonna be hidden. On the other hand, if the +option `'od1.var2'` is different from `'non'`, the option `'od1.var1'` is not +hidden any more:: >>> print c.cfgimpl_get_settings()[rootod.od1.var1] [] @@ -443,10 +442,11 @@ from `'non'`, the option `'od1.var1'` is not hidden any more:: >>> print c.od1.var1 value -The requirement on `od2` is `('od1.var2', 'oui', 'hidden', True)`, which means -that if the option `od1.var2` is set to `oui`, the option is not hidden -(because of the `True` at the end of the tuple wich means 'inverted', take a -look at the :doc:`consistency` document.):: +The requirement on `od2` is `{'option':od1.var2, 'expected':u'oui', +'action':'hidden', 'inverse':True}`, which means that if the option `od1.var2` +is set to `oui`, the option is not hidden (because of the `True` at the end of +the tuple wich means 'inverted', take a look at the :doc:`consistency` +document.):: >>> print c.od2.var4 oui @@ -473,21 +473,110 @@ Requirements can be accumulated Requirements can be accumulated for different or identical properties (inverted or not):: - >>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non', - 'hidden'), ('od1.var1', 'oui', 'hidden'))) - >>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non', - 'hidden'), ('od1.var1', 'oui', 'disabled', True))) - + >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, + 'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'expected':'oui', + 'action':'hidden'}]) + >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, + 'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'excepted':'oui', + 'action':'disabled', 'inverse':True}]) + But it is not possible to have inverted requirements on the same property. Here is an impossible situation:: - >>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non', - 'hidden'), ('od1.var1', 'oui', 'hidden', True))) + >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, + 'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'expected':'oui', + 'hidden', True}]) + Traceback (most recent call last): [...] ValueError: inconsistency in action types for option: var3 action: hidden + +The calculations +~~~~~~~~~~~~~~~~~ - +Let's create four calculation functions:: + + def return_calc(): + #return an unicode value + return u'calc' + + def return_value(value): + return value + + def return_value_param(param=u''): + return param + + def return_no_value_if_non(value): + #if value is not u'non' return value + if value == u'non': + return None + else: + return value + +Then we create four options using theses functions:: + + >>> var1 = UnicodeOption('var1', '', callback=return_calc) + >>> var2 = UnicodeOption('var2', '', callback=return_value, callback_params={'': (u'value',)}) + >>> var3 = UnicodeOption('var3', '', callback=return_value_param, callback_params={'param': (u'value_param',)}) + >>> var4 = UnicodeOption('var4', '', callback=return_no_value_if_non, callback_params={'': (('od1.var5', False),)}) + >>> var5 = UnicodeOption('var5', '', u'oui') + >>> od1 = OptionDescription('od1', '', [var1, var2, var3, var4, var5]) + >>> rootod = OptionDescription('rootod', '', [od1]) + >>> c = Config(rootod) + >>> c.read_write() + +The first option `var1` returns the result of the `return_calc` function, wich +is `u'calc'`:: + + >>> print c.od1.var1 + calc + +The second option `var2` returns the result of the `return_value` fucntion, +wich is `value`. The parameter `u'value'` is passed to this function:: + + >>> print c.od1.var2 + value + +The third option `var3` returns the result of the function `return_value_param` +with the named parameter `param` and the value `u'value_param'`:: + + >>> print c.od1.var3 + value_param + +The fourth option `var4` returns the reslut of the function `return_no_value_if_non` +that is the value of `od1.var5` exceptif the value is u`non`:: + + >>> print c.od1.var4 + oui + >>> c.od1.var5 = u'new' + >>> print c.od1.var4 + new + >>> c.od1.var5 = u'non' + >>> print c.od1.var4 + None + +The calculation replaces the default value. +If we modify the value, the calculation is not carried out any more:: + + >>> print c.od1.var1 + calc + >>> c.od1.var1 = u'new_value' + >>> print c.od1.var1 + new_value + +To force the calculation to be carried out in some cases, one must add the +`frozen` and the `force_default_on_freeze` properties:: + + >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('frozen') + >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('force_default_on_freeze') + >>> print c.od1.var1 + calc + >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('frozen') + >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('force_default_on_freeze') + >>> print c.od1.var1 + new_value + + Configuration's interesting methods ------------------------------------------