diff --git a/doc/architecture.dia b/doc/architecture.dia deleted file mode 100644 index 35adb7e..0000000 Binary files a/doc/architecture.dia and /dev/null differ diff --git a/doc/config.txt b/doc/config.txt index 681a4f8..63c5b38 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -5,11 +5,7 @@ Configuration handling basics =============================== `Config` and `Option` objects -========================================= - - -Take a look at `test_config.test_base_config()` or -`test_config.test_base_config_and_groups()`. +================================ Accessing the configuration `Option`'s ----------------------------------------- @@ -48,7 +44,8 @@ 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``. -**Can you repeat it, what is the protocol of accessing a config's attribute ?** +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, @@ -104,9 +101,90 @@ 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 `glossary#valueowner` +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__ diff --git a/doc/configapi.txt b/doc/configapi.txt deleted file mode 100644 index 91bcbec..0000000 --- a/doc/configapi.txt +++ /dev/null @@ -1,104 +0,0 @@ -.. 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 :ref:`optdescr` - -- `_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', '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 :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__ diff --git a/doc/getting-started.txt b/doc/getting-started.txt index 81bf1c0..1de6ab5 100644 --- a/doc/getting-started.txt +++ b/doc/getting-started.txt @@ -1,5 +1,5 @@ ================================== -Tiramisu - getting started +Getting started ================================== What is Configuration handling ? diff --git a/doc/index.txt b/doc/index.txt index f9fb7de..add8ac0 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -32,7 +32,6 @@ configuration handler. getting-started config - configapi option status consistency diff --git a/doc/status.txt b/doc/status.txt index ceac4b2..faa3002 100644 --- a/doc/status.txt +++ b/doc/status.txt @@ -1,5 +1,8 @@ .. default-role:: literal + +.. TODO: STATUS and settings explained + Configuration status ======================