refactoring doc for the new API
This commit is contained in:
gwen
parent
988bd659b8
commit
d6098f353e
Binary file not shown.
|
|
@ -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__
|
||||
|
|
|
|||
|
|
@ -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__
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
==================================
|
||||
Tiramisu - getting started
|
||||
Getting started
|
||||
==================================
|
||||
|
||||
What is Configuration handling ?
|
||||
|
|
|
|||
|
|
@ -32,7 +32,6 @@ configuration handler.
|
|||
|
||||
getting-started
|
||||
config
|
||||
configapi
|
||||
option
|
||||
status
|
||||
consistency
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
.. default-role:: literal
|
||||
|
||||
|
||||
.. TODO: STATUS and settings explained
|
||||
|
||||
Configuration status
|
||||
======================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue