1 .. default-role:: literal
3 Local statuses and global setting
4 =====================================
6 Available configuration statuses
7 ----------------------------------
9 .. currentmodule:: tiramisu
11 The configuration's status lives in an :class:`setting.Setting()` object.
12 This configuration status corresponds to specific attributes or bunch of
13 attributes that can be accessed together with some `setting.Setting`
18 The configuration can be accessed by `__get__` and `__set__`
19 properties, except for the `hidden` configuration options but, yes, it is
20 possible to modify a disabled option.
22 To enable read-write status, call
23 :class:`config.CommonConfig.read_write()`
27 The whole configuration is `frozen`, that is modifiying a value is
28 forbidden. We can access to a configuration option only with the
29 `__getattr__` property.
31 The configuration has not an access to the hidden options
32 but can read the disabled options.
34 To enable read only status, call :class:`config.SubConfig.read_only()`
36 .. csv-table:: **Configuration's statuses summary**
37 :header: " ", "Hidden", "Disabled", "Mandatory"
39 "read only status", `False`, `True`, `True`
40 "read-write status", `True`, `False`, `False`
44 Freezing a configuration
45 ---------------------------
47 .. todo:: freeze at configuration level
49 At the configuration level, `setting.Setting.freeze` freezes
50 the whole configuration options.
54 It is possible to *freeze* a single :class:`option.Option()` object with
55 :meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen
56 :option, it raises a `TypeError: trying to change a frozen option object`.
58 To find out if an option `myoption` is frozen, just make an assertion on the
61 'frozen' in cfg.cfgimpl_get_settings()[myoption]
63 Moreover, frozen option can return their default values if
64 `option.Option.force_default()` is called on this option.
66 Restricted access to an `Option()`
67 -----------------------------------
69 .. currentmodule:: tiramisu.setting
71 .. autoclass:: Property
73 The `properties` attribute is in charge of the access rules' option's value.
75 Configuration options access statuses are defined at configuration level
76 that corresponds to the `option.Option()`'s `properties` attribute,
77 for example: hidden, disabled.
79 Use the pythonic way to know if a property is there::
81 'hidden' in c.cfgimpl_get_settings()
82 'frozen' in c.cfgimpl_get_settings()[opt]
84 To access to the global settings::
86 cfg.cfgimpl_get_settings()
87 cfg.cfgimpl_get_settings()[option1]
89 to add, or suppress a global property::
91 cfg.cfgimpl_get_settings()[option1].append('hidden')
92 cfg.cfgimpl_get_settings()[option1].remove('hidden')
94 to activate, deactivate properties::
96 cfg.cfgimpl_get_settings().append('hidden')
97 cfg.cfgimpl_get_settings().remove('hidden')
103 Every configuration option has a **owner**. When the option is instanciated,
104 the owner is :obj:`setting.owners.default` because a default value has been set
105 (including `None`, wich means that no value has been set yet).
107 .. method:: config.CommonConfig.getowner()
109 This method can retrieve an Option's owner.
111 - At the instance of the `Config` object, the value owner is
112 :obj:`setting.owners.default` because
113 the default values are set at the instance of the configuration option
116 - at the modification of an option, the owner is `owners.default`, (which is
119 Special behaviors for an option
120 ---------------------------------
124 A mandatory option shall return a value. If a value, or a default value
125 has not been set, a error is raised.
129 This means that it is a calculated value and therefore automatically
130 protected it cannot be modified by attribute access.
132 **force_store_value**
134 if the configuration option has a default value, the default is
135 returned, otherwise the value is calculated.
137 Its inner state is represented by `option.Option.force_default()`
139 Configuration options have default values that are stored in the
140 `Option()` object itself. Default values, the `default`, can be set in
143 If a default value is modified by overriding it, not only the value of
144 the option resets to the default that is proposed, but the owner is
145 modified too, it is reseted to `owners.default`.