getting stated documentation
This commit is contained in:
gwen
14
doc/api.txt
Normal file
14
doc/api.txt
Normal file
@ -0,0 +1,14 @@
|
||||
Auto generated library's API
|
||||
================================
|
||||
|
||||
.. autosummary::
|
||||
:toctree: api
|
||||
:template: module.rst
|
||||
|
||||
tiramisu.option
|
||||
tiramisu.setting
|
||||
tiramisu.config
|
||||
tiramisu.value
|
||||
tiramisu.autolib
|
||||
tiramisu.error
|
||||
|
||||
332
doc/config.txt
332
doc/config.txt
@ -156,13 +156,339 @@ let's come back to the default value
|
||||
>>> print c.od1.var2
|
||||
value
|
||||
|
||||
The value is saved in a :class:`~tiramisu.value.Value` object.
|
||||
It is on this object that we have to trigger the `reset`
|
||||
The value is saved in a :class:`~tiramisu.value.Value` object. It is on this
|
||||
object that we have to trigger the `reset`, wich take the option itself
|
||||
(`var2`) as a parameter.
|
||||
|
||||
On the other side, in the `read_only` mode, it is not possible to modify the value::
|
||||
|
||||
>>> 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
|
||||
|
||||
let's retrieve the option `var1` description
|
||||
|
||||
>>> var1.impl_get_information('doc')
|
||||
'first variable'
|
||||
|
||||
And if the option has been lost, it is possible to retrieve it again:
|
||||
|
||||
>>> c.unwrap_from_path('od1.var1').impl_get_information('doc')
|
||||
'first variable'
|
||||
|
||||
Searching for an option
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In an application, knowing the path of an option is not always feasible.
|
||||
That's why a tree of options can easily be searched. First, let's build such a tree::
|
||||
|
||||
>>> var1 = UnicodeOption('var1', '')
|
||||
>>> var2 = UnicodeOption('var2', '')
|
||||
>>> var3 = UnicodeOption('var3', '')
|
||||
>>> od1 = OptionDescription('od1', '', [var1, var2, var3])
|
||||
>>> var4 = UnicodeOption('var4', '')
|
||||
>>> var5 = UnicodeOption('var5', '')
|
||||
>>> var6 = UnicodeOption('var6', '')
|
||||
>>> var7 = UnicodeOption('var1', '', u'value')
|
||||
>>> od2 = OptionDescription('od2', '', [var4, var5, var6, var7])
|
||||
>>> rootod = OptionDescription('rootod', '', [od1, od2])
|
||||
>>> c = Config(rootod)
|
||||
>>> c.read_write()
|
||||
|
||||
Second, let's find an option by his name::
|
||||
|
||||
>>> print c.find(byname='var1')
|
||||
[<tiramisu.option.UnicodeOption object at 0x7ff1bf7d6ef0>,
|
||||
<tiramisu.option.UnicodeOption object at 0x7ff1b90c7290>]
|
||||
|
||||
If the option name is unique, the search can be stopped once one matched option
|
||||
has been found:
|
||||
|
||||
>>> print c.find_first(byname='var1')
|
||||
<tiramisu.option.UnicodeOption object at 0x7ff1bf7d6ef0>
|
||||
|
||||
Instead of the option's object, the value or path can be retrieved:
|
||||
|
||||
>>> print c.find(byname='var1', type_='value')
|
||||
[None, u'value']
|
||||
>>> print c.find(byname='var1', type_='path')
|
||||
['od1.var1', 'od2.var1']
|
||||
|
||||
Finaly, a search can be performed on the values, the type or even a combination
|
||||
of all these criteria:
|
||||
|
||||
|
||||
>>> print c.find(byvalue=u'value', type_='path')
|
||||
['od2.var1']
|
||||
>>> print c.find(bytype=UnicodeOption, type_='path')
|
||||
['od1.var1', 'od1.var2', 'od1.var3', 'od2.var4', 'od2.var5', 'od2.var6', 'od2.var1']
|
||||
>>> print c.find(byvalue=u'value', byname='var1', bytype=UnicodeOption, type_='path')
|
||||
['od2.var1']
|
||||
|
||||
The search can be performed in a subtree:
|
||||
|
||||
>>> print c.od1.find(byname='var1', type_='path')
|
||||
['od1.var1']
|
||||
|
||||
Configuration's interesting methods
|
||||
In a root tree or in a subtree, all option can be retrieved in a dict container:
|
||||
|
||||
>>> print c.make_dict()
|
||||
{'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 'od2.var1': u'value',
|
||||
'od1.var1': None, 'od1.var3': None, 'od1.var2': None}
|
||||
|
||||
If the organisation in a tree is not important,
|
||||
:meth:`~config.SubConfig.make_dict()` results can be flattened
|
||||
|
||||
>>> print c.make_dict(flatten=True)
|
||||
{'var5': None, 'var4': None, 'var6': None, 'var1': u'value', 'var3': None,
|
||||
'var2': None}
|
||||
|
||||
.. note:: 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
|
||||
example the options that are in the same group that a given `var1` option::
|
||||
|
||||
>>> print c.make_dict(withoption='var1')
|
||||
{'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 'od2.var1': u'value',
|
||||
'od1.var1': None, 'od1.var3': None, 'od1.var2': None}
|
||||
>>> print c.make_dict(withoption='var1', withvalue=u'value')
|
||||
{'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 'od2.var1': u'value'}
|
||||
|
||||
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
|
||||
~~~~~~~~~~~
|
||||
|
||||
When a value is set on an option, an owner is set too, that's why one can know
|
||||
at any time if a value is a default value or not. Let's create a tree::
|
||||
|
||||
>>> var1 = UnicodeOption('var1', '', u'oui')
|
||||
>>> od1 = OptionDescription('od1', '', [var1])
|
||||
>>> rootod = OptionDescription('rootod', '', [od1])
|
||||
>>> c = Config(rootod)
|
||||
>>> c.read_write()
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
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'))
|
||||
>>> var4 = UnicodeOption('var4', '', u'value')
|
||||
>>> od1 = OptionDescription('od1', '', [var1, var2, var3])
|
||||
>>> od2 = OptionDescription('od2', '', [var4], properties=('hidden',))
|
||||
>>> rootod = OptionDescription('rootod', '', [od1, od2])
|
||||
>>> c = Config(rootod)
|
||||
>>> c.read_write()
|
||||
|
||||
A hidden value is a value that cannot be accessed in read/write mode. This
|
||||
option cannot be modified any more. Let's try to access to an option's value
|
||||
with a hidden option::
|
||||
|
||||
>>> print c.od1.var1
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named: var1
|
||||
with properties ['hidden']
|
||||
>>> c.read_only()
|
||||
>>> print c.od1.var1
|
||||
value
|
||||
|
||||
A mandatory option is an option with a value that shall not be `None`. The
|
||||
value has to be defined. Accessing to such an option is easy in read/write
|
||||
mode. But in read only mode, an error is raised if no value has been defined::
|
||||
|
||||
>>> c.read_write()
|
||||
>>> print c.od1.var2
|
||||
None
|
||||
>>> c.read_only()
|
||||
>>> print c.od1.var2
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named: var2
|
||||
with properties ['mandatory']
|
||||
>>> c.read_write()
|
||||
>>> c.od1.var2 = u'value'
|
||||
>>> c.read_only()
|
||||
>>> print c.od1.var2
|
||||
value
|
||||
|
||||
A frozen option, is an option that cannot be modified by a user.
|
||||
Let's try to modify a frozen option::
|
||||
|
||||
>>> c.read_write()
|
||||
>>> print c.od1.var3
|
||||
value
|
||||
>>> c.od1.var3 = u'value2'
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: cannot change the value for option var3 this option is frozen
|
||||
>>> c.read_only()
|
||||
>>> print c.od1.var3
|
||||
value
|
||||
|
||||
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')
|
||||
>>> 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')
|
||||
>>> print c.od1.var3
|
||||
value
|
||||
|
||||
Properties can also be defined on option groups,
|
||||
(that is, on :ref:`option description`s), let's hide a group and try to access to it::
|
||||
|
||||
>>> c.read_write()
|
||||
>>> print c.od2.var4
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named: od2
|
||||
with properties ['hidden']
|
||||
>>> c.read_only()
|
||||
>>> print c.od2.var4
|
||||
value
|
||||
|
||||
Furthermore, let's retrieve the properties, delete and add the `hidden` property::
|
||||
|
||||
>>> c.read_write()
|
||||
>>> c.cfgimpl_get_settings()[rootod.od1.var1]
|
||||
['hidden']
|
||||
>>> print c.od1.var1
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named:
|
||||
var1 with properties ['hidden']
|
||||
>>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('hidden')
|
||||
>>> c.cfgimpl_get_settings()[rootod.od1.var1]
|
||||
[]
|
||||
>>> print c.od1.var1
|
||||
value
|
||||
>>> c.cfgimpl_get_settings()[rootod.od1.var1].append('hidden')
|
||||
>>> c.cfgimpl_get_settings()[rootod.od1.var1]
|
||||
['hidden']
|
||||
>>> print c.od1.var1
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named:
|
||||
var1 with properties ['hidden']
|
||||
|
||||
The requirements
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Let's create an option wich has requirements::
|
||||
|
||||
>>> var1 = UnicodeOption('var1', '', u'value', requires=(('od1.var2',
|
||||
'non', 'hidden'),))
|
||||
>>> var2 = UnicodeOption('var2', '', u'oui')
|
||||
>>> var3 = UnicodeOption('var3', '', u'value', requires=(('od1.var2',
|
||||
'non', 'hidden'), ('od1.var2', 'non', 'disabled')))
|
||||
>>> var4 = UnicodeOption('var4', '', u'oui')
|
||||
>>>
|
||||
>>> od1 = OptionDescription('od1', '', [var1, var2, var3])
|
||||
>>> od2 = OptionDescription('od2', '', [var4], requires=(('od1.var2',
|
||||
'oui', 'hidden', True),))
|
||||
>>> rootod = OptionDescription('rootod', '', [od1, od2])
|
||||
>>> c = Config(rootod)
|
||||
>>> c.read_write()
|
||||
|
||||
The requirement here is the tuple `('od1.var2' , 'non', 'hidden')` wich means
|
||||
that is the option `'od1.var2'` is set to `'non'`, the option `'od1.var1'` is
|
||||
gonna be hidden. On the other hand, if the option `'od1.var2'` is different
|
||||
from `'non'`, the option `'od1.var1'` is not hidden any more::
|
||||
|
||||
>>> print c.cfgimpl_get_settings()[rootod.od1.var1]
|
||||
[]
|
||||
>>> print c.od1.var1
|
||||
value
|
||||
>>> print c.od1.var2
|
||||
oui
|
||||
>>> c.od1.var2 = u'non'
|
||||
>>> print c.cfgimpl_get_settings()[rootod.od1.var1]
|
||||
['hidden']
|
||||
>>> print c.od1.var1
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named:
|
||||
var1 with properties ['hidden']
|
||||
>>> c.od1.var2 = u'oui'
|
||||
>>> print c.cfgimpl_get_settings()[rootod.od1.var1]
|
||||
[]
|
||||
>>> print c.od1.var1
|
||||
value
|
||||
|
||||
The requirement on `od2` is `('od1.var2', 'oui', 'hidden', True)`, which means
|
||||
that if the option `od1.var2` is set to `oui`, the option is not hidden
|
||||
(because of the `True` at the end of the tuple wich means 'inverted', take a
|
||||
look at the :doc:`consistency` document.)::
|
||||
|
||||
>>> print c.od2.var4
|
||||
oui
|
||||
>>> c.od1.var2 = u'non'
|
||||
>>> print c.od2.var4
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
tiramisu.error.PropertiesOptionError: trying to access to an option named: od2 with properties ['hidden']
|
||||
>>> c.od1.var2 = u'oui'
|
||||
>>> print c.od2.var4
|
||||
oui
|
||||
|
||||
Requirements can be accumulated
|
||||
|
||||
>>> print c.cfgimpl_get_settings()[rootod.od1.var3]
|
||||
[]
|
||||
>>> c.od1.var2 = u'non'
|
||||
>>> print c.cfgimpl_get_settings()[rootod.od1.var3]
|
||||
['disabled', 'hidden']
|
||||
>>> c.od1.var2 = u'oui'
|
||||
>>> print c.cfgimpl_get_settings()[rootod.od1.var3]
|
||||
[]
|
||||
|
||||
Requirements can be accumulated for different or identical properties (inverted
|
||||
or not)::
|
||||
|
||||
>>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non',
|
||||
'hidden'), ('od1.var1', 'oui', 'hidden')))
|
||||
>>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non',
|
||||
'hidden'), ('od1.var1', 'oui', 'disabled', True)))
|
||||
|
||||
But it is not possible to have inverted requirements on the same property.
|
||||
Here is an impossible situation::
|
||||
|
||||
>>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non',
|
||||
'hidden'), ('od1.var1', 'oui', 'hidden', True)))
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
ValueError: inconsistency in action types for option: var3 action: hidden
|
||||
|
||||
|
||||
Configuration's interesting methods
|
||||
------------------------------------------
|
||||
|
||||
A `Config` object is informed by an `option.OptionDescription`
|
||||
|
||||
@ -22,10 +22,10 @@ The tasting of `Tiramisu`
|
||||
.. _`options controller tool`: http://en.wikipedia.org/wiki/Configuration_management#Overview
|
||||
|
||||
|
||||
It's a pretty small, local (that is, straight on the operating system) options
|
||||
It's a pretty small, local (that is, straight on the operating system) options
|
||||
handler and controller.
|
||||
|
||||
controlling options explanations
|
||||
controlling options explanations
|
||||
--------------------------------------
|
||||
|
||||
.. toctree::
|
||||
@ -38,23 +38,9 @@ controlling options explanations
|
||||
consistency
|
||||
error
|
||||
glossary
|
||||
api
|
||||
doctest
|
||||
|
||||
|
||||
auto generated library's API
|
||||
--------------------------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: api
|
||||
:template: module.rst
|
||||
|
||||
tiramisu.option
|
||||
tiramisu.setting
|
||||
tiramisu.config
|
||||
tiramisu.value
|
||||
tiramisu.autolib
|
||||
tiramisu.error
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
@ -62,12 +48,9 @@ Indices and tables
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
This work is licensed under a `Creative Commons Attribution-ShareAlike 3.0 Unported License`_.
|
||||
.. note:: This documentation 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::
|
||||
|
||||
|
||||
|
||||
|
||||
.. todolist::
|
||||
|
||||
Reference in New Issue
Block a user