update doc

This commit is contained in:
Emmanuel Garette 2013-09-14 14:44:33 +02:00
parent 3afcf0322c
commit abbb7a274e
6 changed files with 114 additions and 50 deletions

View File

@ -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')
[<tiramisu.option.UnicodeOption object at 0x7ff1bf7d6ef0>,
@ -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')
>>> print c.getowner(var1)
default
>>> c.od1.var1 = u'non'
>>> print c.getowner('var1')
>>> c.od1.var1 = u'no'
>>> print c.getowner(var1)
user
>>> del(c.var1)
>>> print c.getowner('var1')
>>> print c.getowner(var1)
default
the properties
~~~~~~~~~~~~~~~~
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

View File

@ -33,8 +33,8 @@ controlling options explanations
getting-started
config
storage
option
storage
status
consistency
error

View File

@ -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:

View File

@ -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

View File

@ -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)

View File

@ -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()``.
"""