dd8b6a7757802742a620b7c3d0e720cce9310ee6
[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.set(self, **kwargs)`:
37         "do what I mean"-interface to option setting. Searches all paths
38         starting from that config for matches of the optional arguments
39         and sets the found option if the match is not ambiguous.
40
41     :api:`config.Config.get(self, name)`:
42         the behavior is much like the attribute access way, except that
43         the search for the option is performed recursively in the whole
44         configuration tree.
45
46     :api:`config.Config.cfgimpl_read_write()`:
47         configuration level `read_write` status, see :doc:`status`
48
49     :api:`config.Config.cfgimpl_read_only()`:
50         configuration level `read_only` status, see :doc:`status`
51
52 Here are some private attributes of a `Config()` object, for a
53 comprehension of the internal merchanism:
54
55 - `_cfgimpl_descr =` :api:`option.OptionDescription()`,
56   e.g. the :ref:`optionapi#schema`
57
58 - `_cfgimpl_values` contains the :api:`option.Option()`'s values.
59   Yes, the values of the options: remember that the values are stored **inside**
60   the :api:`config.Config()` and not in the `Option()`
61
62 `_cfgimpl_values` contains something like that
63
64 ::
65
66     {'int': 0, 'wantframework': False, 'objspace': 'std', 'bool': False,
67     'str': 'abc', 'gc': <config.Config object at 0xa33f8ec>, 'wantref': False}
68
69 We can see that values can also be config objects, it's the
70 sub-namespaces that are stored in the values as `Config()` objects.
71
72 convenience utilities (iteration, exports...)
73 -----------------------------------------------
74
75 With this :api:`config.Config()` configuration management entry point,
76 it is possible to
77
78 - `iter` on config, notice that there is an iteration order wich is
79   the order of the :ref:`optionapi#schema` specification entries,
80 - compare two configs (equality),
81 - export the whole config into a `dict` with :api:`config.make_dict()`,
82
83 .. - `validate()` an option value into a config, see :doc:`consistency`.
84
85 :api:`option.Option()` objects in a config are iterable in the pythonic
86 way, that is something like `[(name, value) for name, value in config]`.
87
88 To iter on groups in the same manner, use the
89 :api:`config.Config.iter_groups()` method wich yields generators too.
90
91 **iteration utilities**
92
93     :api:`config.Config.__iter__()`
94         Pythonesque way of parsing group's ordered options.
95
96     :api:`config.Config.iter_groups(group_type=None)`:
97         To iter on groups objects only.
98         All groups are returned if `group_type` is `None`, otherwise the groups
99         can be filtered by categories (families, or whatever).