update doc
This commit is contained in:
Emmanuel Garette
parent
3afcf0322c
commit
abbb7a274e
6 changed files with 114 additions and 50 deletions
|
|
@ -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')
|
||||
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
|
||||
|
|
|
|||
|
|
@ -33,8 +33,8 @@ controlling options explanations
|
|||
|
||||
getting-started
|
||||
config
|
||||
storage
|
||||
option
|
||||
storage
|
||||
status
|
||||
consistency
|
||||
error
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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()``.
|
||||
"""
|
||||
|
|
|
|||
Loading…
Reference in a new issue