doc : None is a possible value for the options
[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 Available configuration statuses 
12 ----------------------------------
13
14 These configuration statuses corresponds to specific global attributes : 
15
16 **read write status**
17
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.
21
22     To enable read-write status, call
23     :api:`config.Config.cfgimpl_read_write()`
24     
25 **read only status**
26
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.
30     
31     The configuration has not an access to the hidden options
32     but can read the disabled options.  
33
34     To enable read only status, call :api:`config.Config.cfgimpl_read_only()`
35
36 .. csv-table:: **Configuration's statuses summary**
37    :header: " ", "Hidden", "Disabled", "Mandatory"
38
39     "read only status", `False`, `True`, `True`
40     "read-write status", `True`, `False`, `False`
41
42 Freezing a configuration
43 ---------------------------
44
45 It is possible to *freeze* a single `Option` object with 
46 :api:`option.Option.freeze()`. If you try to modify a frozen option, it 
47 raises a `TypeError: trying to change a frozen option object`.
48
49 At the configuration level, :api:`config.Config.cfgimpl_freeze()` freeze 
50 the whole configuration options.
51
52 - :api:`test_option_type.test_freeze_one_option()`
53 - :api:`test_option_type.test_frozen_value()`
54 - :api:`test_option_type.test_freeze()`
55
56
57 Restricted access to an `Option()`
58 -----------------------------------
59
60 Configuration options access statuses are defined at configuration level 
61 that corresponds to theses :api:`option.Option()`'s attribute: 
62
63 **hidden**
64
65     This means that an option raises an `HiddenOptionError` if we try to access 
66     the value of the option. 
67
68     See `hide()` or `show()` in `Option()` that comes from 
69     :api:`option.HiddenBaseType`
70
71 corresponding convenience API provided:
72
73     `hide()`:
74         set the `hidden` attribute to `True`
75
76     `show()`:
77         set the `hidden` attribute to `False`
78
79 **disabled**
80
81     This means that an option *doesn't exists* (doesn't say anything 
82     much more thant an `AttibuteAccess` error)
83
84     See in :api:`option.DisabledBaseType` the origins of 
85     `Option.enable()` or `Option.disable()`
86
87 corresponding convenience API provided:
88
89     `disable()`:
90         set the `disabled` attribute to `True`
91
92     `enable()`:
93         set the `disabled` attribute to `False`
94
95 .. 
96     mode 
97
98         a mode is `normal` or `expert`, just a category of `Option()` or 
99         group wich determines if an option is easy to choose or not, 
100         available methods are:
101
102         `get_mode()`:
103             returns the current mode
104             
105         `set_mode(mode)`:
106             sets a new mode
107
108         see it in :api:`option.ModeBaseType`
109
110 Value owners
111 -------------
112
113 Every configuration option has a **owner**. When the option is 
114 instanciated, the owner is `default` because a default value has been 
115 set (including `None`, take a look at the tests).
116
117 The `value_owner` is the man who did it. Yes, the man who changed the value of the
118 configuration option. 
119
120 - At the instance of the `Config` object, the value owner is `default` because
121   the default values are set at the instance of the configuration option object,
122
123 ::
124     
125     # let's expect there is an option named 'name'
126     config = Config(descr, bool=False)
127     # the override method has been called
128     config._cfgimpl_value_owners['name'] == 'default'
129
130 - at the modification of an option, the owner is `default_owner`, (which is `user`)
131
132 ::
133
134     # modification of the value by attribute access
135     config.gc.dummy = True
136     assert config.gc._cfgimpl_value_owners['dummy'] == 'user'
137     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'user'
138
139 - the default owner can be set with the `set_owner()` method
140
141 ::
142
143     config.set_owner('spam')
144     config.set(dummy=True)
145     assert config.gc._cfgimpl_value_owners['dummy'] == 'spam'
146     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'spam'
147
148 Special owners
149 ---------------
150
151 If the owner of a configuration option is `auto` or `fill` the behavior of the
152 access of the value changes. In fact, there is nothing in the value. 
153 The value comes from somewhere else (typically, it is calculated by the
154 operation system). 
155
156 **auto**
157
158     This means that it is a calculated value and therefore automatically 
159     protected it cannot be modified by attribute access once the owner 
160     is `auto`.
161     
162     The configuration option is hidden and a fonction in a specific
163     library is called for the computation of the value.
164
165 **fill**
166
167     if the configuration option has a default value, the default is
168     returned, otherwise the value is calculated
169
170 The default values behavior
171 ----------------------------
172
173 Configuration options have default values that are stored in the 
174 `Option()` object itself. Default values, the `default`, can be set in 
175 various ways.
176
177 .. FIXME : ADD DETAILS HERE
178
179 If a default value is modified by overriding it, not only the value of 
180 the option resets to the default that is proposed, but the owner is 
181 modified too, it is reseted to `default`.
182