tiramisu/doc/consistency.txt

.. default-role:: literal

.. currentmodule:: tiramisu

The global consistency
===========================

Identical option names
----------------------

If an :class:`~option.Option()` happens to be defined twice in the
:term:`schema` (e.g. the :class:`~option.OptionDescription()`),
that is the two options actually have the same name, an exception is raised.

The calculation is currently carried out in the samespace, for example
if `config.gc.name` is defined, another option in `gc` with the name
`name` is **not** allowed, whereas `config.whateverelse.name` is still
allowed.

Option's values type validation
--------------------------------

When a value is set to the option, the value is validated by the
option's :class:`option.Option()` validator's type.

Notice that if the option is `multi`, that is the `multi` attribute is set to
`True`, then the validation of the option value accepts a list of values
of the same type.

For example, an :class:`option.IntOption` validator waits for an `int` object of 
course, an :class:`option.StrOption` validator waits for an `str`, vs...


Where are located the values
-------------------------------

The entry point of the acces to the values is the :class:`setting.Setting()` of 
the root configuration object, but the values are actually located in the 
:class:`value.Values()` object, in order to be delegated in some kind of a 
`tiramisu.storage`, which can be a in-memory storage, or a persistent (for the 
time being, a sqlite3) storage.

:class:`value.Values()` is also responsible of the owners and the calculation 
of the options that have callbacks.

Requirements
------------

Configuration options can specify requirements as parameters at the init
time, the specification of some links between options or groups allows
to carry out a dependencies calculation. For example, an option can ben
hidden if another option has been set with some expected value. This is
just an example, the possibilities are hudge.

A requirement is a list of dictionnaries that have fairly this form::

    [{'option': a, 'expected': False, 'action': 'disabled', 'inverse': True,
    'transitive':True, 'same_action': True}]

Actually a transformation is made to this dictionnary during the validation of 
this requires at the :class:`~option.Option()`'s init. The dictionnairy becomes 
a tuple, wich is passed to the :meth:`~setting.Settings.apply_requires()` 
method. Take a look at the code to fully understand the exact meaning of the 
requirements:

.. automethod:: tiramisu.setting.Settings.apply_requires


The path of the option is required, the second element is the value wich is 
expected to trigger the callback, it is required too, and the third one is the 
callback's action name (`hide`, `show`...), wich is a 
:class:`~setting.Property()`. Requirements are validated in 
:class:`setting.Setting`.

Validation upon a whole configuration object
----------------------------------------------

An option's integrity can be validated towards a whole configuration.

This type of validation is very open. Let's take a use case : an option
has a certain value, and the value of this option can change the owner
of another option or option group... Everything is possible.

.. currentmodule:: tiramisu.option

Other hooks are availables to validate upon a whole configuration at any time, 
for example the consistency between two options (typically, an 
:class:`IPOption` and a :class:`NetworkOption`).

Values that are calculated
--------------------------------

An option that have a callback is considered to have a value that is to be 
calculated. 

An option's property with a `force_store_value` attribute is considered to be 
modified at the first calculation.

.. automodule:: tiramisu.autolib
    :members:

This is the typically protocol for accessing a option's for a calculated value, 
but some twisted ways are also possible, take a look at the `force_store_value` 
attribute.

.. glossary:: 

    force store value 

        A calculated value (that is, an option that has a callback) with the 
        attribute `force_store_value` enabled is considered to be modified at 
        the first calculation