From 5c8bb1f8f92d78e0533f0360255c3c893103ac2b Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 20 Aug 2013 16:38:06 +0200 Subject: [PATCH] documentation update --- doc/consistency.txt | 9 ++++++-- doc/index.txt | 2 ++ doc/status.txt | 52 +++++++++++++++++++++++++-------------------- tiramisu/setting.py | 26 +++++++++++++++++------ 4 files changed, 57 insertions(+), 32 deletions(-) diff --git a/doc/consistency.txt b/doc/consistency.txt index 73d3671..31e9817 100644 --- a/doc/consistency.txt +++ b/doc/consistency.txt @@ -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 ------------ diff --git a/doc/index.txt b/doc/index.txt index 17dc35f..441b639 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -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:: diff --git a/doc/status.txt b/doc/status.txt index 524a7b8..87a62c0 100644 --- a/doc/status.txt +++ b/doc/status.txt @@ -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 --------------------------------- diff --git a/tiramisu/setting.py b/tiramisu/setting.py index 37c08e6..94c26a5 100644 --- a/tiramisu/setting.py +++ b/tiramisu/setting.py @@ -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: