2090bc4795ba0a3e6686eb83dff8f38e1b4ed7bc
[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 .. _`frozenconfig`:
43
44 Freezing a configuration
45 ---------------------------
46
47 At the configuration level, :api:`config.Config.cfgimpl_freeze()` freezes 
48 the whole configuration options.
49
50 - :api:`test_option_type.test_frozen_value()`
51 - :api:`test_option_type.test_freeze()`
52
53 .. _`frozen`: 
54
55 It is possible to *freeze* a single `Option` object with 
56 :api:`option.Option.freeze()`. If you try to modify a frozen option, it 
57 raises a `TypeError: trying to change a frozen option object`.
58
59 - :api:`test_option_type.test_freeze_one_option()`
60
61 Moreover, frozen option can return his default value if 
62 :api:`option.Option.force_default()` has been called on this option, 
63 see :api:`test_option_default.test_force_default_on_freeze()`
64
65
66 Restricted access to an `Option()`
67 -----------------------------------
68
69 Configuration options access statuses are defined at configuration level 
70 that corresponds to the :api:`option.Option()`'s `properties` attribute.
71
72 **hidden**
73
74     This means that an option raises an `HiddenOptionError` if we try to access 
75     the value of the option. 
76
77     See `hide()` or `show()` in `Option()` that comes from 
78     :api:`option.HiddenBaseType`
79
80 corresponding convenience API provided:
81
82     `hide()`:
83         set the `hidden` attribute to `True`
84
85     `show()`:
86         set the `hidden` attribute to `False`
87
88 **disabled**
89
90     This means that an option *doesn't exists* (doesn't say anything 
91     much more thant an `AttibuteAccess` error)
92
93     See in :api:`option.DisabledBaseType` the origins of 
94     `Option.enable()` or `Option.disable()`
95
96 corresponding convenience API provided:
97
98     `disable()`:
99         set the `disabled` attribute to `True`
100
101     `enable()`:
102         set the `disabled` attribute to `False`
103
104 Value owners
105 -------------
106
107 Every configuration option has a **owner**. When the option is 
108 instanciated, the owner is `default` because a default value has been 
109 set (including `None`, take a look at the tests).
110
111 The `value_owner` is the man who did it. Yes, the man who changed the value of the
112 configuration option. 
113
114 - At the instance of the `Config` object, the value owner is `default` because
115   the default values are set at the instance of the configuration option object,
116
117 ::
118     
119     # let's expect there is an option named 'name'
120     config = Config(descr, bool=False)
121     # the override method has been called
122     config._cfgimpl_value_owners['name'] == 'default'
123
124 - at the modification of an option, the owner is `default_owner`, (which is `user`)
125
126 ::
127
128     # modification of the value by attribute access
129     config.gc.dummy = True
130     assert config.gc._cfgimpl_value_owners['dummy'] == 'user'
131     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'user'
132
133 - the default owner can be set with the `set_owner()` method
134
135 ::
136
137     config.set_owner('spam')
138     config.set(dummy=True)
139     assert config.gc._cfgimpl_value_owners['dummy'] == 'spam'
140     assert config._cfgimpl_values['gc']._cfgimpl_value_owners['dummy'] == 'spam'
141
142
143 Special behaviors for an option
144 ---------------------------------
145
146 **auto**
147
148     This means that it is a calculated value and therefore automatically 
149     protected it cannot be modified by attribute access.
150         
151     Its inner state is represented by :api:`option.Option.has_callback()`
152     and :api:`option.Option.hascallback_and_isfrozen()`
153
154 **fill**
155
156     if the configuration option has a default value, the default is
157     returned, otherwise the value is calculated.
158
159     Its inner state is represented by :api:`option.Option.has_callback()`
160
161 `default` value owner
162 ----------------------
163
164 Configuration options have default values that are stored in the 
165 `Option()` object itself. Default values, the `default`, can be set in 
166 various ways.
167
168 If a default value is modified by overriding it, not only the value of 
169 the option resets to the default that is proposed, but the owner is 
170 modified too, it is reseted to `default`.
171