Infra/tiramisu
5
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

documentation update and docstrings

Browse Source
This commit is contained in:
gwen 2013-08-21 11:09:11 +02:00
parent 1b608202ce
commit defae40a2f
5 changed files with 76 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/consistency.txt
View File

@ -47,8 +47,7 @@ third one is the callback's action name (`hide`, `show`...)::
stroption = StrOption('str', 'Test string option', default="abc",
requires=[('int', 1, 'hide')])
Take a look at an example here
`test_option_consistency.test_hidden_if_in()`
Requirements are validated in :class:`setting.Setting`.
Validation upon a whole configuration object
----------------------------------------------

51
doc/glossary.txt
View File

@ -10,8 +10,6 @@ Glossary
Global configuration object, wich contains the whole configuration
options *and* their descriptions (option types and group)
.. glossary::
schema
option description
@ -24,14 +22,15 @@ Glossary
- how they are organised in groups or even subgroups, that's why we
call them **groups** too.
.. glossary::
configuration option
An option object wich has a name and a value and can be accessed
from the configuration object
.. glossary::
access rules
Global access rules are : :meth:`~config.CommonConfig.read_write()` or
:meth:`~config.Config.read_only()`, see :doc:`status`
default value
@ -39,69 +38,49 @@ Glossary
set at instanciation time, or even at any moment. Remember that if
you reset the default value, the owner reset to `default`
.. glossary::
acces rules
Access rules are : `config.Config.read_write()` or
`config.Config.read_only()`, see :doc:`status`
.. glossary::
freeze
A whole configuration can be frozen (used in read only access). See
`status#frozenconfig` for details.
:ref:`frozen` for details.
A single option can be frozen too.
.. glossary::
forced on freeze
A single option is frozen and we want the option to return something
else than his value, typically his default value, see
`status#frozen`
.. glossary::
value owner
When an option is modified, including at the instanciation, we
always know who has modified it. It's the owner of the option, see
:doc:`status` for more details.
.. glossary::
option with properties
an option wich has property like 'hidden' or 'disabled' is an option
wich has restricted acces rules
.. glossary::
hidden option
a hidden option has a different behaviour on regards to the access
of the value in the configuration, see :doc:`status` for more details.
.. glossary::
disabled option
a disabled option has a different behaviour on regards to the access
of the value in the configuration, see :doc:`status` for more details.
.. glossary::
mandatory option
A mandatory option is a configuration option wich value has to be
set, that is the default value cannot be `None`.
.. glossary::
consistency
Preserve the consistency in a whole configuration is a tricky thing,
Preserving the consistency in a whole configuration is a tricky thing,
tiramisu takes care of it for you, see :doc:`consistency` for details.
context
The context is a :class:`tiramisu.setting.Setting()` object in the
configuration that enables us to access to the global properties
for example the `read_write` or `read_only` :term:`access rules`

5
doc/index.txt
View File

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

39
doc/status.txt
View File

@ -40,21 +40,18 @@ method:
"read only status", `False`, `True`, `True`
"read-write status", `True`, `False`, `False`
.. _`frozenconfig`:
.. _`frozen`:
Freezing a configuration
---------------------------
.. todo:: freeze at configuration level
At the configuration level, :class:`~setting.Setting()` enables us to freeze the
whole configuration, wich means that the frozen :class:`~option.Option()`'s
values cannot be modified.
At the configuration level, `setting.Setting.freeze` freezes
the whole configuration options.
.. _`frozen`:
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`.
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`.
To find out if an option `myoption` is frozen, just make an assertion on the
settings like that::
@ -62,14 +59,22 @@ 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.
:meth:`~option.Option.force_default()` is called on this option.
.. glossary::
force default on freeze
A single option is frozen and we want the option to return something
else than his value, typically it is his default value.
In the option's values, an attribute can be set
:attr:`force_default_on_freeze`, that forces this behavior.
Restricted access to an `Option()`
-----------------------------------
.. currentmodule:: tiramisu.setting
.. autoclass:: Property
.. autoclass:: tiramisu.setting.Property
The `properties` attribute is in charge of the access rules' option's value.
@ -97,10 +102,13 @@ to activate, deactivate properties::
cfg.cfgimpl_get_settings().append('hidden')
cfg.cfgimpl_get_settings().remove('hidden')
The global properties are living in e :class:`~setting.Setting` object. A
`Setting` object also takes care of the way to access option values and the
storage in the cache.
Value owners
-------------
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).
@ -144,3 +152,4 @@ 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
modified too, it is reseted to `owners.default`.

37
tiramisu/value.py
View File

@ -67,7 +67,7 @@ class Values(object):
"return value or default value if not set"
key = self._getkey(opt)
if not self._p_.hasvalue(key):
#if no value
# if no value
value = self._getdefault(opt)
if opt.impl_is_multi():
value = Multi(value, self.context, opt, validate)
@ -75,7 +75,7 @@ class Values(object):
#if value
value = self._p_.getvalue(key)
if opt.impl_is_multi() and not isinstance(value, Multi):
#load value so don't need to validate if is not a Multi
# load value so don't need to validate if is not a Multi
value = Multi(value, self.context, opt, validate=False)
return value
@ -86,6 +86,10 @@ class Values(object):
return self._p_.hasvalue('value', self._getkey(opt))
def __delitem__(self, opt):
"""overrides the builtins `del()` instructions
if you use this you are responsible for all bad things happening
"""
self.reset(opt)
def reset(self, opt):
@ -173,7 +177,7 @@ class Values(object):
value = [value for i in range(lenmaster)]
if opt.impl_is_multi():
value = Multi(value, self.context, opt, validate)
#suppress value if already set
# suppress value if already set
self.reset(opt)
# frozen and force default
elif is_frozen and 'force_default_on_freeze' in setting[opt]:
@ -197,9 +201,9 @@ class Values(object):
self.setitem(opt, value)
def setitem(self, opt, value, force_permissive=False, is_write=True):
#is_write is, for example, used with "force_store_value"
#user didn't change value, so not write
#valid opt
# is_write is, for example, used with "force_store_value"
# user didn't change value, so not write
# valid opt
opt.impl_validate(value, self.context,
'validator' in self.context.cfgimpl_get_settings())
if opt.impl_is_multi() and not isinstance(value, Multi):
@ -221,6 +225,12 @@ class Values(object):
self._p_.setvalue(self._getkey(opt), value, owner)
def getowner(self, opt):
"""
retrieves the option's owner
:param opt: the `option.Option` object
:returns: a `setting.owners.Owner` object
"""
if isinstance(opt, SymLinkOption):
opt = opt._opt
owner = self._p_.getowner(self._getkey(opt), owners.default)
@ -230,6 +240,12 @@ class Values(object):
return owner
def setowner(self, opt, owner):
"""
sets a owner to an option
:param opt: the `option.Option` object
:param owner: a valid owner, that is a `setting.owners.Owner` object
"""
if not isinstance(owner, owners.Owner):
raise TypeError(_("invalid generic owner {0}").format(str(owner)))
if self.getowner(opt) == owners.default:
@ -246,12 +262,21 @@ class Values(object):
return self.getowner(opt) == owners.default
def reset_cache(self, only_expired):
"""
clears the cache if necessary
"""
if only_expired:
self._p_.reset_expired_cache('value', time())
else:
self._p_.reset_all_cache('value')
def _get_opt_path(self, opt):
"""
retrieve the option's path in the config
:param opt: the `option.Option` object
:returns: a string with points like "gc.dummy.my_option"
"""
return self.context.cfgimpl_get_description().impl_get_path_by_opt(opt)
# ____________________________________________________________