add docstring and some docs
This commit is contained in:
gwen
@ -7,12 +7,12 @@ Configuration Handling
|
||||
:module: :api:`config.py`
|
||||
:tests: - :api:`test_config.py`
|
||||
- :api:`test_option_setting.py`
|
||||
|
||||
|
||||
Main Assumption
|
||||
===============
|
||||
|
||||
Configuration option objects :api:`config.Config()` are produced at the
|
||||
entry points and handed down to where they are actually used. This keeps
|
||||
Configuration option objects :api:`config.Config()` are produced at the
|
||||
entry points and handed down to where they are actually used. This keeps
|
||||
configuration local but available everywhere and consistent.
|
||||
|
||||
`Config` and `Option` objects
|
||||
@ -35,7 +35,7 @@ very basic `Config` object manipulations:
|
||||
>>> config.bool
|
||||
True
|
||||
|
||||
Take a look at :api:`test_config.test_base_config()` or
|
||||
Take a look at :api:`test_config.test_base_config()` or
|
||||
:api:`test_config.test_base_config_and_groups()`.
|
||||
|
||||
|
||||
@ -45,7 +45,7 @@ Accessing the configuration `Option`'s
|
||||
The `Config` object attribute access notation stands for the value of the
|
||||
configuration's `Option`. That is, the `Config`'s object attribute is the name
|
||||
of the `Option`, and the value is the value accessed by the `__getattr__`
|
||||
attribute access mechanism.
|
||||
attribute access mechanism.
|
||||
|
||||
If the attribute of the `Config` called by `__getattr__` has not been set before
|
||||
(by the classic `__setattr__` mechanism), the default value of the `Option`
|
||||
@ -70,10 +70,10 @@ object is returned, and if no `Option` has been declared in the
|
||||
>>> cfg.idontexist
|
||||
AttributeError: 'OptionDescription' object has no attribute 'idontexist'
|
||||
|
||||
The configuration `Option` objects (in this case the `BoolOption`), are
|
||||
organized into a tree into nested `OptionDescription` objects. Every
|
||||
option has a name, as does every option group. The parts of the full
|
||||
name of the option are separated by dots: e.g.
|
||||
The configuration `Option` objects (in this case the `BoolOption`), are
|
||||
organized into a tree into nested `OptionDescription` objects. Every
|
||||
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 ?**
|
||||
@ -91,22 +91,21 @@ name of the option are separated by dots: e.g.
|
||||
|
||||
What if a value has been set and `None` is to be returned again ? Don't
|
||||
worry, an option value can be "reseted" just by the affectation of the special
|
||||
value `None`. An option accepts a type value as a setting, but also `None` as
|
||||
value `None`. An option accepts a type value as a setting, but also `None` as
|
||||
a possible value.
|
||||
|
||||
If you do not want to use the pythonic way, that is the attribute access
|
||||
way to obtain the value of the configuration option, you can also search
|
||||
for it recursively in the whole config namespaces with the ``get()``
|
||||
If you do not want to use the pythonic way, that is the attribute access
|
||||
way to obtain the value of the configuration option, you can also search
|
||||
for it recursively in the whole config namespaces with the ``get()``
|
||||
method :
|
||||
|
||||
::
|
||||
|
||||
>>> config.get('bool')
|
||||
True
|
||||
|
||||
|
||||
To find the right option, `get()` searches recursively into the whole
|
||||
tree. For example, to find an option which is in the `gc` namespace
|
||||
To find the right option, `get()` searches recursively into the whole
|
||||
tree. For example, to find an option which is in the `gc` namespace
|
||||
there are two possibilites.
|
||||
|
||||
If you know the path:
|
||||
@ -128,20 +127,20 @@ Setting the values of the options
|
||||
|
||||
An important part of the setting of the configuration consists of setting the
|
||||
values of the configuration options. There are different ways of setting values,
|
||||
the first one is of course the `__setattr__` method
|
||||
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
|
||||
wich has the same effect that the "global" `set()` method : it expects that
|
||||
the value owner is the default :ref:`glossary#valueowner`
|
||||
|
||||
::
|
||||
|
||||
cfg.set(name=value)
|
||||
|
||||
The global `setoption()` method of the config objects can set a value with a specific owner
|
||||
The global `setoption()` method of the config objects can set a value with a specific owner
|
||||
|
||||
::
|
||||
|
||||
@ -158,6 +157,5 @@ value has been changed and no bad side effect won't occur
|
||||
>>> descr = OptionDescription('descr', '', [booloption])
|
||||
>>> cfg = Config(descr)
|
||||
>>> booloption.setoption(cfg, False, 'owner')
|
||||
>>> cfg.bool
|
||||
>>> cfg.bool
|
||||
>>> False
|
||||
|
||||
|
||||
@ -8,29 +8,29 @@ Config API Details
|
||||
- :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
|
||||
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:`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
|
||||
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
|
||||
``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)`:
|
||||
@ -38,66 +38,65 @@ Here are the (useful) methods on ``Config``:
|
||||
``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
|
||||
"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
|
||||
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`
|
||||
configuration level `read_write` status, see :doc:`status`
|
||||
|
||||
Here are some private attributes of a `Config()` object, for a
|
||||
: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()`,
|
||||
|
||||
- `_cfgimpl_descr =` :api:`option.OptionDescription()`,
|
||||
e.g. the :ref:`optionapi#schema`
|
||||
|
||||
- `_cfgimpl_values` contains the :api:`option.Option()`'s values.
|
||||
- `_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
|
||||
`_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
|
||||
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,
|
||||
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
|
||||
- `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`.
|
||||
.. - `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]`.
|
||||
: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__()`
|
||||
: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.
|
||||
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).
|
||||
|
||||
|
||||
@ -6,42 +6,54 @@ The global configuration's consistency
|
||||
:module: :api:`config.py`
|
||||
:tests: :api:`test_option_consistency.py`
|
||||
|
||||
Identical option names
|
||||
----------------------
|
||||
|
||||
If an :api:`option.Option()` happens to be defined twice in the
|
||||
:ref:`glossary#schema` (e.g. the :api:`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
|
||||
When a value is set to the option, the value is validated by the
|
||||
option's :api:`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
|
||||
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.
|
||||
|
||||
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
|
||||
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, because the possibilities are hudge.
|
||||
|
||||
A requirement is specified using a list of triplets. The first element
|
||||
of the triplet gives the path of the option that is required, the second
|
||||
element is the value wich is expected to trigger the callback, and the
|
||||
A requirement is specified using a list of triplets. The first element
|
||||
of the triplet gives the path of the option that is required, the second
|
||||
element is the value wich is expected to trigger the callback, and the
|
||||
third one is the callback's action name (`hide`, `show`...)::
|
||||
|
||||
stroption = StrOption('str', 'Test string option', default="abc",
|
||||
stroption = StrOption('str', 'Test string option', default="abc",
|
||||
requires=[('int', 1, 'hide')])
|
||||
|
||||
Take a look at an example here
|
||||
Take a look at an example here
|
||||
:api:`test_option_consistency.test_hidden_if_in()`
|
||||
|
||||
Config updates
|
||||
---------------
|
||||
|
||||
New configuration options and groups can be dynamically added.
|
||||
New configuration options and groups can be dynamically added.
|
||||
|
||||
The configuration has to be *updated* after that the description has been
|
||||
The configuration has to be *updated* after that the description has been
|
||||
passed to the Config objet, see:
|
||||
|
||||
::
|
||||
@ -53,50 +65,25 @@ passed to the Config objet, see:
|
||||
>>> config.newoption
|
||||
False
|
||||
|
||||
in
|
||||
in
|
||||
|
||||
- :api:`test_option_consistency.test_newoption_add_in_descr()`
|
||||
- :api:`test_option_consistency.test_newoption_add_in_subdescr()`
|
||||
- :api:`test_option_consistency.test_newoption_add_in_config()`
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
For example, the configuration paths have to be unique in the
|
||||
:ref:`glossary#schema`, the validation is carried out at the
|
||||
:api:`config.Config._cfgimpl_build()` time in the
|
||||
For example, the configuration paths have to be unique in the
|
||||
:ref:`glossary#schema`, the validation is carried out at the
|
||||
:api:`config.Config._cfgimpl_build()` time in the
|
||||
:api:`config.Config._validate_duplicates()` method.
|
||||
|
||||
Other hook are availables to validate upon a whole configuration at any
|
||||
Other hook are availables to validate upon a whole configuration at any
|
||||
time.
|
||||
|
||||
Identical option names
|
||||
----------------------
|
||||
|
||||
If an :api:`option.Option()` happens to be defined twice in the
|
||||
:ref:`glossary#schema` (e.g. the :api:`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.
|
||||
|
||||
.. the calculation was carried out by the requires, wich is not a goog idead
|
||||
|
||||
Type constraints with the `multi` type
|
||||
----------------------------------------
|
||||
|
||||
By convention, if a multi option has somme requires, the constraints on
|
||||
the multi type is in all the OptionGroup (a group has to be `multi`, and
|
||||
a multi of the same length).
|
||||
|
||||
See :api:`test_option_consistency.test_multi_constraints()`
|
||||
|
||||
|
||||
@ -1,70 +0,0 @@
|
||||
- abstract values from `gaspacho`
|
||||
|
||||
Les types possibles :
|
||||
|
||||
- sans valeur : `boolean`
|
||||
- avec valeur : `unicode` (un texte libre), `integer` (un chiffre), `enum` (une liste de choix prédéfinies) et `list` (une liste de choix libres).
|
||||
|
||||
Les types sans valeurs sont les plus simples. Par exemple cette règle n’attend
|
||||
aucune valeur particulière Vérifier que Firefox est le navigateur par défaut.
|
||||
|
||||
Alors que celle-ci attend une adresse IP Configuration du serveur proxy manuelle.
|
||||
|
||||
Il existe un autre type (multi) qui permet de mêler plusieurs types.
|
||||
|
||||
Il s’agit bien de définir ici le type de la règle (et uniquement de la règle).
|
||||
|
||||
- configuration levels in `creole`
|
||||
|
||||
*thu, 28 april 2011*
|
||||
|
||||
Exemple de niveau de configuration (dans l'ordre) :
|
||||
|
||||
1. - Coeur
|
||||
|
||||
2.
|
||||
- Coeur
|
||||
- gen_config
|
||||
|
||||
3.
|
||||
- Coeur
|
||||
- gen_config
|
||||
- EAD
|
||||
|
||||
4.
|
||||
- Coeur
|
||||
- EAD
|
||||
|
||||
5.
|
||||
- Coeur
|
||||
- baculaconfig.py
|
||||
|
||||
(`fill` : calcule une valeur jusqu'à ce que l'utilisateur change la
|
||||
valeur)
|
||||
|
||||
Gestion des ACL en écriture :
|
||||
|
||||
Le coeur charge les variables
|
||||
|
||||
- si auto : seul le coeur peut la modifier (cas 1) ;
|
||||
|
||||
- si fill : le coeur calcule une valeur tant que pas configuré par
|
||||
l'utilisateur. L'utilisateur peut modifier (cas 2 ou 3) ;
|
||||
|
||||
- des variables modifiables que par gen_config (cas 2) ;
|
||||
|
||||
- des variables modifiables par gen_config ou l'EAD (cas 3) ;
|
||||
|
||||
- des variables d'autres applications (cas 4 et 5).
|
||||
|
||||
Gestion des ACLs en lecture :
|
||||
|
||||
- seule une application peut lire certaines variables (exemple un mot de
|
||||
passe).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -57,7 +57,7 @@ glossary
|
||||
**forced on freeze**
|
||||
|
||||
A single option is frozen and we want the option to return something
|
||||
else than his value, for example his default value, see
|
||||
else than his value, typically his default value, see
|
||||
:ref:`status#frozen`
|
||||
|
||||
.. _`valueowner`:
|
||||
@ -83,16 +83,6 @@ glossary
|
||||
a disabled option has a different behaviour on regards to the access
|
||||
of the value in the configuration, see :doc:`status` for more details.
|
||||
|
||||
**fill option**
|
||||
|
||||
a fill option is like an automatic option except that it is
|
||||
calculated only if a value hasn't been set.
|
||||
|
||||
**auto option**
|
||||
|
||||
an automatic option is an option thas is carried out by an external
|
||||
calculation
|
||||
|
||||
.. _mandatory:
|
||||
|
||||
**mandatory option**
|
||||
@ -101,7 +91,6 @@ glossary
|
||||
set, that is the default value cannot be `None`, see
|
||||
:ref:`optionapi#optioninit`
|
||||
|
||||
|
||||
.. _consistency:
|
||||
|
||||
**consistency**
|
||||
|
||||
@ -10,14 +10,14 @@ Options API Details
|
||||
Description of Options
|
||||
----------------------
|
||||
|
||||
All the constructors take a ``name`` and a ``doc`` argument as first
|
||||
arguments to give the option or option group a name and to document it.
|
||||
Most constructors take a ``default`` argument that specifies the default
|
||||
value of the option. If this argument is not supplied the default value
|
||||
is assumed to be ``None``.
|
||||
All the constructors take a ``name`` and a ``doc`` argument as first
|
||||
arguments to give the option or option group a name and to document it.
|
||||
Most constructors take a ``default`` argument that specifies the default
|
||||
value of the option. If this argument is not supplied the default value
|
||||
is assumed to be ``None``.
|
||||
|
||||
Appart from that, the `Option` object is not supposed to contain any
|
||||
other value than the `tainted` attribute, which is explained later. The
|
||||
Appart from that, the `Option` object is not supposed to contain any
|
||||
other value than the `tainted` attribute, which is explained later. The
|
||||
container of the value is in the `Config` object.
|
||||
|
||||
``OptionDescription``
|
||||
@ -30,12 +30,12 @@ This class is used to group suboptions.
|
||||
``OptionDescription`` instances for nested namespaces).
|
||||
|
||||
``set_group_type(self, group_name)``
|
||||
Three available group_types : `default`, `family`, `group` and
|
||||
`master` (for master~slave group type). Notice that for a
|
||||
master~slave group, the name of the group and the name of the
|
||||
Three available group_types : `default`, `family`, `group` and
|
||||
`master` (for master~slave group type). Notice that for a
|
||||
master~slave group, the name of the group and the name of the
|
||||
master option are identical.
|
||||
|
||||
`Options description` objects lives in the `_cfgimpl_descr` config attribute.
|
||||
`Options description` objects lives in the `_cfgimpl_descr` config attribute.
|
||||
|
||||
If you need to access an option object, you can do it with the OptionDescription
|
||||
object. Not only the value of the option by attribute access, but the option
|
||||
@ -45,7 +45,7 @@ option named `name` in a `gc` group the `name` object can be accessed like
|
||||
this::
|
||||
|
||||
conf._cfgimpl_descr.name
|
||||
|
||||
|
||||
of sub configs with ::
|
||||
|
||||
conf.gc._cfgimpl_descr.name
|
||||
@ -53,7 +53,7 @@ of sub configs with ::
|
||||
This is a binding. The option objects are in the `_children` config's attribute.
|
||||
|
||||
Why accessing an option object ? It is possible for example freeze the
|
||||
configuration option
|
||||
configuration option
|
||||
|
||||
::
|
||||
|
||||
@ -67,7 +67,7 @@ generic option ``__init__`` method:
|
||||
|
||||
``__init__(name, doc, default=None, requires=None, multi=False, mandatory=False)``
|
||||
|
||||
:``default``: specifies the default value of the option.
|
||||
:``default``: specifies the default value of the option.
|
||||
:``requires``: is a list of names of options located anywhere in the configuration.
|
||||
:``multi``: means the value can be a list.
|
||||
:``mandatory``: see :ref:`glossary#mandatory`.
|
||||
@ -77,7 +77,7 @@ generic option ``__init__`` method:
|
||||
``BoolOption``
|
||||
++++++++++++++
|
||||
|
||||
Represents a choice between ``True`` and ``False``.
|
||||
Represents a choice between ``True`` and ``False``.
|
||||
|
||||
``IntOption``
|
||||
+++++++++++++
|
||||
@ -103,8 +103,8 @@ Redirects to another configuration option in the configuration, that is :
|
||||
- can set the value of the target too.
|
||||
|
||||
``__init__(self, name, path)``
|
||||
|
||||
`path` is the path to the target, the option
|
||||
|
||||
`path` is the path to the target, the option
|
||||
|
||||
``IPOption``
|
||||
+++++++++++++
|
||||
@ -124,4 +124,3 @@ Represents a choice out of several objects. The option can also have the value
|
||||
|
||||
``__init__(self, name, doc, values, default=None, requires=None)``
|
||||
``values`` is a list of values the option can possibly take.
|
||||
|
||||
|
||||
@ -1,82 +0,0 @@
|
||||
#!/usr/bin/python
|
||||
# unproudly borrowed from David Goodger's rst2html.py
|
||||
|
||||
"""
|
||||
A minimal front end to the Docutils Publisher, producing HTML.
|
||||
"""
|
||||
|
||||
try:
|
||||
import locale
|
||||
locale.setlocale(locale.LC_ALL, '')
|
||||
except:
|
||||
pass
|
||||
|
||||
from docutils.core import publish_cmdline, default_description
|
||||
# ____________________________________________________________
|
||||
from docutils import nodes, utils
|
||||
from docutils.parsers.rst import roles
|
||||
from docutils.writers import manpage
|
||||
|
||||
"""
|
||||
description of the new roles:
|
||||
|
||||
`:api:` : link to the code
|
||||
|
||||
- code.py becomes api/code.html
|
||||
- code.Code.code_test becomes api/code.Code.code_test.html
|
||||
- code.Code() becomes api/code.Code.html
|
||||
|
||||
`:doc:`a link to an internal file
|
||||
example become example.html
|
||||
|
||||
ref: link with anchor as in an external file
|
||||
|
||||
:ref:`toto#titi` becomes toto.html#titi
|
||||
"""
|
||||
from os.path import splitext
|
||||
|
||||
def api_reference_role(role, rawtext, text, lineno, inliner,
|
||||
options={}, content=[]):
|
||||
basename = text
|
||||
if "(" in text:
|
||||
basename = text.split("(")[0]
|
||||
if ".py" in text:
|
||||
basename = splitext(text)[0]
|
||||
if "test_" in text:
|
||||
refuri = "api/" + "tiramisu.test." + basename + '.html'
|
||||
else:
|
||||
refuri = "api/" + "tiramisu." + basename + '.html'
|
||||
roles.set_classes(options)
|
||||
node = nodes.reference(rawtext, utils.unescape(text), refuri=refuri,
|
||||
**options)
|
||||
return [node], []
|
||||
|
||||
roles.register_local_role('api', api_reference_role)
|
||||
|
||||
def doc_reference_role(role, rawtext, text, lineno, inliner,
|
||||
options={}, content=[]):
|
||||
refuri = text + '.html'
|
||||
roles.set_classes(options)
|
||||
node = nodes.reference(rawtext, utils.unescape(text), refuri=refuri,
|
||||
**options)
|
||||
return [node], []
|
||||
|
||||
roles.register_local_role('doc', doc_reference_role)
|
||||
|
||||
def ref_reference_role(role, rawtext, text, lineno, inliner,
|
||||
options={}, content=[]):
|
||||
fname, anchor = text.split('#')
|
||||
refuri = fname + '.html#' + anchor
|
||||
roles.set_classes(options)
|
||||
node = nodes.reference(rawtext, utils.unescape(anchor), refuri=refuri,
|
||||
**options)
|
||||
return [node], []
|
||||
|
||||
roles.register_local_role('ref', ref_reference_role)
|
||||
|
||||
# ____________________________________________________________
|
||||
|
||||
description = ("Generates plain unix manual documents. " + default_description)
|
||||
|
||||
publish_cmdline(writer=manpage.Writer(), description=description)
|
||||
|
||||
@ -5,13 +5,13 @@ Configuration status
|
||||
|
||||
:module: :api:`config.py`
|
||||
:tests: - :api:`test_option_owner.py`
|
||||
- :api:`test_option_type.py`
|
||||
- :api:`test_option_type.py`
|
||||
- :api:`test_option_default.py`
|
||||
|
||||
Available configuration statuses
|
||||
Available configuration statuses
|
||||
----------------------------------
|
||||
|
||||
These configuration statuses corresponds to specific global attributes :
|
||||
These configuration statuses corresponds to specific global attributes :
|
||||
|
||||
**read write status**
|
||||
|
||||
@ -21,15 +21,15 @@ These configuration statuses corresponds to specific global attributes :
|
||||
|
||||
To enable read-write status, call
|
||||
:api:`config.Config.cfgimpl_read_write()`
|
||||
|
||||
|
||||
**read only status**
|
||||
|
||||
The whole configuration is `frozen`, that is modifiying a value is
|
||||
forbidden. We can access to a configuration option only with the
|
||||
The whole configuration is `frozen`, that is modifiying a value is
|
||||
forbidden. We can access to a configuration option only with the
|
||||
`__getattr__` property.
|
||||
|
||||
|
||||
The configuration has not an access to the hidden options
|
||||
but can read the disabled options.
|
||||
but can read the disabled options.
|
||||
|
||||
To enable read only status, call :api:`config.Config.cfgimpl_read_only()`
|
||||
|
||||
@ -44,37 +44,38 @@ These configuration statuses corresponds to specific global attributes :
|
||||
Freezing a configuration
|
||||
---------------------------
|
||||
|
||||
At the configuration level, :api:`config.Config.cfgimpl_freeze()` freezes
|
||||
At the configuration level, :api:`config.Config.cfgimpl_freeze()` freezes
|
||||
the whole configuration options.
|
||||
|
||||
- :api:`test_option_type.test_frozen_value()`
|
||||
- :api:`test_option_type.test_freeze()`
|
||||
|
||||
.. _`frozen`:
|
||||
.. _`frozen`:
|
||||
|
||||
It is possible to *freeze* a single `Option` object with
|
||||
:api:`option.Option.freeze()`. If you try to modify a frozen option, it
|
||||
It is possible to *freeze* a single `Option` object with
|
||||
:api:`option.Option.freeze()`. If you try to modify a frozen option, it
|
||||
raises a `TypeError: trying to change a frozen option object`.
|
||||
|
||||
- :api:`test_option_type.test_freeze_one_option()`
|
||||
|
||||
Moreover, frozen option can return his default value if
|
||||
:api:`option.Option.force_default()` has been called on this option,
|
||||
Moreover, frozen option can return his default value if
|
||||
:api:`option.Option.force_default()` has been called on this option,
|
||||
see :api:`test_option_default.test_force_default_on_freeze()`
|
||||
|
||||
|
||||
Restricted access to an `Option()`
|
||||
-----------------------------------
|
||||
|
||||
Configuration options access statuses are defined at configuration level
|
||||
that corresponds to the :api:`option.Option()`'s `properties` attribute.
|
||||
Configuration options access statuses are defined at configuration level
|
||||
that corresponds to the :api:`option.Option()`'s `properties` attribute,
|
||||
for example
|
||||
|
||||
**hidden**
|
||||
|
||||
This means that an option raises an `HiddenOptionError` if we try to access
|
||||
the value of the option.
|
||||
This means that an option raises an error if we try to access
|
||||
the value of the option.
|
||||
|
||||
See `hide()` or `show()` in `Option()` that comes from
|
||||
See `hide()` or `show()` in `Option()` that comes from
|
||||
:api:`option.HiddenBaseType`
|
||||
|
||||
corresponding convenience API provided:
|
||||
@ -87,10 +88,10 @@ corresponding convenience API provided:
|
||||
|
||||
**disabled**
|
||||
|
||||
This means that an option *doesn't exists* (doesn't say anything
|
||||
This means that an option *doesn't exists* (doesn't say anything
|
||||
much more thant an `AttibuteAccess` error)
|
||||
|
||||
See in :api:`option.DisabledBaseType` the origins of
|
||||
See in :api:`option.DisabledBaseType` the origins of
|
||||
`Option.enable()` or `Option.disable()`
|
||||
|
||||
corresponding convenience API provided:
|
||||
@ -104,18 +105,18 @@ corresponding convenience API provided:
|
||||
Value owners
|
||||
-------------
|
||||
|
||||
Every configuration option has a **owner**. When the option is
|
||||
instanciated, the owner is `default` because a default value has been
|
||||
Every configuration option has a **owner**. When the option is
|
||||
instanciated, the owner is `default` because a default value has been
|
||||
set (including `None`, take a look at the tests).
|
||||
|
||||
The `value_owner` is the man who did it. Yes, the man who changed the value of the
|
||||
configuration option.
|
||||
configuration option.
|
||||
|
||||
- At the instance of the `Config` object, the value owner is `default` because
|
||||
the default values are set at the instance of the configuration option object,
|
||||
|
||||
::
|
||||
|
||||
|
||||
# let's expect there is an option named 'name'
|
||||
config = Config(descr, bool=False)
|
||||
# the override method has been called
|
||||
@ -143,29 +144,30 @@ configuration option.
|
||||
Special behaviors for an option
|
||||
---------------------------------
|
||||
|
||||
**auto**
|
||||
**mandatory**
|
||||
|
||||
This means that it is a calculated value and therefore automatically
|
||||
A mandatory option shall return a value. If a value, or a default value
|
||||
has not been set, a error is raised.
|
||||
|
||||
**has a callback**
|
||||
|
||||
This means that it is a calculated value and therefore automatically
|
||||
protected it cannot be modified by attribute access.
|
||||
|
||||
|
||||
Its inner state is represented by :api:`option.Option.has_callback()`
|
||||
and :api:`option.Option.hascallback_and_isfrozen()`
|
||||
|
||||
**fill**
|
||||
**force default**
|
||||
|
||||
if the configuration option has a default value, the default is
|
||||
returned, otherwise the value is calculated.
|
||||
|
||||
Its inner state is represented by :api:`option.Option.has_callback()`
|
||||
Its inner state is represented by :api:`option.Option.force_default()`
|
||||
|
||||
`default` value owner
|
||||
----------------------
|
||||
|
||||
Configuration options have default values that are stored in the
|
||||
`Option()` object itself. Default values, the `default`, can be set in
|
||||
Configuration options have default values that are stored in the
|
||||
`Option()` object itself. Default values, the `default`, can be set in
|
||||
various ways.
|
||||
|
||||
If a default value is modified by overriding it, not only the value of
|
||||
the option resets to the default that is proposed, but the owner is
|
||||
If a default value is modified by overriding it, not only the value of
|
||||
the option resets to the default that is proposed, but the owner is
|
||||
modified too, it is reseted to `default`.
|
||||
|
||||
|
||||
55
doc/todo.txt
55
doc/todo.txt
@ -45,40 +45,22 @@ alors que gc est un groupe
|
||||
|
||||
:date: 12 avril
|
||||
|
||||
- faire un mode dégradé avec des warnings
|
||||
- validations de longueur des maitres/esclaves ailleurs à sortir des requires
|
||||
et à mettre dans des validators
|
||||
|
||||
:date: 3 avril 2012
|
||||
|
||||
- hide sur les sous-sous groupe : il faut que ça hide **tout** les sous-groupe
|
||||
récursivement
|
||||
|
||||
groupes `master/slaves`:
|
||||
|
||||
faut-il coder les multi avec des requires, ou bien simplement
|
||||
un groupe avec comme variable le nom du groupe ?
|
||||
|
||||
auto, fill, obligatoire
|
||||
|
||||
2012-03-22
|
||||
|
||||
**groupe master**
|
||||
**groupe master**
|
||||
|
||||
faire une api du genre : `Option().is_master()`
|
||||
pour cela, tester `if self.parent._name == self._name: return True`
|
||||
|
||||
- mettre un attribut `auto` aux options de configuration, de manière à
|
||||
ce qu'elles sachent quelle fonction eos appeler (que ça soit une info
|
||||
dans l'option ou bien au niveau de la config ?)
|
||||
le fait de détecter un "auto" vient du owner, mais il faut savoir
|
||||
quelle fonction appeler
|
||||
|
||||
A documenter
|
||||
-------------
|
||||
|
||||
- les variables multiples
|
||||
- expliquer les urls du json dans la doc
|
||||
- documenter le typage des options descriptions descr_type
|
||||
|
||||
A ajouter
|
||||
@ -87,40 +69,5 @@ A ajouter
|
||||
Option -> attribut help (en plus de doc)
|
||||
get_help() (à mettre en class Type avec Doc aussi)
|
||||
|
||||
separator -> pas pour l'instant
|
||||
|
||||
fill, auto, obligatoire
|
||||
|
||||
nouveau type :
|
||||
|
||||
type option (dérivé de ChoiceOPtion) dans lequel il y a des nouvelles valeurs
|
||||
possibles (pas de validations) ou plutôt une StringOption qui propose un choix
|
||||
de valeurs par défault de type liste.
|
||||
|
||||
:date: 24 mars
|
||||
|
||||
- hide pour les sous-sous config (récursivement) et pas seulement une
|
||||
seule sous-config (ou bien, quelque chose de réglable)
|
||||
|
||||
- validate global : vérifier à l'init de la conf qu'une variable
|
||||
n'existe pas déjà, etc
|
||||
|
||||
:date: 26 janvier
|
||||
|
||||
- un attribut eosfunc pour auto + les paramètres à donner à la fonction
|
||||
pareil pour le fill (function et paramètres)
|
||||
|
||||
reset
|
||||
-------
|
||||
|
||||
**à discuter** : ça correspond exactement au override,
|
||||
ou bien au opt.setoption(None, 'default')
|
||||
|
||||
**si la valeur par défaut est définie, un __get__ ne pourra jamais
|
||||
renvoyer None.** ce qui est bloquant. Il faut pouvoir revenir à None.
|
||||
|
||||
pour supprimer la valeur d'une options (et revenir à la valeur par défault)
|
||||
cfg.reset() (supprime _cfgimpl_value[name]) et _cfgimpl_value_owner[name])
|
||||
|
||||
reset()
|
||||
|
||||
|
||||
Reference in New Issue
Block a user