Merge branch 'master' of ssh://git.labs.libre-entreprise.org/gitroot/tiramisu
This commit is contained in:
commit
5beade8b2c
|
@ -0,0 +1,6 @@
|
|||
{{ fullname }}
|
||||
{{ underline }}
|
||||
|
||||
.. automodule:: {{ fullname }}
|
||||
:members:
|
||||
:noindex:
|
|
@ -0,0 +1,6 @@
|
|||
tiramisu.autolib
|
||||
================
|
||||
|
||||
.. automodule:: tiramisu.autolib
|
||||
:members:
|
||||
:noindex:
|
|
@ -0,0 +1,6 @@
|
|||
tiramisu.config
|
||||
===============
|
||||
|
||||
.. automodule:: tiramisu.config
|
||||
:members:
|
||||
:noindex:
|
|
@ -0,0 +1,6 @@
|
|||
tiramisu.error
|
||||
==============
|
||||
|
||||
.. automodule:: tiramisu.error
|
||||
:members:
|
||||
:noindex:
|
|
@ -0,0 +1,6 @@
|
|||
tiramisu.option
|
||||
===============
|
||||
|
||||
.. automodule:: tiramisu.option
|
||||
:members:
|
||||
:noindex:
|
|
@ -0,0 +1,5 @@
|
|||
tiramisu.setting
|
||||
================
|
||||
|
||||
.. automodule:: tiramisu.setting
|
||||
:members:
|
|
@ -0,0 +1,5 @@
|
|||
tiramisu.value
|
||||
==============
|
||||
|
||||
.. automodule:: tiramisu.value
|
||||
:members:
|
21
doc/conf.py
21
doc/conf.py
|
@ -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
|
||||
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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()
|
||||
|
|
|
@ -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
|
||||
==================
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
.. default-role:: literal
|
||||
|
||||
The options
|
||||
===============
|
||||
The options types
|
||||
===================
|
||||
|
||||
Description of Options
|
||||
----------------------
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue