finalise the doc for the 1.0 release
This commit is contained in:
gwen
parent
a6213f2189
commit
92a61a91cd
|
|
@ -13,10 +13,11 @@ Tiramisu is made of almost three main objects :
|
|||
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
|
||||
of the `Option`, and the value is the value accessed by the `__getattr__`
|
||||
attribute access mechanism.
|
||||
The :class:`~tiramisu.config.Config` object attribute access notation stands for
|
||||
the value of the configuration's :class:`~tiramisu.option.Option`. That is, the
|
||||
: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.
|
||||
|
||||
If the attribute of the `Config` called by `__getattr__` has not been set before
|
||||
(by the classic `__setattr__` mechanism), the default value of the `Option`
|
||||
|
|
@ -26,23 +27,27 @@ object is returned, and if no `Option` has been declared in the
|
|||
|
||||
::
|
||||
|
||||
>>> from tiramisu.config import Config
|
||||
>>> from tiramisu.option import BoolOption, OptionDescription
|
||||
>>>
|
||||
>>> gcdummy = BoolOption('dummy', 'dummy', default=False)
|
||||
>>> gcdummy.getdefault()
|
||||
>>> gcdummy.impl_getdefault()
|
||||
False
|
||||
>>> cfg.dummy
|
||||
False
|
||||
>>> descr = OptionDescription('tiramisu', '', [gcdummy])
|
||||
>>> cfg = Config(descr)
|
||||
>>> cfg.dummy
|
||||
False
|
||||
>>> cfg.dummy = True
|
||||
>>> cfg.dummy
|
||||
True
|
||||
>>> cfg.idontexist
|
||||
AttributeError: 'OptionDescription' object has no attribute 'idontexist'
|
||||
|
||||
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``.
|
||||
The `Option` objects (in this case the :class:`~tiramisu.option.BoolOption`),
|
||||
are organized into a tree into nested
|
||||
:class:`~tiramisu.option.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):
|
||||
|
|
@ -59,19 +64,18 @@ Let's make the protocol of accessing a config's attribute explicit
|
|||
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.
|
||||
:term:`mandatory option`. A mandatory option is an option that must have a value
|
||||
defined.
|
||||
|
||||
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()`
|
||||
method.
|
||||
|
||||
If you know the path:
|
||||
Appart from this case, 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::
|
||||
::
|
||||
|
||||
>>> config.gc.dummy
|
||||
>>> cfg.cfgimpl_get_values().reset(gcdummy)
|
||||
>>> cfg.dummy
|
||||
False
|
||||
|
||||
Setting the values of the options
|
||||
|
|
@ -103,7 +107,6 @@ 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
|
||||
------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,6 @@ of the same type.
|
|||
For example, an :class:`option.IntOption` validator waits for an `int` object of
|
||||
course, an :class:`option.StrOption` validator waits for an `str`, vs...
|
||||
|
||||
|
||||
Where are located the values
|
||||
-------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,11 @@
|
|||
Test framework
|
||||
==================
|
||||
|
||||
Have a look at the :file:`test` subdirectory of the project.
|
||||
We are using py.test_
|
||||
|
||||
.. _py.test: http://pytest.org/latest/
|
||||
|
||||
|
||||
config APIs
|
||||
-----------------
|
||||
|
|
@ -11,9 +16,86 @@ config APIs
|
|||
option APIs
|
||||
---------------
|
||||
|
||||
|
||||
.. automodule:: test.test_option
|
||||
:members:
|
||||
|
||||
|
||||
others
|
||||
----------
|
||||
|
||||
.. automodule:: test.test_config_api
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_mandatory
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_config_big_example
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_default
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_consistency
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_cache
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_setting
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_config
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_freeze
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_config_ip
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_slots
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_reverse_from_path
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_requires
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_owner
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_permissive
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_type
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_dereference
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_storage
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_calculation
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_option_with_special_name
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_config_domain
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_symlink
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_metaconfig
|
||||
:members:
|
||||
|
||||
.. automodule:: test.test_parsing_group
|
||||
:members:
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,9 +6,9 @@ What is options handling ?
|
|||
=================================
|
||||
|
||||
Due to more and more available options required to set up an operating system,
|
||||
to set up compiler options, and so on. 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
|
||||
compiler options or whatever, 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 control was
|
||||
introduced...
|
||||
|
||||
What is Tiramisu ?
|
||||
|
|
@ -18,10 +18,8 @@ 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, options can be reached and changed according to the access
|
||||
rules from nearly everywhere in your appliance.
|
||||
validations towards the whole options. Furthermore, options can be reached and
|
||||
changed according to the access rules from nearly everywhere in your appliance.
|
||||
|
||||
Just the facts
|
||||
==============
|
||||
|
|
@ -32,7 +30,7 @@ Download
|
|||
---------
|
||||
|
||||
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.
|
||||
We suggest using `git` if one wants to access to the current developments.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -52,29 +50,32 @@ manipulations:
|
|||
|
||||
>>> from tiramisu.config import Config
|
||||
>>> from tiramisu.option import OptionDescription, BoolOption
|
||||
>>> # let's create a group of options... with only one option inside
|
||||
>>> descr = OptionDescription("optgroup", "", [
|
||||
... BoolOption("bool", "", default=False)])
|
||||
>>>
|
||||
>>> # c is a namespace as well as a container for the options
|
||||
>>> c = Config(descr)
|
||||
>>> # now we have a container, wich contains an option:
|
||||
>>> c.bool
|
||||
False
|
||||
>>> c.bool = True
|
||||
>>> c.bool
|
||||
True
|
||||
|
||||
|
||||
So by now, we have
|
||||
So by now, we have:
|
||||
|
||||
- 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:
|
||||
attribute access way (here `bool`, wich is a boolean option
|
||||
: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
|
||||
and consistent.
|
||||
So, option objects are produced at the entry point `c` and then handed down to
|
||||
where they are actually used when `c.bool` is triggered. This keeps options
|
||||
local but available at any timer and consistent.
|
||||
|
||||
The namespace is created, we can set a `read_write` access to the options::
|
||||
Once the namespace is created, we can set a
|
||||
:meth:`~config.CommonConfig.read_write()` access to the options::
|
||||
|
||||
>>> c.read_write()
|
||||
|
||||
which enables us to set a bunch of access rules that we wil explain later in
|
||||
:doc:`status`.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
.. default-role:: literal
|
||||
|
||||
.. module:: tiramisu.option
|
||||
|
||||
The options types
|
||||
===================
|
||||
|
||||
|
|
@ -12,24 +14,6 @@ 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``.
|
||||
|
||||
|
||||
.. _optdescr:
|
||||
|
||||
The `OptionDescription` class
|
||||
-------------------------------
|
||||
|
||||
.. module:: tiramisu.option
|
||||
|
||||
.. autoclass:: OptionDescription
|
||||
:special-members:
|
||||
:members:
|
||||
|
||||
|
||||
If you need to access an option object, you can do it with the OptionDescription
|
||||
object. Not only the value of the option by attribute access, but the option
|
||||
object itself that lives behind the scene. It can always be accessed internally.
|
||||
The option objects are in the `_children` `OptionDescription`'s attribute.
|
||||
|
||||
The `Option` base class
|
||||
-------------------------
|
||||
|
||||
|
|
@ -83,3 +67,18 @@ configuration, that is :
|
|||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. _optdescr:
|
||||
|
||||
The `OptionDescription` class
|
||||
-------------------------------
|
||||
|
||||
.. autoclass:: OptionDescription
|
||||
:special-members:
|
||||
:members:
|
||||
|
||||
|
||||
If you need to access to an option object, you can do it with the
|
||||
OptionDescription object. Not only the value of the option by attribute access,
|
||||
but the option object itself that lives behind the scene. It can always be
|
||||
accessed internally. The option objects are in the `_children`
|
||||
`OptionDescription`'s attribute.
|
||||
|
|
|
|||
Loading…
Reference in New Issue