tiramisu/doc/config.txt

149 lines
4.7 KiB
Plaintext
Raw Normal View History

.. default-role:: literal
2012-11-20 17:14:58 +01:00
===============================
Configuration handling basics
===============================
2012-10-05 16:00:07 +02:00
2013-05-21 18:42:56 +02:00
Tiramisu is made of almost three main objects :
- :class:`tiramisu.config.Config` witch is the whole configuration entry point
2013-05-21 18:42:56 +02:00
- :class:`tiramisu.option.Option` stands for the option types
- :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
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__`
2012-10-05 16:00:07 +02:00
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'
2012-10-05 16:00:07 +02:00
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``.
2013-05-17 12:11:14 +02:00
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.
2013-08-21 17:21:09 +02:00
But there are special exceptions. We will see later on that an option can be a
:term:`mandatory option`. A mandatory option is an option that must have a defined value.
If no value have been set yet, the value is `None`.
When the option is called to retrieve a value, an exception is raised.
What if a value has been set and `None` is to be returned again ? Don't
2012-11-20 17:14:58 +01:00
worry, an option value can be "reseted" with the help of the `option.Option.reset()`
2012-11-14 11:30:11 +01:00
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,
2012-10-05 16:00:07 +02:00
the first one is of course the `__setattr__` method
::
cfg.name = value
2013-05-23 17:51:50 +02:00
And if you wanna come back to a default value, use the builtin `del()` function::
2013-05-21 18:42:56 +02:00
del(cfg.name)
2013-05-17 12:11:14 +02:00
.. module:: tiramisu.config
2013-08-22 12:17:10 +02:00
.. _`tree`:
The handling of options
~~~~~~~~~~~~~~~~~~~~~~~~~~
2013-05-17 12:11:14 +02:00
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
------------------------------------------
2013-05-17 12:11:14 +02:00
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``.
2013-05-23 17:51:50 +02:00
Here are the (useful) methods on ``Config`` (or `SubConfig`).
2013-05-17 12:11:14 +02:00
.. currentmodule:: tiramisu.config
2013-05-17 12:11:14 +02:00
2013-05-23 17:51:50 +02:00
.. class:: Config
2013-05-17 12:11:14 +02:00
2013-05-23 17:51:50 +02:00
.. autoclass:: SubConfig
:members: find, find_first, __iter__, iter_groups, iter_all, make_dict
2013-05-17 12:11:14 +02:00
2013-05-23 17:51:50 +02:00
.. automethod:: __init__
.. rubric:: Summary
2013-05-17 12:11:14 +02:00
.. autosummary::
2013-05-23 17:51:50 +02:00
find
find_first
2013-05-17 12:11:14 +02:00
2013-05-23 17:51:50 +02:00
__iter__
iter_groups
iter_all
2013-05-17 12:11:14 +02:00
2013-05-23 17:51:50 +02:00
make_dict
2013-05-21 18:42:56 +02:00
2013-05-23 17:51:50 +02:00
.. rubric:: Methods
2013-05-21 18:42:56 +02:00
2013-05-23 17:51:50 +02:00
2013-08-21 17:21:09 +02:00
A :class:`~config.CommonConfig` is a abstract base class. A
:class:`~config.SubConfig` is an just in time created objects that wraps an
::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
::fact that a config is a root object and has an environnement, a context wich
::defines the different properties, access rules, vs... There is generally only
::one Config, and many SubConfigs.