From defae40a2f4ea185de2ce3030f8da7f07ff0d9e0 Mon Sep 17 00:00:00 2001 From: gwen Date: Wed, 21 Aug 2013 11:09:11 +0200 Subject: [PATCH] documentation update and docstrings --- doc/consistency.txt | 3 +-- doc/glossary.txt | 51 +++++++++++++-------------------------------- doc/index.txt | 5 +++++ doc/status.txt | 39 +++++++++++++++++++++------------- tiramisu/value.py | 37 ++++++++++++++++++++++++++------ 5 files changed, 76 insertions(+), 59 deletions(-) diff --git a/doc/consistency.txt b/doc/consistency.txt index b7d0ddf..16d9eab 100644 --- a/doc/consistency.txt +++ b/doc/consistency.txt @@ -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 ---------------------------------------------- diff --git a/doc/glossary.txt b/doc/glossary.txt index a23136e..32e9052 100644 --- a/doc/glossary.txt +++ b/doc/glossary.txt @@ -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` + + diff --git a/doc/index.txt b/doc/index.txt index 441b639..e5b9e12 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -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:: + + + + + diff --git a/doc/status.txt b/doc/status.txt index f7f9183..5fac59c 100644 --- a/doc/status.txt +++ b/doc/status.txt @@ -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`. + diff --git a/tiramisu/value.py b/tiramisu/value.py index 60b9255..0cd1c0f 100644 --- a/tiramisu/value.py +++ b/tiramisu/value.py @@ -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) # ____________________________________________________________