add autopath to executable doc
[tiramisu.git] / doc / configapi.txt
1 .. default-role:: literal
2
3 Config API Details
4 ==================
5
6 :module: :api:`config.py`
7 :test cases: - :api:`test_config_api.py`
8              - :api:`test_config_big_example.py`
9
10
11 The handling of options is split into two parts: the description of 
12 which options are available, what their possible values and defaults are 
13 and how they are organized into a tree. A specific choice of options is 
14 bundled into a configuration object which has a reference to its option 
15 description (and therefore makes sure that the configuration values 
16 adhere to the option description).
17
18 The configuration object
19 -------------------------
20
21 :api:`config.Config()` object that lives in :api:`config.py` hold the 
22 choosen values for the options (or the default value for the 
23 :api:`option.Option()` object, if no choice was made).
24
25 A `Config` object is informed by an :api:`option.OptionDescription` 
26 instance. The attributes of the ``Config`` objects are the names of the 
27 children of the ``OptionDescription``.
28
29 Here are the (useful) methods on ``Config``:
30
31     :api:`config.Config.__init__(self, descr, **overrides)`:
32         ``descr`` is an instance of :api:`option.OptionDescription` that 
33         describes the configuration object. ``override`` can be used to 
34         set different default values (see method ``override``).
35
36     :api:`config.Config.override(self, overrides)`:
37         override default values. This marks the overridden values as defaults.
38         ``overrides`` is a dictionary of path strings to values.
39
40     :api:`config.Config.set(self, **kwargs)`:
41         "do what I mean"-interface to option setting. Searches all paths 
42         starting from that config for matches of the optional arguments 
43         and sets the found option if the match is not ambiguous.
44
45     :api:`config.Config.get(self, name)`:
46         the behavior is much like the attribute access way, except that 
47         the search for the option is performed recursively in the whole 
48         configuration tree.
49
50     :api:`config.Config.cfgimpl_read_write()`:
51         configuration level `read_write` status, see :doc:`status` 
52     
53     :api:`config.Config.cfgimpl_read_only()`:
54         configuration level `read_only` status, see :doc:`status` 
55
56 Here are some private attributes of a `Config()` object, for a 
57 comprehension of the internal merchanism:
58     
59 - `_cfgimpl_descr =` :api:`option.OptionDescription()`, 
60   e.g. the :ref:`optionapi#schema`
61
62 - `_cfgimpl_values` contains the :api:`option.Option()`'s values. 
63   Yes, the values of the options: remember that the values are stored **inside**
64   the :api:`config.Config()` and not in the `Option()`
65
66 `_cfgimpl_values` contains something like that 
67
68 ::
69
70     {'int': 0, 'wantframework': False, 'objspace': 'std', 'bool': False,
71     'str': 'abc', 'gc': <config.Config object at 0xa33f8ec>, 'wantref': False}
72
73 We can see that values can also be config objects, it's the 
74 sub-namespaces that are stored in the values as `Config()` objects.
75
76 convenience utilities (iteration, exports...)
77 -----------------------------------------------
78
79 With this :api:`config.Config()` configuration management entry point, 
80 it is possible to
81
82 - `iter` on config, notice that there is an iteration order wich is 
83   the order of the :ref:`optionapi#schema` specification entries,
84 - compare two configs (equality),
85 - export the whole config into a `dict` with :api:`config.make_dict()`,
86 - `validate()` an option value into a config, see :doc:`consistency`.
87
88 :api:`option.Option()` objects in a config are iterable in the pythonic 
89 way, that is something like `[(name, value) for name, value in config]`. 
90
91 To iter on groups in the same manner, use the
92 :api:`config.Config.iter_groups()` method wich yields generators too.
93
94 **iteration utilities**
95
96     :api:`config.Config.__iter__()` 
97         Pythonesque way of parsing group's ordered options.
98     
99     :api:`config.Config.iter_groups(group_type=None)`:
100         To iter on groups objects only. 
101         All groups are returned if `group_type` is `None`, otherwise the groups
102         can be filtered by categories (families, or whatever).
103