23de627e1c3ef4a4972e8cb8bbb66acfa8a28995
[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 mode 
96
97     a mode is `normal` or `expert`, just a category of `Option()` or 
98     group wich determines if an option is easy to choose or not, 
99     available methods are:
100
101     `get_mode()`:
102         returns the current mode
103         
104     `set_mode(mode)`:
105         sets a new mode
106
107     see it in :api:`option.ModeBaseType`
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 Special owners
148 ---------------
149
150 If the owner of a configuration option is `auto` or `fill` the behavior of the
151 access of the value changes. In fact, there is nothing in the value. 
152 The value comes from somewhere else (typically, it is calculated by the
153 operation system). 
154
155 **auto**
156
157     This means that it is a calculated value and therefore automatically 
158     protected it cannot be modified by attribute access once the owner 
159     is `auto`.
160     
161     The configuration option is hidden and a fonction in a specific
162     library is called for the computation of the value.
163
164 **fill**
165
166     if the configuration option has a default value, the default is
167     returned, otherwise the value is calculated
168
169 The default values behavior
170 ----------------------------
171
172 Configuration options have default values that are stored in the 
173 `Option()` object itself. Default values, the `default`, can be set in 
174 various ways.
175
176 .. FIXME : ADD DETAILS HERE
177
178 If a default value is modified by overriding it, not only the value of 
179 the option resets to the default that is proposed, but the owner is 
180 modified too, it is reseted to `default`.
181