tiramisu/doc/status.txt

175 lines
5.0 KiB
Plaintext
Raw Normal View History

.. default-role:: literal
2013-05-17 12:11:14 +02:00
.. TODO: STATUS and settings explained
The statuses
======================
2012-10-05 16:00:07 +02:00
Available configuration statuses
----------------------------------
2012-11-20 17:14:58 +01:00
The configuration's status lives in an `setting.Setting` object.
2012-11-19 16:48:47 +01:00
This configuration status corresponds to specific attributes or bunch of
2012-11-20 17:14:58 +01:00
attributes that can be accessed together with some `setting.Setting`
2012-11-19 16:48:47 +01:00
method:
**read write status**
The configuration can be accessed by `__get__` and `__set__`
properties, except for the `hidden` configuration options but, yes, it is
possible to modify a disabled option.
To enable read-write status, call
`congi.Config.read_write()`
2012-10-05 16:00:07 +02:00
**read only status**
2012-10-05 16:00:07 +02:00
The whole configuration is `frozen`, that is modifiying a value is
forbidden. We can access to a configuration option only with the
`__getattr__` property.
2012-10-05 16:00:07 +02:00
The configuration has not an access to the hidden options
2012-10-05 16:00:07 +02:00
but can read the disabled options.
To enable read only status, call `config.Config.read_only()`
.. csv-table:: **Configuration's statuses summary**
:header: " ", "Hidden", "Disabled", "Mandatory"
"read only status", `False`, `True`, `True`
"read-write status", `True`, `False`, `False`
.. _`frozenconfig`:
Freezing a configuration
---------------------------
2012-11-20 17:14:58 +01:00
At the configuration level, `setting.Setting.freeze` freezes
the whole configuration options.
2012-11-20 17:14:58 +01:00
- `test_option_type.test_frozen_value()`
- `test_option_type.test_freeze()`
2012-10-05 16:00:07 +02:00
.. _`frozen`:
2012-10-05 16:00:07 +02:00
It is possible to *freeze* a single `Option` object with
2012-11-20 17:14:58 +01:00
`option.Option.freeze()`. If you try to modify a frozen option, it
raises a `TypeError: trying to change a frozen option object`.
2012-11-20 17:14:58 +01:00
- `test_option_type.test_freeze_one_option()`
2012-10-05 16:00:07 +02:00
Moreover, frozen option can return his default value if
2012-11-20 17:14:58 +01:00
`option.Option.force_default()` has been called on this option,
see `test_option_default.test_force_default_on_freeze()`
Restricted access to an `Option()`
-----------------------------------
2012-10-05 16:00:07 +02:00
Configuration options access statuses are defined at configuration level
2012-11-20 17:14:58 +01:00
that corresponds to the `option.Option()`'s `properties` attribute,
2012-10-05 16:00:07 +02:00
for example
**hidden**
2012-10-05 16:00:07 +02:00
This means that an option raises an error if we try to access
the value of the option.
2012-10-05 16:00:07 +02:00
See `hide()` or `show()` in `Option()` that comes from
2012-11-20 17:14:58 +01:00
`option.HiddenBaseType`
corresponding convenience API provided:
`hide()`:
set the `hidden` attribute to `True`
`show()`:
set the `hidden` attribute to `False`
**disabled**
2012-10-05 16:00:07 +02:00
This means that an option *doesn't exists* (doesn't say anything
much more thant an `AttibuteAccess` error)
2012-11-20 17:14:58 +01:00
See in `option.DisabledBaseType` the origins of
`Option.enable()` or `Option.disable()`
corresponding convenience API provided:
`disable()`:
set the `disabled` attribute to `True`
`enable()`:
set the `disabled` attribute to `False`
Value owners
-------------
2012-10-05 16:00:07 +02:00
Every configuration option has a **owner**. When the option is
instanciated, the owner is `default` because a default value has been
set (including `None`, take a look at the tests).
The `value_owner` is the man who did it. Yes, the man who changed the value of the
2012-10-05 16:00:07 +02:00
configuration option.
- At the instance of the `Config` object, the value owner is `default` because
the default values are set at the instance of the configuration option object,
::
2012-10-05 16:00:07 +02:00
# let's expect there is an option named 'name'
config = Config(descr, bool=False)
# the override method has been called
config._cfgimpl_value_owners['name'] == 'default'
- at the modification of an option, the owner is `default_owner`, (which is `user`)
::
# modification of the value by attribute access
config.gc.dummy = True
assert config.gc._cfgimpl_value_owners['dummy'] == 'user'
assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'user'
- the default owner can be set with the `set_owner()` method
::
config.set_owner('spam')
config.set(dummy=True)
assert config.gc._cfgimpl_value_owners['dummy'] == 'spam'
assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'spam'
Special behaviors for an option
---------------------------------
2012-10-05 16:00:07 +02:00
**mandatory**
A mandatory option shall return a value. If a value, or a default value
has not been set, a error is raised.
**has a callback**
2012-10-05 16:00:07 +02:00
This means that it is a calculated value and therefore automatically
protected it cannot be modified by attribute access.
2012-10-05 16:00:07 +02:00
2012-11-20 17:14:58 +01:00
Its inner state is represented by `option.Option.has_callback()`
and `option.Option.hascallback_and_isfrozen()`
2012-10-05 16:00:07 +02:00
**force default**
if the configuration option has a default value, the default is
returned, otherwise the value is calculated.
2012-11-20 17:14:58 +01:00
Its inner state is represented by `option.Option.force_default()`
2012-10-05 16:00:07 +02:00
Configuration options have default values that are stored in the
`Option()` object itself. Default values, the `default`, can be set in
various ways.
2012-10-05 16:00:07 +02:00
If a default value is modified by overriding it, not only the value of
the option resets to the default that is proposed, but the owner is
modified too, it is reseted to `default`.