137 lines
4.4 KiB
Text
137 lines
4.4 KiB
Text
.. default-role:: literal
|
|
|
|
===============================
|
|
Configuration handling basics
|
|
===============================
|
|
|
|
Tiramisu is designed with three main objects :
|
|
|
|
- :class:`tiramisu.config.Config` witch is the whole configuration entry point
|
|
- :class:`tiramisu.option.Option` stands for the option type
|
|
- :class:`tiramisu.option.OptionDescription` stands for the description (the schema)
|
|
|
|
Accessing the configuration `Option`'s
|
|
-----------------------------------------
|
|
|
|
The `Config` object attribute access notation stands for the value of the
|
|
configuration's `Option`. That is, the `Config`'s object attribute is the name
|
|
of the `Option`, and the value is the value accessed by the `__getattr__`
|
|
attribute access mechanism.
|
|
|
|
If the attribute of the `Config` called by `__getattr__` has not been set before
|
|
(by the classic `__setattr__` mechanism), the default value of the `Option`
|
|
object is returned, and if no `Option` has been declared in the
|
|
`OptionDescription` (that is the schema of the configuration), an
|
|
`AttributeError` is raised.
|
|
|
|
::
|
|
|
|
>>> gcdummy = BoolOption('dummy', 'dummy', default=False)
|
|
>>> gcdummy._name
|
|
'dummy'
|
|
>>> gcdummy.getdefault()
|
|
False
|
|
>>> descr = OptionDescription('tiramisu', '', [gcdummy])
|
|
>>> cfg = Config(descr)
|
|
>>> cfg.dummy
|
|
False
|
|
>>> cfg.dummy = True
|
|
>>> cfg.dummy
|
|
True
|
|
>>> cfg.idontexist
|
|
AttributeError: 'OptionDescription' object has no attribute 'idontexist'
|
|
|
|
The configuration `Option` objects (in this case the `BoolOption`), are
|
|
organized into a tree into nested `OptionDescription` objects. Every
|
|
option has a name, as does every option group. The parts of the full
|
|
name of the option are separated by dots: e.g.
|
|
``config.optgroup.optname``.
|
|
|
|
Let's make the protocol of accessing a config's attribute explicit
|
|
(because explicit is better than implicit):
|
|
|
|
1. If the option has not been declared, an `AttributeError` is raised,
|
|
|
|
2. If an option is declared, but neither a value nor a default value has
|
|
been set, the returned value is `None`,
|
|
|
|
3. If an option is declared and a default value has been set, but no value
|
|
has been set, the returned value is the default value of the option,
|
|
|
|
4. If an option is declared, and a value has been set, the returned value is
|
|
the value of the option.
|
|
|
|
What if a value has been set and `None` is to be returned again ? Don't
|
|
worry, an option value can be "reseted" with the help of the `option.Option.reset()`
|
|
method.
|
|
|
|
If you know the path:
|
|
|
|
::
|
|
|
|
>>> config.gc.dummy
|
|
False
|
|
|
|
Setting the values of the options
|
|
----------------------------------------
|
|
|
|
An important part of the setting of the configuration consists of setting the
|
|
values of the configuration options. There are different ways of setting values,
|
|
the first one is of course the `__setattr__` method
|
|
|
|
::
|
|
|
|
cfg.name = value
|
|
|
|
.. module:: tiramisu.config
|
|
|
|
The handling of options is split into two parts: the description of
|
|
which options are available, what their possible values and defaults are
|
|
and how they are organized into a tree. A specific choice of options is
|
|
bundled into a configuration object which has a reference to its option
|
|
description (and therefore makes sure that the configuration values
|
|
adhere to the option description).
|
|
|
|
Configuration's interesting methods
|
|
------------------------------------------
|
|
|
|
A `Config` object is informed by an `option.OptionDescription`
|
|
instance. The attributes of the ``Config`` objects are the names of the
|
|
children of the ``OptionDescription``.
|
|
|
|
Here are the (useful) methods on ``Config``:
|
|
|
|
|
|
With this `config.Config()` configuration management entry point,
|
|
it is possible to
|
|
|
|
- `iter` on config, notice that there is an iteration order wich is
|
|
the order of the :ref:`optdescr` specification entries,
|
|
- compare two configs (equality),
|
|
- export the whole config into a `dict` with `config.make_dict()`,
|
|
|
|
`option.Option()` objects in a config are iterable in the pythonic
|
|
way, that is something like `[(name, value) for name, value in config]`.
|
|
|
|
To iter on groups in the same manner, use the
|
|
`config.Config.iter_groups()` method wich yields generators too.
|
|
|
|
.. currentmodule:: tiramisu.config
|
|
|
|
.. autoclass:: Config
|
|
|
|
.. automethod:: __init__
|
|
|
|
.. rubric:: Methods
|
|
|
|
.. autosummary::
|
|
|
|
~Config.find
|
|
~Config.find_first
|
|
~Config.iter_groups
|
|
~Config.__iter__
|
|
|
|
.. automethod:: find
|
|
.. automethod:: find_first
|
|
.. automethod:: iter_groups
|
|
.. automethod:: __iter__
|