63c5b38eac4824af0730c58ca39b5d01a889d83a
[tiramisu.git] / doc / config.txt
1 .. default-role:: literal
2
3 ===============================
4 Configuration handling basics
5 ===============================
6
7 `Config` and `Option` objects
8 ================================
9
10 Accessing the configuration `Option`'s
11 -----------------------------------------
12
13 The `Config` object attribute access notation stands for the value of the
14 configuration's `Option`. That is, the `Config`'s object attribute is the name
15 of the `Option`, and the value is the value accessed by the `__getattr__`
16 attribute access mechanism.
17
18 If the attribute of the `Config` called by `__getattr__` has not been set before
19 (by the classic `__setattr__` mechanism), the default value of the `Option`
20 object is returned, and if no `Option` has been declared in the
21 `OptionDescription` (that is the schema of the configuration), an
22 `AttributeError` is raised.
23
24 ::
25
26     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
27     >>> gcdummy._name
28     'dummy'
29     >>> gcdummy.getdefault()
30     False
31     >>> descr = OptionDescription('tiramisu', '', [gcdummy])
32     >>> cfg = Config(descr)
33     >>> cfg.dummy
34     False
35     >>> cfg.dummy = True
36     >>> cfg.dummy
37     True
38     >>> cfg.idontexist
39     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
40
41 The configuration `Option` objects (in this case the `BoolOption`), are
42 organized into a tree into nested `OptionDescription` objects. Every
43 option has a name, as does every option group. The parts of the full
44 name of the option are separated by dots: e.g.
45 ``config.optgroup.optname``.
46
47 Let's make the protocol of accessing a config's attribute explicit
48 (because explicit is better than implicit): 
49
50 1. If the option has not been declared, an `AttributeError` is raised,
51
52 2. If an option is declared, but neither a value nor a default value has
53    been set, the returned value is `None`,
54
55 3. If an option is declared and a default value has been set, but no value
56    has been set, the returned value is the default value of the option,
57
58 4. If an option is declared, and a value has been set, the returned value is
59    the value of the option.
60
61 What if a value has been set and `None` is to be returned again ? Don't
62 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
63 method.
64
65 If you do not want to use the pythonic way, that is the attribute access
66 way to obtain the value of the configuration option, you can also search
67 for it recursively in the whole config namespaces with the ``get()``
68 method :
69
70 ::
71
72     >>> config.get('bool')
73     True
74
75 To find the right option, `get()` searches recursively into the whole
76 tree. For example, to find an option which is in the `gc` namespace
77 there are two possibilites.
78
79 If you know the path:
80
81 ::
82
83     >>> config.gc.dummy
84     False
85
86 If you don't remember the path:
87
88 ::
89
90     >>> config.get('dummy')
91     False
92
93 Setting the values of the options
94 ----------------------------------------
95
96 An important part of the setting of the configuration consists of setting the
97 values of the configuration options. There are different ways of setting values,
98 the first one is of course the `__setattr__` method
99
100 ::
101
102     cfg.name = value
103
104 wich has the same effect that the "global" `set()` method (it expects that
105 the value owner is the default)
106
107 ::
108
109      cfg.set(name=value)
110
111 .. module:: tiramisu.config
112
113 The handling of options is split into two parts: the description of
114 which options are available, what their possible values and defaults are
115 and how they are organized into a tree. A specific choice of options is
116 bundled into a configuration object which has a reference to its option
117 description (and therefore makes sure that the configuration values
118 adhere to the option description).
119
120 The configuration object important methods
121 ---------------------------------------------
122
123 `config.Config()` object that lives in `config.py` hold the
124 choosen values for the options (or the default value for the
125 `option.Option()` object, if no choice was made).
126
127 A `Config` object is informed by an `option.OptionDescription`
128 instance. The attributes of the ``Config`` objects are the names of the
129 children of the ``OptionDescription``.
130
131 Here are the (useful) methods on ``Config``:
132
133 .. currentmodule:: tiramisu.config
134
135 .. autoclass:: Config
136
137     .. automethod:: __init__
138
139     .. rubric:: Methods
140
141     .. autosummary::
142
143       ~Config.__init__
144       ~Config.set
145
146     .. automethod:: set
147
148 We can see that values can also be config objects, it's the
149 sub-namespaces that are stored in the values as `Config()` objects.
150
151 convenience utilities (iteration, exports...)
152 -----------------------------------------------
153
154 With this `config.Config()` configuration management entry point,
155 it is possible to
156
157 - `iter` on config, notice that there is an iteration order wich is
158   the order of the :ref:`optdescr` specification entries,
159 - compare two configs (equality),
160 - export the whole config into a `dict` with `config.make_dict()`,
161
162 `option.Option()` objects in a config are iterable in the pythonic
163 way, that is something like `[(name, value) for name, value in config]`.
164
165 To iter on groups in the same manner, use the
166 `config.Config.iter_groups()` method wich yields generators too.
167
168 **iteration utilities**
169
170 .. autoclass:: Config
171
172     .. automethod:: __init__
173
174     .. rubric:: Methods
175
176     .. autosummary::
177
178       ~Config.get
179       ~Config.find
180       ~Config.find_first
181       ~Config.getpaths
182       ~Config.iter_groups
183       ~Config.__iter__
184
185     .. automethod:: get
186     .. automethod:: find
187     .. automethod:: find_first
188     .. automethod:: getpaths
189     .. automethod:: iter_groups
190     .. automethod:: __iter__