|
1 :mod:`VirtualMailManager.Config` --- Simplified configuration access |
|
2 ====================================================================== |
|
3 |
|
4 .. module:: VirtualMailManager.Config |
|
5 :synopsis: Simplified configuration access |
|
6 |
|
7 .. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net> |
|
8 |
|
9 .. toctree:: |
|
10 :maxdepth: 2 |
|
11 |
|
12 |
|
13 This module provides a few classes for simplified configuration handling |
|
14 and the validation of the setting's *type* and *value*. |
|
15 |
|
16 :class:`LazyConfig` is derived from Python's |
|
17 :class:`ConfigParser.RawConfigParser`. It doesn't use ``RawConfigParser``'s |
|
18 ``DEFAULT`` section. All settings and their defaults, if supposed, are |
|
19 handled by :class:`LazyConfigOption` objects in the :attr:`LazyConfig._cfg` |
|
20 *dict*. |
|
21 |
|
22 ``LazyConfig``'s setters and getters for options are taking a single string |
|
23 for the *section* and *option* argument, e.g. ``config.pget('database.user')`` |
|
24 instead of ``config.get('database', 'user')``. |
|
25 |
|
26 |
|
27 |
|
28 LazyConfig |
|
29 ---------- |
|
30 .. class:: LazyConfig |
|
31 |
|
32 Bases: :class:`ConfigParser.RawConfigParser` |
|
33 |
|
34 .. versionadded:: 0.6.0 |
|
35 |
|
36 .. attribute:: _cfg |
|
37 |
|
38 a multi dimensional :class:`dict`, containing *sections* and *options*, |
|
39 represented by :class:`LazyConfigOption` objects. |
|
40 |
|
41 For example:: |
|
42 |
|
43 from VirtualMailManager.Config import LazyConfig, LazyConfigOption |
|
44 |
|
45 class FooConfig(LazyConfig): |
|
46 def __init__(self, ...): |
|
47 LazyConfig.__init__(self) |
|
48 ... |
|
49 LCO = LazyConfigOption |
|
50 self._cfg = { |
|
51 'database': {# section database: |
|
52 'host': LCO(str, '::1', self.get),# options of the |
|
53 'name': LCO(str, 'dbx', self.get),# database section. |
|
54 'pass': LCO(str, None, self.get),# No defaults for the |
|
55 'user': LCO(str, None, self.get),# user and pass options |
|
56 } |
|
57 } |
|
58 |
|
59 ... |
|
60 |
|
61 |
|
62 .. method:: bool_new(value) |
|
63 |
|
64 Converts the string *value* into a `bool` and returns it. |
|
65 |
|
66 | ``'1'``, ``'on'``, ``'yes'`` and ``'true'`` will become :const:`True` |
|
67 | ``'0'``, ``'off'``, ``'no'`` and ``'false'`` will become :const:`False` |
|
68 |
|
69 :param value: one of the above mentioned strings |
|
70 :type value: :obj:`basestring` |
|
71 :rtype: bool |
|
72 :raise ConfigValueError: for all other values, except ``bool``\ s |
|
73 |
|
74 .. method:: dget(option) |
|
75 |
|
76 Like :meth:`pget`, but returns the *option*'s default value, from |
|
77 :attr:`_cfg` (defined by :attr:`LazyConfigOption.default`) if the *option* |
|
78 is not configured in a ini-like configuration file. |
|
79 |
|
80 :param option: the section.option combination |
|
81 :type option: :obj:`basestring` |
|
82 :raise NoDefaultError: if the *option* couldn't be found in the |
|
83 configuration file and no default value was passed to |
|
84 :class:`LazyConfigOption`'s constructor for the requested *option*. |
|
85 |
|
86 .. method:: getboolean(section, option) |
|
87 |
|
88 Returns the boolean value of the *option*, in the given *section*. |
|
89 |
|
90 For a boolean :const:`True`, the value must be set to ``'1'``, ``'on'``, |
|
91 ``'yes'``, ``'true'`` or :const:`True`. For a boolean :const:`False`, the |
|
92 value must set to ``'0'``, ``'off'``, ``'no'``, ``'false'`` or |
|
93 :const:`False`. |
|
94 |
|
95 :param section: The section's name |
|
96 :type section: :obj:`basestring` |
|
97 :param option: The option's name |
|
98 :type option: :obj:`basestring` |
|
99 :rtype: bool |
|
100 :raise ValueError: if the option has an other value than the values |
|
101 mentioned above. |
|
102 |
|
103 .. method:: has_option(option) |
|
104 |
|
105 Checks if the *option* (section\ **.**\ option) is a known configuration |
|
106 option. |
|
107 |
|
108 :param option: The option's name |
|
109 :type option: :obj:`basestring` |
|
110 :rtype: bool |
|
111 |
|
112 .. method:: has_section(section) |
|
113 |
|
114 Checks if *section* is a known configuration section. |
|
115 |
|
116 :param section: The section's name |
|
117 :type section: :obj:`basestring` |
|
118 :rtype: bool |
|
119 |
|
120 .. method:: items(section) |
|
121 |
|
122 Returns an iterator for ``key, value`` :obj:`tuple`\ s for each option in |
|
123 the given *section*. |
|
124 |
|
125 :param section: The section's name |
|
126 :type section: :obj:`basestring` |
|
127 :raise NoSectionError: if the given *section* is not known. |
|
128 |
|
129 .. method:: pget(option) |
|
130 |
|
131 Polymorphic getter which returns the *option*'s value (by calling |
|
132 :attr:`LazyConfigOption.getter`) with the appropriate type, defined by |
|
133 :attr:`LazyConfigOption.cls`. |
|
134 |
|
135 :param option: the section.option combination |
|
136 :type option: :obj:`basestring` |
|
137 |
|
138 .. method:: sections() |
|
139 |
|
140 Returns an iterator object for all configuration sections from the |
|
141 :attr:`_cfg` dictionary. |
|
142 |
|
143 :rtype: :obj:`dictionary-keyiterator` |
|
144 |
|
145 .. method:: set(option, value) |
|
146 |
|
147 Like :meth:`ConfigParser.RawConfigParser.set`, but converts the *option*'s |
|
148 new *value* (by calling :attr:`LazyConfigOption.cls`) to the appropriate |
|
149 type/class. When the ``LazyConfigOption``'s optional parameter *validate* |
|
150 was not :const:`None`, the new *value* will be also validated. |
|
151 |
|
152 :param option: the section.option combination |
|
153 :type option: :obj:`basestring` |
|
154 :param value: the new value to be set |
|
155 :type value: :obj:`basestring` |
|
156 :rtype: :const:`None` |
|
157 :raise ConfigValueError: if a boolean value shout be set (:meth:`bool_new`) |
|
158 and it fails |
|
159 :raise ValueError: if an other setter (:attr:`LazyConfigOption.cls`) or |
|
160 validator (:attr:`LazyConfigOption.validate`) fails. |
|
161 :raise VirtualMailManager.Exceptions.VMMException: if |
|
162 :attr:`LazyConfigOption.validate` is set to |
|
163 :func:`VirtualMailManager.exec_ok` or :func:`VirtualMailManager.is_dir`. |
|
164 |
|
165 |
|
166 LazyConfigOption |
|
167 ---------------- |
|
168 LazyConfigOption instances are required by :class:`LazyConfig` instances, and |
|
169 instances of classes derived from `LazyConfig`, like the :class:`Config` |
|
170 class. |
|
171 |
|
172 .. class:: LazyConfigOption (cls, default, getter[, validate=None]) |
|
173 |
|
174 .. versionadded:: 0.6.0 |
|
175 |
|
176 The constructor's parameters are: |
|
177 |
|
178 ``cls`` : :obj:`type` |
|
179 The class/type of the option's value. |
|
180 ``default`` : :obj:`str` or the one defined by ``cls`` |
|
181 Default value of the option. Use :const:`None` if the option shouldn't |
|
182 have a default value. |
|
183 ``getter``: :obj:`callable` |
|
184 A method's name of :class:`ConfigParser.RawConfigParser` and derived |
|
185 classes, to get a option's value, e.g. `self.getint`. |
|
186 ``validate`` : :obj:`callable` or :const:`None` |
|
187 :const:`None` or any function, which takes one argument and returns the |
|
188 validated argument with the appropriate type (for example: |
|
189 :meth:`LazyConfig.bool_new`). The function should raise a |
|
190 :exc:`ConfigValueError` if the validation fails. This function checks the |
|
191 new value when :meth:`LazyConfig.set()` is called. |
|
192 |
|
193 Each LazyConfigOption object has the following read-only attributes: |
|
194 |
|
195 .. attribute:: cls |
|
196 |
|
197 The class of the option's value e.g. `str`, `unicode` or `bool`. Used as |
|
198 setter method when :meth:`LazyConfig.set` (or the ``set()`` method of a |
|
199 derived class) is called. |
|
200 |
|
201 .. attribute:: default |
|
202 |
|
203 The option's default value, may be ``None`` |
|
204 |
|
205 .. attribute:: getter |
|
206 |
|
207 A method's name of :class:`ConfigParser.RawConfigParser` and derived |
|
208 classes, to get a option's value, e.g. ``self.getint``. |
|
209 |
|
210 .. attribute:: validate |
|
211 |
|
212 A method or function to validate the option's new value. |
|
213 |
|
214 |
|
215 Config |
|
216 ------ |
|
217 The final configuration class of the virtual mail manager. |
|
218 |
|
219 .. class:: Config (filename) |
|
220 |
|
221 Bases: :class:`LazyConfig` |
|
222 |
|
223 :param filename: absolute path to the configuration file. |
|
224 :type filename: :obj:`basestring` |
|
225 |
|
226 .. attribute:: _cfg |
|
227 |
|
228 The configuration ``dict``, containing all configuration sections and |
|
229 options, as described in :attr:`LazyConfig._cfg`. |
|
230 |
|
231 .. method:: check() |
|
232 |
|
233 Checks all section's options for settings w/o a default value. |
|
234 |
|
235 :raise VirtualMailManager.Exceptions.VMMConfigException: if the check fails |
|
236 |
|
237 .. method:: load() |
|
238 |
|
239 Loads the configuration read-only. |
|
240 |
|
241 :raise VirtualMailManager.Exceptions.VMMConfigException: if the |
|
242 configuration syntax is invalid |
|
243 |
|
244 .. method:: unicode(section, option) |
|
245 |
|
246 Returns the value of the *option* from *section*, converted to Unicode. |
|
247 This method is intended for the :attr:`LazyConfigOption.getter`. |
|
248 |
|
249 :param section: The name of the configuration section |
|
250 :type section: :obj:`basestring` |
|
251 :param option: The name of the configuration option |
|
252 :type option: :obj:`basestring` |
|
253 :rtype: :obj:`unicode` |
|
254 |
|
255 |
|
256 Exceptions |
|
257 ---------- |
|
258 |
|
259 .. exception:: BadOptionError (msg) |
|
260 |
|
261 Bases: :exc:`ConfigParser.Error` |
|
262 |
|
263 Raised when a option isn't in the format 'section.option'. |
|
264 |
|
265 .. exception:: ConfigValueError (msg) |
|
266 |
|
267 Bases: :exc:`ConfigParser.Error` |
|
268 |
|
269 Raised when creating or validating of new values fails. |
|
270 |
|
271 .. exception:: NoDefaultError (section, option) |
|
272 |
|
273 Bases: :exc:`ConfigParser.Error` |
|
274 |
|
275 Raised when the requested option has no default value. |