documentation update
[tiramisu.git] / doc / status.txt
1 .. default-role:: literal
2
3 Local statuses and global setting
4 =====================================
5
6 Available configuration statuses
7 ----------------------------------
8
9 .. currentmodule:: tiramisu
10
11 The configuration's status lives in an :class:`setting.Setting()` object.
12 This configuration status corresponds to specific attributes or bunch of
13 attributes that can be accessed together with some `setting.Setting`
14 method:
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     :class:`~config.CommonConfig.read_write()` on the config.
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 :class:`~config.SubConfig.read_only()` on 
35     the config.
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 .. todo:: freeze at configuration level
49
50 At the configuration level, `setting.Setting.freeze` freezes
51 the whole configuration options.
52
53 .. _`frozen`:
54
55 It is possible to *freeze* a single :class:`option.Option()` object with
56 :meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen 
57 :option, it raises a `TypeError: trying to change a frozen option object`.
58
59 To find out if an option `myoption` is frozen, just make an assertion on the 
60 settings like that::
61     
62     'frozen' in cfg.cfgimpl_get_settings()[myoption]
63
64 Moreover, frozen option can return their default values if
65 `option.Option.force_default()` is called on this option.
66
67 Restricted access to an `Option()`
68 -----------------------------------
69
70 .. currentmodule:: tiramisu.setting
71
72 .. autoclass:: Property
73
74 The `properties` attribute is in charge of the access rules' option's value.
75
76 Configuration options access statuses are defined at configuration level
77 that corresponds to the `option.Option()`'s `properties` attribute,
78 for example: hidden, disabled. 
79
80 Use the pythonic way to know if a property is there::
81
82     'hidden' in c.cfgimpl_get_settings()
83     'frozen' in c.cfgimpl_get_settings()[opt]
84
85 To access to the global settings::
86
87     cfg.cfgimpl_get_settings()
88     cfg.cfgimpl_get_settings()[option1]
89
90 to add, or suppress a global property::
91
92     cfg.cfgimpl_get_settings()[option1].append('hidden')
93     cfg.cfgimpl_get_settings()[option1].remove('hidden')
94
95 to activate, deactivate properties::
96
97     cfg.cfgimpl_get_settings().append('hidden')
98     cfg.cfgimpl_get_settings().remove('hidden')
99
100 Value owners
101 -------------
102
103
104 Every configuration option has a **owner**. When the option is instanciated, 
105 the owner is :obj:`setting.owners.default` because a default value has been set 
106 (including `None`, wich means that no value has been set yet).
107
108 .. method:: config.CommonConfig.getowner() 
109
110    This method can retrieve an Option's owner. 
111
112 - At the instance of the `Config` object, the value owner is 
113   :obj:`setting.owners.default` because
114   the default values are set at the instance of the configuration option 
115   object,
116
117 - at the modification of an option, the owner is `owners.default`, (which is 
118   :obj:`owners.user`)
119   
120 Special behaviors for an option
121 ---------------------------------
122
123 **mandatory**
124
125     A mandatory option shall return a value. If a value, or a default value
126     has not been set, a error is raised.
127
128 **has a callback**
129
130     This means that it is a calculated value and therefore automatically
131     protected it cannot be modified by attribute access.
132
133 **force_store_value**
134
135     if the configuration option has a default value, the default is
136     returned, otherwise the value is calculated.
137
138     Its inner state is represented by `option.Option.force_default()`
139
140 Configuration options have default values that are stored in the
141 `Option()` object itself. Default values, the `default`, can be set in
142 various ways.
143
144 If a default value is modified by overriding it, not only the value of
145 the option resets to the default that is proposed, but the owner is
146 modified too, it is reseted to `owners.default`.