Merge branch 'master' of ssh://git.labs.libre-entreprise.org/gitroot/tiramisu

This commit is contained in:
Emmanuel Garette 2013-08-23 16:49:27 +02:00
commit 5beade8b2c
15 changed files with 184 additions and 68 deletions

6
doc/_templates/module.rst vendored Normal file
View File

@ -0,0 +1,6 @@
{{ fullname }}
{{ underline }}
.. automodule:: {{ fullname }}
:members:
:noindex:

View File

@ -0,0 +1,6 @@
tiramisu.autolib
================
.. automodule:: tiramisu.autolib
:members:
:noindex:

View File

@ -0,0 +1,6 @@
tiramisu.config
===============
.. automodule:: tiramisu.config
:members:
:noindex:

View File

@ -0,0 +1,6 @@
tiramisu.error
==============
.. automodule:: tiramisu.error
:members:
:noindex:

View File

@ -0,0 +1,6 @@
tiramisu.option
===============
.. automodule:: tiramisu.option
:members:
:noindex:

View File

@ -0,0 +1,5 @@
tiramisu.setting
================
.. automodule:: tiramisu.setting
:members:

View File

@ -0,0 +1,5 @@
tiramisu.value
==============
.. automodule:: tiramisu.value
:members:

View File

@ -41,16 +41,16 @@ master_doc = 'index'
# General information about the project.
project = u'tiramisu'
copyright = u'2012, gwen'
copyright = u'2013, tiramisu team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0'
version = '1'
# The full version, including alpha/beta/rc tags.
release = '18'
release = '1.0RC1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -91,15 +91,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme_options = {
"rightsidebar": "true",
"nosidebar": "false",
"sidebarbgcolor": "black",
"relbarbgcolor": "black",
"footerbgcolor": "black"
}
html_theme = 'traditional'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -296,3 +288,8 @@ todo_include_todos = True
extlinks = {'api': ('./api/tiramisu.%s', ""),
'test': ('./api/test.%s', "")}
autosummary_generate = True

View File

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

View File

@ -2,26 +2,26 @@
Getting started
==================================
What is Configuration handling ?
What is options handling ?
=================================
Due to more and more available configuration options required to set up
an operating system, 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...
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 yet another configuration handler, wich aims at producing flexible
and fast configuration options access. The main advantages are its access rules
and the fact that the configuration's consistency is preserved at any time, see
:doc:`consistency`. There is of course type and structure validations, but also
validations towards the whole configuration.
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
validations towards the whole options.
Last but not least, configuration options can be reached and changed
according to the access rules from nearly everywhere in your appliance.
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,22 @@ 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
-------------------
Configuration option objects can be created in different ways. Let's perform
very basic :class:`tiramisu.config.Config` object manipulations:
Option objects can be created in different ways. Let's perform very basic
:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
manipulations:
::
@ -54,22 +55,26 @@ very basic :class:`tiramisu.config.Config` object 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()`.
Configuration option objects :class:`tiramisu.config.Config()` are produced at
the entry point and then handed down to where they are actually used. This
keeps configuration local but available everywhere and consistent.
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()

View File

@ -17,13 +17,16 @@ The tasting of `Tiramisu`
is a cool, refreshing Italian dessert,
it is also a `configuration management tool`_.
it is also an `options controller tool`_.
.. _`configuration management tool`: http://en.wikipedia.org/wiki/Configuration_management
.. _`options controller tool`: http://en.wikipedia.org/wiki/Configuration_management#Overview
It's a pretty small, local (that is, straight on the operating system)
configuration handler.
It's a pretty small, local (that is, straight on the operating system) options
handler and controller.
controlling options explanations
--------------------------------------
.. toctree::
:maxdepth: 1
@ -35,7 +38,22 @@ configuration handler.
consistency
error
glossary
test
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
==================

View File

@ -1,7 +1,7 @@
.. default-role:: literal
The options
===============
The options types
===================
Description of Options
----------------------

View File

@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
"pretty small and local configuration management tool"
"options handler global entry point"
# Copyright (C) 2012-2013 Team tiramisu (see AUTHORS for all contributors)
#
# This program is free software; you can redistribute it and/or modify

View File

@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
"option types and option description for the configuration management"
"option types and option description"
# Copyright (C) 2012-2013 Team tiramisu (see AUTHORS for all contributors)
#
# This program is free software; you can redistribute it and/or modify