From abbb7a274eba723f51a3c20f6e0c55ceacc66de3 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sat, 14 Sep 2013 14:44:33 +0200 Subject: [PATCH] update doc --- doc/config.txt | 80 +++++++++++++++++++++--------------- doc/index.txt | 2 +- doc/option.txt | 53 +++++++++++++++++++++--- doc/storage.txt | 16 ++++---- tiramisu/option.py | 5 ++- tiramisu/storage/__init__.py | 8 +++- 6 files changed, 114 insertions(+), 50 deletions(-) diff --git a/doc/config.txt b/doc/config.txt index 2118f4c..3c6d9bc 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -6,15 +6,17 @@ Options handling basics Tiramisu is made of almost three main objects : -- :class:`tiramisu.config.Config` which is the whole configuration entry point - :class:`tiramisu.option.Option` stands for the option types - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure +- :class:`tiramisu.config.Config` which is the whole configuration entry point + +.. image:: config.png Accessing the `Option`'s ------------------------- The :class:`~tiramisu.config.Config` object attribute access notation stands for -the value of the configuration's :class:`~tiramisu.option.Option`. That is, the +the value of the configuration's :class:`~tiramisu.option.Option`. :class:`~tiramisu.config.Config`'s object attribute is the name of the option, and the value is the value accessed by the `__getattr__` attribute access mechanism. @@ -49,7 +51,7 @@ are organized into a tree into nested as does every option group. The parts of the full name of the option are separated by dots: e.g. ``cfg.optgroup.optname``. -Let's make the protocol of accessing a config's attribute explicit +Let's make the protocol of accessing a `Config`'s attribute explicit (because explicit is better than implicit): 1. If the option has not been declared, an `AttributeError` is raised, @@ -67,11 +69,11 @@ But there are special exceptions. We will see later on that an option can be a :term:`mandatory option`. A mandatory option is an option that must have a value defined. -Setting the values of the options ----------------------------------------- +Setting the value of an option +------------------------------ -An important part of the setting of the configuration consists of setting the -values of the configuration options. There are different ways of setting values, +An important part of the setting's configuration consists of setting the +value's option. There are different ways of setting values, the first one is of course the `__setattr__` method :: @@ -103,10 +105,10 @@ Let's perform some common manipulation on some options >>> from tiramisu.config import Config >>> from tiramisu.option import UnicodeOption, OptionDescription ->>> +>>> # >>> var1 = UnicodeOption('var1', 'first variable') >>> var2 = UnicodeOption('var2', '', u'value') ->>> +>>> # >>> od1 = OptionDescription('od1', 'first OD', [var1, var2]) >>> rootod = OptionDescription('rootod', '', [od1]) @@ -127,10 +129,11 @@ None >>> print c.od1.var2 value -let's modify a value (careful to the value's type...) +let's modify a value (be careful to the value's type...) >>> c.od1.var1 = 'value' -Traceback (most recent call last): ValueError: invalid value value for option var1 +Traceback (most recent call last): +ValueError: invalid value value for option var1 >>> c.od1.var1 = u'value' >>> print c.od1.var1 value @@ -153,7 +156,8 @@ On the other side, in the `read_only` mode, it is not possible to modify the val >>> c.read_only() >>> c.od1.var2 = u'value2' Traceback (most recent call last): -tiramisu.error.PropertiesOptionError: cannot change the value to var2 for option ['frozen'] this option is frozen +tiramisu.error.PropertiesOptionError: cannot change the value for option var2 this option is frozen + let's retrieve the option `var1` description @@ -184,7 +188,7 @@ That's why a tree of options can easily be searched. First, let's build such a t >>> c = Config(rootod) >>> c.read_write() -Second, let's find an option by his name:: +Second, let's find an option by it's name:: >>> print c.find(byname='var1') [, @@ -232,7 +236,7 @@ If the organisation in a tree is not important, {'var5': None, 'var4': None, 'var6': None, 'var1': u'value', 'var3': None, 'var2': None} -.. note:: carefull with this `flatten` parameter, here we have just lost +.. note:: be carefull with this `flatten` parameter, here we have just lost two options named `var1` One can export only interesting parts of a tree of options into a dict, for @@ -249,7 +253,7 @@ and of course, :meth:`~config.SubConfig.make_dict()` can be called in a subtree: >>> print c.od1.make_dict(withoption='var1') {'var1': None, 'var3': None, 'var2': None} -the owners +The owners ~~~~~~~~~~~ .. glossary:: @@ -267,24 +271,36 @@ the owners Then let's retrieve the owner associated to an option:: - >>> print c.getowner('var1') - default - >>> c.od1.var1 = u'non' - >>> print c.getowner('var1') - user - >>> del(c.var1) - >>> print c.getowner('var1') - default - -the properties -~~~~~~~~~~~~~~~~ + >>> print c.getowner(var1) + default + >>> c.od1.var1 = u'no' + >>> print c.getowner(var1) + user + >>> del(c.var1) + >>> print c.getowner(var1) + default + +You can create your own owner, for example to distinguish modification made by +one user to an other one's. + + >>> from tiramisu.setting import owners + >>> owners.addowner('toto') + >>> c.cfgimpl_get_settings().setowner(owners.toto) + >>> print c.getowner(var1) + default + >>> c.od1.var1 = u'no' + >>> print c.getowner(var1) + toto + +The properties +~~~~~~~~~~~~~~ A property is an information on an option's state. Let's create options with properties:: >>> var1 = UnicodeOption('var1', '', u'value', properties=('hidden',)) >>> var2 = UnicodeOption('var2', '', properties=('mandatory',)) - >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'inconnu')) + >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'unknown')) >>> var4 = UnicodeOption('var4', '', u'value') >>> od1 = OptionDescription('od1', '', [var1, var2, var3]) >>> od2 = OptionDescription('od2', '', [var4], properties=('hidden',)) @@ -338,17 +354,17 @@ Let's try to modify a frozen option:: Tiramisu allows us to use user defined properties. Let's define and use one in read/write or read only mode:: - >>> c.cfgimpl_get_settings().append('inconnu') + >>> c.cfgimpl_get_settings().append('unknown') >>> print c.od1.var3 Traceback (most recent call last): tiramisu.error.PropertiesOptionError: trying to access to an option named: - var3 with properties ['inconnu'] - >>> c.cfgimpl_get_settings().remove('inconnu') + var3 with properties ['unknown'] + >>> c.cfgimpl_get_settings().remove('unknown') >>> print c.od1.var3 value -Properties can also be defined on an option group, (that is, on an -:term:`option description`), let's hide a group and try to access to it:: +Properties can also be defined on an option group (that is, on an +:term:`option description`) let's hide a group and try to access to it:: >>> c.read_write() >>> print c.od2.var4 diff --git a/doc/index.txt b/doc/index.txt index c073d99..1a55ca4 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -33,8 +33,8 @@ controlling options explanations getting-started config - storage option + storage status consistency error diff --git a/doc/option.txt b/doc/option.txt index 90dea0a..47053b8 100644 --- a/doc/option.txt +++ b/doc/option.txt @@ -9,7 +9,7 @@ Description of Options ---------------------- All the constructors take a ``name`` and a ``doc`` argument as first -arguments to give the option or option group a name and to document it. +arguments to give to the option or option description a name and a description document. Most constructors take a ``default`` argument that specifies the default value of the option. If this argument is not supplied the default value is assumed to be ``None``. @@ -17,7 +17,7 @@ is assumed to be ``None``. The `Option` base class ------------------------- -It's the abstract base class for almost all options (except the symblink). +It's the abstract base class for almost all options (except the symlink). .. _optioninit: @@ -28,22 +28,41 @@ It's the abstract base class for almost all options (except the symblink). All option types ------------------ +BoolOption +~~~~~~~~~~ + .. autoclass:: BoolOption :private-members: +IntOption +~~~~~~~~~ + .. autoclass:: IntOption :private-members: +FloatOption +~~~~~~~~~~~ + .. autoclass:: FloatOption :private-members: +StrOption +~~~~~~~~~ + .. autoclass:: StrOption :private-members: +UnicodeOption +~~~~~~~~~~~~~ + +.. autoclass:: UnicodeOption + :private-members: + +SymLinkOption +~~~~~~~~~~~~~ .. autoclass:: SymLinkOption - - .. automethod:: __init__ + :private-members: ``SymLinkOption`` redirects to another configuration option in the @@ -52,19 +71,41 @@ configuration, that is : - retrieves the value of the target, - can set the value of the target too +IPOption +~~~~~~~~ .. autoclass:: IPOption + :private-members: + +PortOption +~~~~~~~~~~ + +.. autoclass:: PortOption + :private-members: + +NetmaskOption +~~~~~~~~~~~~~ .. autoclass:: NetmaskOption + :private-members: + +NetworkOption +~~~~~~~~~~~~~ .. autoclass:: NetworkOption + :private-members: + +DomainnameOption +~~~~~~~~~~~~~~~~ .. autoclass:: DomainnameOption + :private-members: +ChoiceOption +~~~~~~~~~~~~ .. autoclass:: ChoiceOption - - .. automethod:: __init__ + :private-members: .. _optdescr: diff --git a/doc/storage.txt b/doc/storage.txt index 8ff5d93..6bfb18c 100644 --- a/doc/storage.txt +++ b/doc/storage.txt @@ -1,18 +1,12 @@ Storage ======= -Config's informations are, by default, volatiles. This means, all values and -settings changes will be lost. - -The storage is the system Tiramisu uses to communicate with various DB. -You can specified a persistent storage. - -.. image:: storage.png - .. automodule:: tiramisu.storage .. automethod:: tiramisu.storage.set_storage +.. image:: storage.png + Dictionary ~~~~~~~~~~ @@ -49,4 +43,10 @@ Example >>> c2 = Config(o, persistent=True, session_id='xxxx') >>> c2.str 'yes' +>>> del(c2) +>>> list_sessions() +['xxxx'] +>>> delete_session('xxxx') +>>> c3 = Config(o, persistent=True, session_id='xxxx') +>>> c3.str diff --git a/tiramisu/option.py b/tiramisu/option.py index 6d7f3b3..313299d 100644 --- a/tiramisu/option.py +++ b/tiramisu/option.py @@ -319,7 +319,7 @@ class Option(BaseOption): """ Abstract base class for configuration option's. - Reminder: an Option object is **not** a container for the value + Reminder: an Option object is **not** a container for the value. """ __slots__ = ('_multi', '_validator', '_default_multi', '_default', '_callback', '_multitype', '_master_slaves', '__weakref__') @@ -342,9 +342,10 @@ class Option(BaseOption): :param callback: the name of a function. If set, the function's output is responsible of the option's value :param callback_params: the callback's parameter - :param validator: the name of a function wich stands for a custom + :param validator: the name of a function which stands for a custom validation of the value :param validator_args: the validator's parameters + :param properties: tuple of default properties """ super(Option, self).__init__(name, doc, requires, properties) diff --git a/tiramisu/storage/__init__.py b/tiramisu/storage/__init__.py index 147d8a8..1394258 100644 --- a/tiramisu/storage/__init__.py +++ b/tiramisu/storage/__init__.py @@ -19,7 +19,13 @@ # the whole pypy projet is under MIT licence # ____________________________________________________________ -"""Storage is basic components used to set Config informations in DB. +"""Config's informations are, by default, volatiles. This means, all values and +settings changes will be lost. + +The storage is the system Tiramisu uses to communicate with various DB. +You can specified a persistent storage. + +Storage is basic components used to set Config informations in DB. The primary "entry point" class is the StorageType and it's public configurator ``set_storage()``. """