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