172 lines
5.0 KiB
Plaintext
172 lines
5.0 KiB
Plaintext
.. default-role:: literal
|
|
|
|
Configuration status
|
|
======================
|
|
|
|
Available configuration statuses
|
|
----------------------------------
|
|
|
|
The configuration's status lives in an `setting.Setting` object.
|
|
This configuration status corresponds to specific attributes or bunch of
|
|
attributes that can be accessed together with some `setting.Setting`
|
|
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
|
|
`setting.Setting.read_write()`
|
|
|
|
**read only status**
|
|
|
|
The whole configuration is `frozen`, that is modifiying a value is
|
|
forbidden. We can access to a configuration option only with the
|
|
`__getattr__` property.
|
|
|
|
The configuration has not an access to the hidden options
|
|
but can read the disabled options.
|
|
|
|
To enable read only status, call `setting.Setting.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
|
|
---------------------------
|
|
|
|
At the configuration level, `setting.Setting.freeze` freezes
|
|
the whole configuration options.
|
|
|
|
- `test_option_type.test_frozen_value()`
|
|
- `test_option_type.test_freeze()`
|
|
|
|
.. _`frozen`:
|
|
|
|
It is possible to *freeze* a single `Option` object with
|
|
`option.Option.freeze()`. If you try to modify a frozen option, it
|
|
raises a `TypeError: trying to change a frozen option object`.
|
|
|
|
- `test_option_type.test_freeze_one_option()`
|
|
|
|
Moreover, frozen option can return his default value if
|
|
`option.Option.force_default()` has been called on this option,
|
|
see `test_option_default.test_force_default_on_freeze()`
|
|
|
|
|
|
Restricted access to an `Option()`
|
|
-----------------------------------
|
|
|
|
Configuration options access statuses are defined at configuration level
|
|
that corresponds to the `option.Option()`'s `properties` attribute,
|
|
for example
|
|
|
|
**hidden**
|
|
|
|
This means that an option raises an error if we try to access
|
|
the value of the option.
|
|
|
|
See `hide()` or `show()` in `Option()` that comes from
|
|
`option.HiddenBaseType`
|
|
|
|
corresponding convenience API provided:
|
|
|
|
`hide()`:
|
|
set the `hidden` attribute to `True`
|
|
|
|
`show()`:
|
|
set the `hidden` attribute to `False`
|
|
|
|
**disabled**
|
|
|
|
This means that an option *doesn't exists* (doesn't say anything
|
|
much more thant an `AttibuteAccess` error)
|
|
|
|
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
|
|
-------------
|
|
|
|
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
|
|
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,
|
|
|
|
::
|
|
|
|
# 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
|
|
---------------------------------
|
|
|
|
**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**
|
|
|
|
This means that it is a calculated value and therefore automatically
|
|
protected it cannot be modified by attribute access.
|
|
|
|
Its inner state is represented by `option.Option.has_callback()`
|
|
and `option.Option.hascallback_and_isfrozen()`
|
|
|
|
**force default**
|
|
|
|
if the configuration option has a default value, the default is
|
|
returned, otherwise the value is calculated.
|
|
|
|
Its inner state is represented by `option.Option.force_default()`
|
|
|
|
Configuration options have default values that are stored in the
|
|
`Option()` object itself. Default values, the `default`, can be set in
|
|
various ways.
|
|
|
|
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`.
|