1 .. default-role:: literal
6 :module: :api:`config.py`
7 :tests: - :api:`test_option_owner.py`
8 - :api:`test_option_type.py`
9 - :api:`test_option_default.py`
11 Available configuration statuses
12 ----------------------------------
14 These configuration statuses corresponds to specific global attributes :
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.
22 To enable read-write status, call
23 :api:`config.Config.cfgimpl_read_write()`
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.
31 The configuration has not an access to the hidden options
32 but can read the disabled options.
34 To enable read only status, call :api:`config.Config.cfgimpl_read_only()`
36 .. csv-table:: **Configuration's statuses summary**
37 :header: " ", "Hidden", "Disabled", "Mandatory"
39 "read only status", `False`, `True`, `True`
40 "read-write status", `True`, `False`, `False`
42 Freezing a configuration
43 ---------------------------
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`.
49 At the configuration level, :api:`config.Config.cfgimpl_freeze()` freeze
50 the whole configuration options.
52 - :api:`test_option_type.test_freeze_one_option()`
53 - :api:`test_option_type.test_frozen_value()`
54 - :api:`test_option_type.test_freeze()`
57 Restricted access to an `Option()`
58 -----------------------------------
60 Configuration options access statuses are defined at configuration level
61 that corresponds to theses :api:`option.Option()`'s attribute:
65 This means that an option raises an `HiddenOptionError` if we try to access
66 the value of the option.
68 See `hide()` or `show()` in `Option()` that comes from
69 :api:`option.HiddenBaseType`
71 corresponding convenience API provided:
74 set the `hidden` attribute to `True`
77 set the `hidden` attribute to `False`
81 This means that an option *doesn't exists* (doesn't say anything
82 much more thant an `AttibuteAccess` error)
84 See in :api:`option.DisabledBaseType` the origins of
85 `Option.enable()` or `Option.disable()`
87 corresponding convenience API provided:
90 set the `disabled` attribute to `True`
93 set the `disabled` attribute to `False`
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:
102 returns the current mode
107 see it in :api:`option.ModeBaseType`
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).
116 The `value_owner` is the man who did it. Yes, the man who changed the value of the
117 configuration option.
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,
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'
129 - at the modification of an option, the owner is `default_owner`, (which is `user`)
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'
138 - the default owner can be set with the `set_owner()` method
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'
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
157 This means that it is a calculated value and therefore automatically
158 protected it cannot be modified by attribute access once the owner
161 The configuration option is hidden and a fonction in a specific
162 library is called for the computation of the value.
166 if the configuration option has a default value, the default is
167 returned, otherwise the value is calculated
169 The default values behavior
170 ----------------------------
172 Configuration options have default values that are stored in the
173 `Option()` object itself. Default values, the `default`, can be set in
176 .. FIXME : ADD DETAILS HERE
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`.