documentation update
This commit is contained in:
parent
564fecc261
commit
5c8bb1f8f9
|
@ -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
|
||||
------------
|
||||
|
||||
|
|
|
@ -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::
|
||||
|
|
|
@ -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
|
||||
---------------------------------
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
|
Loading…
Reference in New Issue