tiramisu/doc/config.txt

.. default-role:: literal

===============================
Configuration handling basics
===============================

`Config` and `Option` objects
================================

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 do not want to use the pythonic way, that is the attribute access
way to obtain the value of the configuration option, you can also search
for it recursively in the whole config namespaces with the ``get()``
method :

::

    >>> config.get('bool')
    True

To find the right option, `get()` searches recursively into the whole
tree. For example, to find an option which is in the `gc` namespace
there are two possibilites.

If you know the path:

::

    >>> config.gc.dummy
    False

If you don't remember the path:

::

    >>> config.get('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

wich has the same effect that the "global" `set()` method (it expects that
the value owner is the default)

::

     cfg.set(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).

The configuration object important methods
---------------------------------------------

`config.Config()` object that lives in `config.py` hold the
choosen values for the options (or the default value for the
`option.Option()` object, if no choice was made).

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``:

.. currentmodule:: tiramisu.config

.. autoclass:: Config

    .. automethod:: __init__

    .. rubric:: Methods

    .. autosummary::

      ~Config.__init__
      ~Config.set

    .. automethod:: set

We can see that values can also be config objects, it's the
sub-namespaces that are stored in the values as `Config()` objects.

convenience utilities (iteration, exports...)
-----------------------------------------------

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.

**iteration utilities**

.. autoclass:: Config

    .. automethod:: __init__

    .. rubric:: Methods

    .. autosummary::

      ~Config.get
      ~Config.find
      ~Config.find_first
      ~Config.getpaths
      ~Config.iter_groups
      ~Config.__iter__

    .. automethod:: get
    .. automethod:: find
    .. automethod:: find_first
    .. automethod:: getpaths
    .. automethod:: iter_groups
    .. automethod:: __iter__