ceac4b2d8c809f5e3aa697694610d607f43c4473
[tiramisu.git] / doc / status.txt
1 .. default-role:: literal
2
3 Configuration status
4 ======================
5
6 Available configuration statuses
7 ----------------------------------
8
9 The configuration's status lives in an `setting.Setting` object.
10 This configuration status corresponds to specific attributes or bunch of
11 attributes that can be accessed together with some `setting.Setting`
12 method:
13
14 **read write status**
15
16     The configuration can be accessed by `__get__` and `__set__`
17     properties, except for the `hidden` configuration options but, yes, it is
18     possible to modify a disabled option.
19
20     To enable read-write status, call
21     `setting.Setting.read_write()`
22
23 **read only status**
24
25     The whole configuration is `frozen`, that is modifiying a value is
26     forbidden. We can access to a configuration option only with the
27     `__getattr__` property.
28
29     The configuration has not an access to the hidden options
30     but can read the disabled options.
31
32     To enable read only status, call `setting.Setting.read_only()`
33
34 .. csv-table:: **Configuration's statuses summary**
35    :header: " ", "Hidden", "Disabled", "Mandatory"
36
37     "read only status", `False`, `True`, `True`
38     "read-write status", `True`, `False`, `False`
39
40 .. _`frozenconfig`:
41
42 Freezing a configuration
43 ---------------------------
44
45 At the configuration level, `setting.Setting.freeze` freezes
46 the whole configuration options.
47
48 - `test_option_type.test_frozen_value()`
49 - `test_option_type.test_freeze()`
50
51 .. _`frozen`:
52
53 It is possible to *freeze* a single `Option` object with
54 `option.Option.freeze()`. If you try to modify a frozen option, it
55 raises a `TypeError: trying to change a frozen option object`.
56
57 - `test_option_type.test_freeze_one_option()`
58
59 Moreover, frozen option can return his default value if
60 `option.Option.force_default()` has been called on this option,
61 see `test_option_default.test_force_default_on_freeze()`
62
63
64 Restricted access to an `Option()`
65 -----------------------------------
66
67 Configuration options access statuses are defined at configuration level
68 that corresponds to the `option.Option()`'s `properties` attribute,
69 for example
70
71 **hidden**
72
73     This means that an option raises an error if we try to access
74     the value of the option.
75
76     See `hide()` or `show()` in `Option()` that comes from
77     `option.HiddenBaseType`
78
79 corresponding convenience API provided:
80
81     `hide()`:
82         set the `hidden` attribute to `True`
83
84     `show()`:
85         set the `hidden` attribute to `False`
86
87 **disabled**
88
89     This means that an option *doesn't exists* (doesn't say anything
90     much more thant an `AttibuteAccess` error)
91
92     See in `option.DisabledBaseType` the origins of
93     `Option.enable()` or `Option.disable()`
94
95 corresponding convenience API provided:
96
97     `disable()`:
98         set the `disabled` attribute to `True`
99
100     `enable()`:
101         set the `disabled` attribute to `False`
102
103 Value owners
104 -------------
105
106 Every configuration option has a **owner**. When the option is
107 instanciated, the owner is `default` because a default value has been
108 set (including `None`, take a look at the tests).
109
110 The `value_owner` is the man who did it. Yes, the man who changed the value of the
111 configuration option.
112
113 - At the instance of the `Config` object, the value owner is `default` because
114   the default values are set at the instance of the configuration option object,
115
116 ::
117
118     # let's expect there is an option named 'name'
119     config = Config(descr, bool=False)
120     # the override method has been called
121     config._cfgimpl_value_owners['name'] == 'default'
122
123 - at the modification of an option, the owner is `default_owner`, (which is `user`)
124
125 ::
126
127     # modification of the value by attribute access
128     config.gc.dummy = True
129     assert config.gc._cfgimpl_value_owners['dummy'] == 'user'
130     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'user'
131
132 - the default owner can be set with the `set_owner()` method
133
134 ::
135
136     config.set_owner('spam')
137     config.set(dummy=True)
138     assert config.gc._cfgimpl_value_owners['dummy'] == 'spam'
139     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'spam'
140
141
142 Special behaviors for an option
143 ---------------------------------
144
145 **mandatory**
146
147     A mandatory option shall return a value. If a value, or a default value
148     has not been set, a error is raised.
149
150 **has a callback**
151
152     This means that it is a calculated value and therefore automatically
153     protected it cannot be modified by attribute access.
154
155     Its inner state is represented by `option.Option.has_callback()`
156     and `option.Option.hascallback_and_isfrozen()`
157
158 **force default**
159
160     if the configuration option has a default value, the default is
161     returned, otherwise the value is calculated.
162
163     Its inner state is represented by `option.Option.force_default()`
164
165 Configuration options have default values that are stored in the
166 `Option()` object itself. Default values, the `default`, can be set in
167 various ways.
168
169 If a default value is modified by overriding it, not only the value of
170 the option resets to the default that is proposed, but the owner is
171 modified too, it is reseted to `default`.