205 lines
5.8 KiB
Plaintext
205 lines
5.8 KiB
Plaintext
.. default-role:: literal
|
|
|
|
===============================
|
|
Options handling basics
|
|
===============================
|
|
|
|
Tiramisu is made of almost three main objects :
|
|
|
|
- :class:`tiramisu.config.Config` witch is the whole configuration entry point
|
|
- :class:`tiramisu.option.Option` stands for the option types
|
|
- :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
|
|
|
|
Accessing the `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 `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. ``cfg.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.
|
|
|
|
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
|
|
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
|
|
|
|
And if you wanna come back to a default value, use the builtin `del()` function::
|
|
|
|
del(cfg.name)
|
|
|
|
.. module:: tiramisu.config
|
|
|
|
.. _`tree`:
|
|
|
|
The handling of options
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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).
|
|
|
|
|
|
Common manipulations
|
|
------------------------
|
|
|
|
Let's perform some common manipulation on some options:
|
|
|
|
>>> from tiramisu.config import Config
|
|
>>> from tiramisu.option import UnicodeOption, OptionDescription
|
|
>>>
|
|
>>> var1 = UnicodeOption('var1', 'first variable')
|
|
>>> var2 = UnicodeOption('var2', '', u'value')
|
|
>>>
|
|
>>> od1 = OptionDescription('od1', 'first OD', [var1, var2])
|
|
>>> rootod = OptionDescription('rootod', '', [od1])
|
|
|
|
let's set somme access rules on the main namespace
|
|
|
|
>>> c = Config(rootod)
|
|
>>> c.read_write()
|
|
|
|
let's travel the namespaces
|
|
|
|
>>> print c
|
|
[od1]
|
|
>>> print c.od1
|
|
var1 = None
|
|
var2 = value
|
|
>>> print c.od1.var1
|
|
None
|
|
>>> print c.od1.var2
|
|
value
|
|
|
|
let's modify a value (careful to the value's type...)
|
|
|
|
>>> c.od1.var1 = 'value'
|
|
Traceback (most recent call last):
|
|
[...]
|
|
ValueError: invalid value value for option var1
|
|
>>> c.od1.var1 = u'value'
|
|
>>> print c.od1.var1
|
|
value
|
|
>>> c.od1.var2 = u'value2'
|
|
>>> print c.od1.var2
|
|
value2
|
|
|
|
let's come back to the default value
|
|
|
|
>>> del(c.od1.var2)
|
|
>>> print c.od1.var2
|
|
value
|
|
|
|
The value is saved in a :class:`~tiramisu.value.Value` object.
|
|
It is on this object that we have to trigger the `reset`
|
|
|
|
|
|
|
|
|
|
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`` (or `SubConfig`).
|
|
|
|
.. currentmodule:: tiramisu.config
|
|
|
|
.. class:: Config
|
|
|
|
.. autoclass:: SubConfig
|
|
:members: find, find_first, __iter__, iter_groups, iter_all, make_dict
|
|
|
|
.. automethod:: __init__
|
|
|
|
.. rubric:: Summary
|
|
|
|
.. autosummary::
|
|
|
|
find
|
|
find_first
|
|
|
|
__iter__
|
|
iter_groups
|
|
iter_all
|
|
|
|
make_dict
|
|
|
|
.. rubric:: Methods
|
|
|
|
|
|
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.
|