tiramisu/doc/configapi.txt

.. default-role:: literal

.. module:: tiramisu.config

`tiramisu.config`, the configuration management main entry
================================================================

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
      ~Config.setoption

    .. automethod:: set
    .. automethod:: setoption

Here are some private attributes of a `Config()` object, for a
comprehension of the internal merchanism:

- `_cfgimpl_descr =` `option.OptionDescription()`,
  e.g. the `optionapi#schema`

- `_cfgimpl_values` contains the `option.Option()`'s values.
  Yes, the values of the options: remember that the values are stored **inside**
  the `config.Config()` and not in the `Option()`

`_cfgimpl_values` contains something like that

::

    {'int': 0, 'wantframework': False, 'objspace': 'std', 'bool': False,
    'str': 'abc', 'gc': <config.Config object at 0xa33f8ec>, 'wantref': False}

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 `optionapi#schema` 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__