05f84dc98ecafacac1a88634318022f637b66e16
[tiramisu.git] / doc / config.txt
1 .. default-role:: literal
2
3 =======================
4 Configuration Handling
5 =======================
6
7 :module: :api:`config.py`
8 :tests:  - :api:`test_config.py`
9          - :api:`test_option_setting.py`
10              
11 Main Assumption
12 ===============
13
14 Configuration option objects :api:`config.Config()` are produced at the 
15 entry points and handed down to where they are actually used. This keeps 
16 configuration local but available everywhere and consistent.
17
18 `Config` and `Option` objects
19 ==============================
20
21 Configuration option objects can be created in different ways. Let's perform
22 very basic `Config` object manipulations:
23
24 ::
25
26     >>> from tiramisu.config import Config
27     >>> from tiramisu.option import OptionDescription, BoolOption
28     >>> descr = OptionDescription("optgroup", "", [
29     ...     BoolOption("bool", "", default=False)])
30     >>>
31     >>> config = Config(descr)
32     >>> config.bool
33     False
34     >>> config.bool = True
35     >>> config.bool
36     True
37
38 Take a look at :api:`test_config.test_base_config()` or 
39 :api:`test_config.test_base_config_and_groups()`.
40
41
42 Accessing the configuration `Option`'s
43 -----------------------------------------
44
45 The `Config` object attribute access notation stands for the value of the
46 configuration's `Option`. That is, the `Config`'s object attribute is the name
47 of the `Option`, and the value is the value accessed by the `__getattr__`
48 attribute access mechanism. 
49
50 If the attribute of the `Config` called by `__getattr__` has not been set before
51 (by the classic `__setattr__` mechanism), the default value of the `Option`
52 object is returned, and if no `Option` has been declared in the
53 `OptionDescription` (that is the schema of the configuration), an
54 `AttributeError` is raised.
55
56 ::
57
58     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
59     >>> gcdummy._name
60     'dummy'
61     >>> gcdummy.getdefault()
62     False
63     >>> descr = OptionDescription('tiramisu', '', [gcdummy])
64     >>> cfg = Config(descr)
65     >>> cfg.dummy
66     False
67     >>> cfg.dummy = True
68     >>> cfg.dummy
69     True
70     >>> cfg.idontexist
71     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
72
73 The configuration `Option` objects (in this case the `BoolOption`), are 
74 organized into a tree into nested `OptionDescription` objects. Every 
75 option has a name, as does every option group. The parts of the full 
76 name of the option are separated by dots: e.g. 
77 ``config.optgroup.optname``.
78
79 **Can you repeat it, what is the protocol of accessing a config's attribute ?**
80
81 1. If the option has not been declared, an `AttributeError` is raised,
82
83 2. If an option is declared, but neither a value nor a default value has
84    been set, the returned value is `None`,
85
86 3. If an option is declared and a default value has been set, but no value
87    has been set, the returned value is the default value of the option,
88
89 4. If an option is declared, and a value has been set, the returned value is
90    the value of the option.
91
92 What if a value has been set and `None` is to be returned again ? Don't
93 worry, an option value can be "reseted" just by the affectation of the special
94 value `None`. An option accepts a type value as a setting, but also `None` as 
95 a possible value.
96
97 If you do not want to use the pythonic way, that is the attribute access 
98 way to obtain the value of the configuration option, you can also search 
99 for it recursively in the whole config namespaces with the ``get()`` 
100 method :
101
102 ::
103
104     >>> config.get('bool')
105     True
106     
107
108 To find the right option, `get()` searches recursively into the whole 
109 tree. For example, to find an option which is in the `gc` namespace 
110 there are two possibilites.
111
112 If you know the path:
113
114 ::
115
116     >>> config.gc.dummy
117     False
118
119 If you don't remember the path:
120
121 ::
122
123     >>> config.get('dummy')
124     False
125
126 Setting the values of the options
127 ----------------------------------------
128
129 An important part of the setting of the configuration consists of setting the
130 values of the configuration options. There are different ways of setting values,
131 the first one is of course the `__setattr__` method 
132
133 ::
134
135     cfg.name = value
136
137 wich has the same effect that the "global" `set()` method : it expects that 
138 the value owner is the default :ref:`glossary#valueowner`
139
140 ::
141
142      cfg.set(name=value)
143
144 The global `setoption()` method of the config objects can set a value with a specific owner 
145
146 ::
147
148     cfg.setoption('name', value, 'owner')
149
150
151 Finally, the local `setoption()` method directly in the `Option` object can be
152 used. While the `Option` object refers to his parent, the config knows that the
153 value has been changed and no bad side effect won't occur
154
155 ::
156
157     >>> booloption = BoolOption('bool', 'Test boolean option', default=True)
158     >>> descr = OptionDescription('descr', '', [booloption])
159     >>> cfg = Config(descr)
160     >>> booloption.setoption(cfg, False, 'owner')
161     >>> cfg.bool 
162     >>> False
163