pep8
[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 .. _`frozen`:
44
45 Freezing a configuration
46 ---------------------------
47
48 At the configuration level, :class:`~setting.Setting()` enables us to freeze the 
49 whole configuration, wich means that the frozen :class:`~option.Option()`'s 
50 values cannot be modified.
51
52 It is possible to *freeze* a single :class:`~option.Option()` object with
53 :meth:`~config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen 
54 option, it raises a `TypeError: trying to change a frozen option object`.
55
56 To find out if an option `myoption` is frozen, just make an assertion on the 
57 settings like that::
58     
59     'frozen' in cfg.cfgimpl_get_settings()[myoption]
60
61 Moreover, frozen option can return their default values if
62 :meth:`~option.Option.force_default()` is called on this option.
63
64 .. glossary::
65
66     force default on freeze
67
68         A single option is frozen and we want the option to return something
69         else than his value, typically it is his default value.
70
71         In the option's values, an attribute can be set 
72         :attr:`force_default_on_freeze`, that forces this behavior.
73
74 Restricted access to an `Option()`
75 -----------------------------------
76
77 .. autoclass:: tiramisu.setting.Property
78
79 The `properties` attribute is in charge of the access rules' option's value.
80
81 Configuration options access statuses are defined at configuration level
82 that corresponds to the `option.Option()`'s `properties` attribute,
83 for example: hidden, disabled. 
84
85 Use the pythonic way to know if a property is there::
86
87     'hidden' in c.cfgimpl_get_settings()
88     'frozen' in c.cfgimpl_get_settings()[opt]
89
90 To access to the global settings::
91
92     cfg.cfgimpl_get_settings()
93     cfg.cfgimpl_get_settings()[option1]
94
95 to add, or suppress a global property::
96
97     cfg.cfgimpl_get_settings()[option1].append('hidden')
98     cfg.cfgimpl_get_settings()[option1].remove('hidden')
99
100 to activate, deactivate properties::
101
102     cfg.cfgimpl_get_settings().append('hidden')
103     cfg.cfgimpl_get_settings().remove('hidden')
104
105 The global properties are living in e :class:`~setting.Setting` object. A 
106 `Setting` object also takes care of the way to access option values and the 
107 storage in the cache.
108
109 Value owners
110 -------------
111
112 Every configuration option has a **owner**. When the option is instanciated, 
113 the owner is :obj:`setting.owners.default` because a default value has been set 
114 (including `None`, wich means that no value has been set yet).
115
116 .. method:: config.CommonConfig.getowner() 
117
118    This method can retrieve an Option's owner. 
119
120 - At the instance of the `Config` object, the value owner is 
121   :obj:`setting.owners.default` because
122   the default values are set at the instance of the configuration option 
123   object,
124
125 - at the modification of an option, the owner is `owners.default`, (which is 
126   :obj:`owners.user`)
127   
128 Special behaviors for an option
129 ---------------------------------
130
131 **mandatory**
132
133     A mandatory option shall return a value. If a value, or a default value
134     has not been set, a error is raised.
135
136 **has a callback**
137
138     This means that it is a calculated value and therefore automatically
139     protected it cannot be modified by attribute access.
140
141 **force_store_value**
142
143     if the configuration option has a default value, the default is
144     returned, otherwise the value is calculated.
145
146     Its inner state is represented by `option.Option.force_default()`
147
148 Configuration options have default values that are stored in the
149 `Option()` object itself. Default values, the `default`, can be set in
150 various ways.
151
152 If a default value is modified by overriding it, not only the value of
153 the option resets to the default that is proposed, but the owner is
154 modified too, it is reseted to `owners.default`.
155