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
.. currentmodule:: tiramisu
The global consistency
========================================
===========================
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
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
`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...
Requirements
------------

View File

@ -46,3 +46,5 @@ Indices and tables
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
.. todolist::

View File

@ -6,7 +6,9 @@ Local statuses and global setting
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
attributes that can be accessed together with some `setting.Setting`
method:
@ -18,7 +20,7 @@ method:
possible to modify a disabled option.
To enable read-write status, call
`congi.Config.read_write()`
:class:`config.CommonConfig.read_write()`
**read only status**
@ -29,7 +31,7 @@ method:
The configuration has not an access to the hidden 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**
:header: " ", "Hidden", "Disabled", "Mandatory"
@ -42,24 +44,24 @@ method:
Freezing a configuration
---------------------------
.. todo:: freeze at configuration level
At the configuration level, `setting.Setting.freeze` freezes
the whole configuration options.
- `test_option_type.test_frozen_value()`
- `test_option_type.test_freeze()`
.. _`frozen`:
It is possible to *freeze* a single `Option` object with
`option.Option.freeze()`. If you try to modify a frozen option, it
raises a `TypeError: trying to change a frozen option object`.
It is possible to *freeze* a single :class:`option.Option()` object with
:meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen
:option, it raises a `TypeError: trying to change a frozen option object`.
- `test_option_type.test_freeze_one_option()`
Moreover, frozen option can return his default value if
`option.Option.force_default()` has been called on this option,
see `test_option_default.test_force_default_on_freeze()`
To find out if an option `myoption` is frozen, just make an assertion on the
settings like that::
'frozen' in cfg.cfgimpl_get_settings()[myoption]
Moreover, frozen option can return their default values if
`option.Option.force_default()` is called on this option.
Restricted access to an `Option()`
-----------------------------------
@ -97,19 +99,23 @@ to activate, deactivate properties::
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.
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).
- 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 instance of the `Config` object, the value owner is
:obj:`setting.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
:obj:`owners.user`)
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,
value=None, force_permissive=False,
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))
#remove opt permissive
# remove opt permissive
properties -= self._get_permissive(opt_or_descr)
#remove global permissive if need
# remove global permissive if need
self_properties = copy(self._get_properties())
if force_permissive is True or 'permissive' in self_properties:
properties -= self._get_permissive()
#global properties
# global properties
if force_properties is not None:
self_properties.update(force_properties)
#calc properties
# calc properties
properties &= self_properties
#mandatory and frozen are special properties
# mandatory and frozen are special properties
if is_descr:
properties -= frozenset(('mandatory', 'frozen'))
else:
@ -288,7 +300,7 @@ class Setting(object):
properties.add('frozen')
elif 'frozen' in properties and not is_write:
properties.remove('frozen')
# at this point an option should not remain in properties
if properties != frozenset():
props = list(properties)
if 'frozen' in properties: