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