.. default-role:: literal

Config API Details
==================

:module: :api:`config.py`
:test cases: - :api:`test_config_api.py`
             - :api:`test_config_big_example.py`


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

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

A `Config` object is informed by an :api:`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``:

    :api:`config.Config.__init__(self, descr, **overrides)`:
        ``descr`` is an instance of :api:`option.OptionDescription` that 
        describes the configuration object. ``override`` can be used to 
        set different default values (see method ``override``).

    :api:`config.Config.override(self, overrides)`:
        override default values. This marks the overridden values as defaults.
        ``overrides`` is a dictionary of path strings to values.

    :api:`config.Config.set(self, **kwargs)`:
        "do what I mean"-interface to option setting. Searches all paths 
        starting from that config for matches of the optional arguments 
        and sets the found option if the match is not ambiguous.

    :api:`config.Config.get(self, name)`:
        the behavior is much like the attribute access way, except that 
        the search for the option is performed recursively in the whole 
        configuration tree.

    :api:`config.Config.cfgimpl_read_write()`:
        configuration level `read_write` status, see :doc:`status` 
    
    :api:`config.Config.cfgimpl_read_only()`:
        configuration level `read_only` status, see :doc:`status` 

Here are some private attributes of a `Config()` object, for a 
comprehension of the internal merchanism:
    
- `_cfgimpl_descr =` :api:`option.OptionDescription()`, 
  e.g. the :ref:`optionapi#schema`

- `_cfgimpl_values` contains the :api:`option.Option()`'s values. 
  Yes, the values of the options: remember that the values are stored **inside**
  the :api:`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 :api:`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:`optionapi#schema` specification entries,
- compare two configs (equality),
- export the whole config into a `dict` with :api:`config.make_dict()`,
- `validate()` an option value into a config, see :doc:`consistency`.

:api:`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
:api:`config.Config.iter_groups()` method wich yields generators too.

**iteration utilities**

    :api:`config.Config.__iter__()` 
        Pythonesque way of parsing group's ordered options.
    
    :api:`config.Config.iter_groups(group_type=None)`:
        To iter on groups objects only. 
        All groups are returned if `group_type` is `None`, otherwise the groups
        can be filtered by categories (families, or whatever).