automatic API documentation
This commit is contained in:
gwen
parent
0db7ef72a6
commit
f235986879
3 changed files with 103 additions and 43 deletions
|
|
@ -1,7 +1,7 @@
|
|||
.. default-role:: literal
|
||||
|
||||
===============================
|
||||
Configuration handling basics
|
||||
Options handling basics
|
||||
===============================
|
||||
|
||||
Tiramisu is made of almost three main objects :
|
||||
|
|
@ -10,8 +10,8 @@ Tiramisu is made of almost three main objects :
|
|||
- :class:`tiramisu.option.Option` stands for the option types
|
||||
- :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
|
||||
|
||||
Accessing the configuration `Option`'s
|
||||
-----------------------------------------
|
||||
Accessing the `Option`'s
|
||||
-------------------------
|
||||
|
||||
The `Config` object attribute access notation stands for the value of the
|
||||
configuration's `Option`. That is, the `Config`'s object attribute is the name
|
||||
|
|
@ -41,11 +41,10 @@ object is returned, and if no `Option` has been declared in the
|
|||
>>> cfg.idontexist
|
||||
AttributeError: 'OptionDescription' object has no attribute 'idontexist'
|
||||
|
||||
The configuration `Option` objects (in this case the `BoolOption`), are
|
||||
organized into a tree into nested `OptionDescription` objects. Every
|
||||
option has a name, as does every option group. The parts of the full
|
||||
name of the option are separated by dots: e.g.
|
||||
``config.optgroup.optname``.
|
||||
The `Option` objects (in this case the `BoolOption`), are organized into a tree
|
||||
into nested `OptionDescription` objects. Every option has a name, 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
|
||||
(because explicit is better than implicit):
|
||||
|
|
@ -61,10 +60,10 @@ Let's make the protocol of accessing a config's attribute explicit
|
|||
4. If an option is declared, and a value has been set, the returned value is
|
||||
the value of the option.
|
||||
|
||||
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 defined value.
|
||||
If no value have been set yet, the value is `None`.
|
||||
When the option is called to retrieve a value, an exception is raised.
|
||||
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 defined value.
|
||||
If no value have been set yet, the value is `None`.
|
||||
When the option is called to retrieve a value, an exception is raised.
|
||||
|
||||
What if a value has been set and `None` is to be returned again ? Don't
|
||||
worry, an option value can be "reseted" with the help of the `option.Option.reset()`
|
||||
|
|
@ -106,6 +105,63 @@ bundled into a configuration object which has a reference to its option
|
|||
description (and therefore makes sure that the configuration values
|
||||
adhere to the option description).
|
||||
|
||||
|
||||
Common manipulations
|
||||
------------------------
|
||||
|
||||
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])
|
||||
|
||||
let's set somme access rules on the main namespace
|
||||
|
||||
>>> c = Config(rootod)
|
||||
>>> c.read_write()
|
||||
|
||||
let's travel the namespaces
|
||||
|
||||
>>> print c
|
||||
[od1]
|
||||
>>> print c.od1
|
||||
var1 = None
|
||||
var2 = value
|
||||
>>> print c.od1.var1
|
||||
None
|
||||
>>> print c.od1.var2
|
||||
value
|
||||
|
||||
let's modify a value (careful to the value's type...)
|
||||
|
||||
>>> c.od1.var1 = 'value'
|
||||
Traceback (most recent call last):
|
||||
[...]
|
||||
ValueError: invalid value value for option var1
|
||||
>>> c.od1.var1 = u'value'
|
||||
>>> print c.od1.var1
|
||||
value
|
||||
>>> c.od1.var2 = u'value2'
|
||||
>>> print c.od1.var2
|
||||
value2
|
||||
|
||||
let's come back to the default value
|
||||
|
||||
>>> del(c.od1.var2)
|
||||
>>> 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`
|
||||
|
||||
|
||||
|
||||
|
||||
Configuration's interesting methods
|
||||
------------------------------------------
|
||||
|
||||
|
|
@ -123,11 +179,11 @@ Here are the (useful) methods on ``Config`` (or `SubConfig`).
|
|||
:members: find, find_first, __iter__, iter_groups, iter_all, make_dict
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Summary
|
||||
|
||||
.. autosummary::
|
||||
|
||||
|
||||
find
|
||||
find_first
|
||||
|
||||
|
|
@ -139,10 +195,10 @@ Here are the (useful) methods on ``Config`` (or `SubConfig`).
|
|||
|
||||
.. rubric:: Methods
|
||||
|
||||
|
||||
A :class:`~config.CommonConfig` is a abstract base class. A
|
||||
:class:`~config.SubConfig` is an just in time created objects that wraps an
|
||||
::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
|
||||
::fact that a config is a root object and has an environnement, a context wich
|
||||
::defines the different properties, access rules, vs... There is generally only
|
||||
|
||||
A :class:`~config.CommonConfig` is a abstract base class. A
|
||||
:class:`~config.SubConfig` is an just in time created objects that wraps an
|
||||
::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
|
||||
::fact that a config is a root object and has an environnement, a context wich
|
||||
::defines the different properties, access rules, vs... There is generally only
|
||||
::one Config, and many SubConfigs.
|
||||
|
|
|
|||
|
|
@ -5,22 +5,22 @@ Getting started
|
|||
What is options handling ?
|
||||
=================================
|
||||
|
||||
Due to more and more available options required to set up an operating system,
|
||||
to set up compiler options, vs... it became quite annoying to hand the
|
||||
necessary options to where they are actually used and even more annoying to add
|
||||
new options. To circumvent these problems the configuration management was
|
||||
Due to more and more available options required to set up an operating system,
|
||||
to set up compiler options, vs... it became quite annoying to hand the
|
||||
necessary options to where they are actually used and even more annoying to add
|
||||
new options. To circumvent these problems the configuration management was
|
||||
introduced...
|
||||
|
||||
What is Tiramisu ?
|
||||
===================
|
||||
|
||||
Tiramisu is an options handler and an options controller, wich aims at
|
||||
producing flexible and fast options access. The main advantages are its access
|
||||
Tiramisu is an options handler and an options controller, wich aims at
|
||||
producing flexible and fast options access. The main advantages are its access
|
||||
rules and the fact that the whole consistency is preserved at any time, see
|
||||
:doc:`consistency`. There is of course type and structure validations, but also
|
||||
:doc:`consistency`. There is of course type and structure validations, but also
|
||||
validations towards the whole options.
|
||||
|
||||
Last but not least, options can be reached and changed according to the access
|
||||
Last but not least, options can be reached and changed according to the access
|
||||
rules from nearly everywhere in your appliance.
|
||||
|
||||
Just the facts
|
||||
|
|
@ -31,21 +31,21 @@ Just the facts
|
|||
Download
|
||||
---------
|
||||
|
||||
To obtain a copy of the sources, check it out from the repository using `git`.
|
||||
To obtain a copy of the sources, check it out from the repository using `git`.
|
||||
We suggest using `git` if one wants to access the current developments.
|
||||
|
||||
::
|
||||
|
||||
git clone git://git.labs.libre-entreprise.org/tiramisu.git
|
||||
|
||||
This will get you a fresh checkout of the code repository in a local directory
|
||||
This will get you a fresh checkout of the code repository in a local directory
|
||||
named ``tiramisu``.
|
||||
|
||||
Getting started
|
||||
-------------------
|
||||
|
||||
Option objects can be created in different ways. Let's perform very basic
|
||||
:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
|
||||
Option objects can be created in different ways. Let's perform very basic
|
||||
:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
|
||||
manipulations:
|
||||
|
||||
::
|
||||
|
|
@ -55,22 +55,26 @@ manipulations:
|
|||
>>> descr = OptionDescription("optgroup", "", [
|
||||
... BoolOption("bool", "", default=False)])
|
||||
>>>
|
||||
>>> config = Config(descr)
|
||||
>>> # now we have a config, wich contains an option:
|
||||
>>> config.bool
|
||||
>>> c = Config(descr)
|
||||
>>> # now we have a container, wich contains an option:
|
||||
>>> c.bool
|
||||
False
|
||||
>>> config.bool = True
|
||||
>>> config.bool
|
||||
>>> c.bool = True
|
||||
>>> c.bool
|
||||
True
|
||||
|
||||
|
||||
So by now, we have
|
||||
|
||||
- a namespace (which is `config` here)
|
||||
- a namespace (which is `c` here)
|
||||
- the access of an option's value by the
|
||||
attribute access way (here `bool`, wich is a boolean option:
|
||||
:class:`tiramisu.option.BoolOption()`.
|
||||
:class:`~tiramisu.option.BoolOption()`.
|
||||
|
||||
So, option objects are produced at the entry point and then handed down to
|
||||
where they are actually used. This keeps options local but available everywhere
|
||||
So, option objects are produced at the entry point and then handed down to
|
||||
where they are actually used. This keeps options local but available everywhere
|
||||
and consistent.
|
||||
|
||||
The namespace is created, we can set a `read_write` access to the options::
|
||||
|
||||
>>> c.read_write()
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.. default-role:: literal
|
||||
|
||||
The options
|
||||
===============
|
||||
The options types
|
||||
===================
|
||||
|
||||
Description of Options
|
||||
----------------------
|
||||
|
|
|
|||
Loading…
Reference in a new issue