documentation update

This commit is contained in:
gwen 2013-08-20 16:38:06 +02:00
parent 564fecc261
commit 5c8bb1f8f9
4 changed files with 57 additions and 32 deletions

View File

@ -1,7 +1,9 @@
.. default-role:: literal .. default-role:: literal
.. currentmodule:: tiramisu
The global consistency The global consistency
======================================== ===========================
Identical option names Identical option names
---------------------- ----------------------
@ -19,12 +21,15 @@ 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 `option.Option()` validator's type. option's :class:`option.Option()` validator's type.
Notice that if the option is `multi`, that is the `multi` attribute is set to 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 `True`, then the validation of the option value accepts a list of values
of the same type. 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...
Requirements Requirements
------------ ------------

View File

@ -46,3 +46,5 @@ Indices and tables
This work is licensed under a `Creative Commons Attribution-ShareAlike 3.0 Unported License`_. This work is licensed under a `Creative Commons Attribution-ShareAlike 3.0 Unported License`_.
.. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US .. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US
.. todolist::

View File

@ -6,7 +6,9 @@ Local statuses and global setting
Available configuration statuses Available configuration statuses
---------------------------------- ----------------------------------
The configuration's status lives in an `setting.Setting` object. .. currentmodule:: tiramisu
The configuration's status lives in an :class:`setting.Setting()` object.
This configuration status corresponds to specific attributes or bunch of This configuration status corresponds to specific attributes or bunch of
attributes that can be accessed together with some `setting.Setting` attributes that can be accessed together with some `setting.Setting`
method: method:
@ -18,7 +20,7 @@ method:
possible to modify a disabled option. possible to modify a disabled option.
To enable read-write status, call To enable read-write status, call
`congi.Config.read_write()` :class:`config.CommonConfig.read_write()`
**read only status** **read only status**
@ -29,7 +31,7 @@ method:
The configuration has not an access to the hidden options 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 `config.Config.read_only()` To enable read only status, call :class:`config.SubConfig.read_only()`
.. csv-table:: **Configuration's statuses summary** .. csv-table:: **Configuration's statuses summary**
:header: " ", "Hidden", "Disabled", "Mandatory" :header: " ", "Hidden", "Disabled", "Mandatory"
@ -42,24 +44,24 @@ method:
Freezing a configuration Freezing a configuration
--------------------------- ---------------------------
.. todo:: freeze at configuration level
At the configuration level, `setting.Setting.freeze` freezes At the configuration level, `setting.Setting.freeze` freezes
the whole configuration options. the whole configuration options.
- `test_option_type.test_frozen_value()`
- `test_option_type.test_freeze()`
.. _`frozen`: .. _`frozen`:
It is possible to *freeze* a single `Option` object with It is possible to *freeze* a single :class:`option.Option()` object with
`option.Option.freeze()`. If you try to modify a frozen option, it :meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen
raises a `TypeError: trying to change a frozen option object`. :option, it raises a `TypeError: trying to change a frozen option object`.
- `test_option_type.test_freeze_one_option()` To find out if an option `myoption` is frozen, just make an assertion on the
settings like that::
Moreover, frozen option can return his default value if
`option.Option.force_default()` has been called on this option, 'frozen' in cfg.cfgimpl_get_settings()[myoption]
see `test_option_default.test_force_default_on_freeze()`
Moreover, frozen option can return their default values if
`option.Option.force_default()` is called on this option.
Restricted access to an `Option()` Restricted access to an `Option()`
----------------------------------- -----------------------------------
@ -97,19 +99,23 @@ to activate, deactivate properties::
Value owners Value owners
------------- -------------
.. method:: tiramisu.config.Config.getowner()
Every configuration option has a **owner**. When the option is instanciated,
the owner is :obj:`setting.owners.default` because a default value has been set
(including `None`, wich means that no value has been set yet).
.. method:: config.CommonConfig.getowner()
This method can retrieve an Option's owner. This method can retrieve an Option's owner.
Every configuration option has a **owner**. When the option is - At the instance of the `Config` object, the value owner is
instanciated, the owner is `default` because a default value has been :obj:`setting.owners.default` because
set (including `None`, take a look at the tests). the default values are set at the instance of the configuration option
object,
- At the instance of the `Config` object, the value owner is `owners.default` because
the default values are set at the instance of the configuration option object,
- at the modification of an option, the owner is `owners.default`, (which is `user`)
- at the modification of an option, the owner is `owners.default`, (which is
:obj:`owners.user`)
Special behaviors for an option Special behaviors for an option
--------------------------------- ---------------------------------

View File

@ -261,22 +261,34 @@ class Setting(object):
def validate_properties(self, opt_or_descr, is_descr, is_write, def validate_properties(self, opt_or_descr, is_descr, is_write,
value=None, force_permissive=False, value=None, force_permissive=False,
force_properties=None): force_properties=None):
#opt properties """
validation upon the properties related to `opt_or_descr`
:param opt_or_descr: an option or an option description object
:param force_permissive: behaves as if the permissive property was present
:param is_descr: we have to know if we are in an option description,
just because the mandatory property doesn't exist there
:param is_write: in the validation process, an option is to be modified,
the behavior can be different (typically with the `frozen`
property)
"""
# opt properties
properties = copy(self._get_properties(opt_or_descr)) properties = copy(self._get_properties(opt_or_descr))
#remove opt permissive # remove opt permissive
properties -= self._get_permissive(opt_or_descr) properties -= self._get_permissive(opt_or_descr)
#remove global permissive if need # remove global permissive if need
self_properties = copy(self._get_properties()) self_properties = copy(self._get_properties())
if force_permissive is True or 'permissive' in self_properties: if force_permissive is True or 'permissive' in self_properties:
properties -= self._get_permissive() properties -= self._get_permissive()
#global properties # global properties
if force_properties is not None: if force_properties is not None:
self_properties.update(force_properties) self_properties.update(force_properties)
#calc properties # calc properties
properties &= self_properties properties &= self_properties
#mandatory and frozen are special properties # mandatory and frozen are special properties
if is_descr: if is_descr:
properties -= frozenset(('mandatory', 'frozen')) properties -= frozenset(('mandatory', 'frozen'))
else: else:
@ -288,7 +300,7 @@ class Setting(object):
properties.add('frozen') properties.add('frozen')
elif 'frozen' in properties and not is_write: elif 'frozen' in properties and not is_write:
properties.remove('frozen') properties.remove('frozen')
# at this point an option should not remain in properties
if properties != frozenset(): if properties != frozenset():
props = list(properties) props = list(properties)
if 'frozen' in properties: if 'frozen' in properties: