the value owner is a string now
[tiramisu.git] / tiramisu / option.py
1 # -*- coding: utf-8 -*-
2 "option types and option description for the configuration management"
3 # Copyright (C) 2012 Team tiramisu (see AUTHORS for all contributors)
4 #
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2 of the License, or
8 # (at your option) any later version.
9 #
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 # GNU General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with this program; if not, write to the Free Software
17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18 #
19 # The original `Config` design model is unproudly borrowed from
20 # the rough pypy's guys: http://codespeak.net/svn/pypy/dist/pypy/config/
21 # the whole pypy projet is under MIT licence
22 # ____________________________________________________________
23 from tiramisu.basetype import HiddenBaseType, DisabledBaseType
24 from tiramisu.error import (ConfigError, ConflictConfigError, NotFoundError,
25     RequiresError, RequirementRecursionError, MandatoryError,
26     PropertiesOptionError)
27 from tiramisu.autolib import carry_out_calculation
28
29 requires_actions = [('hide', 'show'), ('enable', 'disable'), ('freeze', 'unfreeze')]
30
31 available_actions = []
32 reverse_actions = {}
33 for act1, act2 in requires_actions:
34     available_actions.extend([act1, act2])
35     reverse_actions[act1] = act2
36     reverse_actions[act2] = act1
37 # ____________________________________________________________
38 # OptionDescription authorized group_type values
39 """
40 Three available group_types : `default`, `family`, `group` and
41 `master` (for master~slave group type). Notice that for a
42 master~slave group, the name of the group and the name of the
43 master option are identical.
44 """
45 group_types = ['default', 'family', 'group', 'master']
46
47 # ____________________________________________________________
48 # multi types
49
50 class Multi(list):
51     "container that support items for the values of list (multi) options"
52     def __init__(self, lst, config, child):
53         self.config = config
54         self.child = child
55         super(Multi, self).__init__(lst)
56
57     def __setitem__(self, key, value):
58         return self.setoption(value, key)
59
60     def append(self, value):
61         self.setoption(value)
62
63     def setoption(self, value, key=None, who=None):
64         if who is None:
65             who = self.config._cfgimpl_owner
66         if value != None:
67             if not self.child._validate(value):
68                 raise ConfigError("invalid value {0} "
69                     "for option {1}".format(str(value), self.child._name))
70         oldvalue = list(self)
71         if key is None:
72             ret = super(Multi, self).append(value)
73         else:
74             ret = super(Multi, self).__setitem__(key, value)
75         self.child.setowner(self.config, who)
76         self.config._cfgimpl_previous_values[self.child._name] = oldvalue
77         return ret
78
79     def pop(self, key):
80         self.child.setowner(self.config, self.config._cfgimpl_owner)
81         super(Multi, self).pop(key)
82 # ____________________________________________________________
83 #
84 class Option(HiddenBaseType, DisabledBaseType):
85     """
86     Abstract base class for configuration option's
87     reminder: an Option object is **not** a container for the value
88     """
89     "freeze means: cannot modify the value of an Option once set"
90     _frozen = False
91     "if an Option has been frozen, shall return the default value"
92     _force_default_on_freeze = False
93     def __init__(self, name, doc, default=None, default_multi=None,
94                  requires=None, mandatory=False, multi=False, callback=None,
95                  callback_params=None):
96         """
97         :param default: ['bla', 'bla', 'bla']
98         :param default_multi: 'bla' (used in case of a reset to default only at
99             a given index)
100         """
101         self._name = name
102         self.doc = doc
103         self._requires = requires
104         self._mandatory = mandatory
105         self.multi = multi
106         if not self.multi and default_multi is not None:
107             raise ConfigError("a default_multi is set whereas multi is False"
108                   " in option: {0}".format(name))
109         if default_multi is not None and not self._validate(default_multi):
110             raise ConfigError("invalid default_multi value {0} "
111                 "for option {1}".format(str(default_multi), name))
112         self.default_multi = default_multi
113         #if self.multi and default_multi is None:
114         #    _cfgimpl_warnings[name] = DefaultMultiWarning
115         if callback is not None and (default is not None or default_multi is not None):
116             raise ConfigError("defaut values not allowed if option: {0} "
117                 "is calculated".format(name))
118         self.callback = callback
119         if self.callback is None and callback_params is not None:
120             raise ConfigError("params defined for a callback function but"
121             " no callback defined yet for option {0}".format(name))
122         self.callback_params = callback_params
123         if self.multi == True:
124             if default == None:
125                 default = []
126             if not isinstance(default, list) or not self.validate(default):
127                 raise ConfigError("invalid default value {0} "
128                 "for option {1} : not list type".format(str(default), name))
129         else:
130             if default != None and not self.validate(default):
131                 raise ConfigError("invalid default value {0} "
132                                          "for option {1}".format(str(default), name))
133         self.default = default
134         self.properties = [] # 'hidden', 'disabled'...
135
136     def validate(self, value):
137         if self.multi == False:
138             # None allows the reset of the value
139             if value != None:
140                 return self._validate(value)
141         else:
142             if not isinstance(value, list):
143                 raise ConfigError("invalid value {0} "
144                         "for option {1} which must be a list".format(value,
145                         self._name))
146             for val in value:
147                 if val != None:
148                     # None allows the reset of the value
149                     if not self._validate(val):
150                         return False
151         return True
152
153     def getdefault(self):
154         "accessing the default value"
155         return self.default
156
157     def is_empty_by_default(self):
158         "no default value has been set yet"
159         if ((not self.is_multi() and self.default == None) or
160             (self.is_multi() and self.default == []) or None in self.default):
161             return True
162         return False
163
164     def force_default(self):
165         "if an Option has been frozen, shall return the default value"
166         self._force_default_on_freeze = True
167
168     def hascallback_and_isfrozen():
169         return self._frozen and self.has_callback()
170
171     def is_forced_on_freeze(self):
172         "if an Option has been frozen, shall return the default value"
173         return self._frozen and self._force_default_on_freeze
174
175     def getdoc(self):
176         "accesses the Option's doc"
177         return self.doc
178
179     def getcallback(self):
180         "a callback is only a link, the name of an external hook"
181         return self.callback
182
183     def has_callback(self):
184         "to know if a callback has been defined or not"
185         if self.callback == None:
186             return False
187         else:
188             return True
189
190     def getcallback_value(self, config):
191         return carry_out_calculation(self._name,
192                 option=self, config=config)
193
194     def getcallback_params(self):
195         "if a callback has been defined, returns his arity"
196         return self.callback_params
197
198     def setowner(self, config, owner):
199         """
200         :param config: *must* be only the **parent** config
201         (not the toplevel config)
202         :param owner: is a **real* owner, that is a name or a list
203         which is allowable here
204         """
205         name = self._name
206         if not type(owner) == str:
207             raise ConfigError("invalid type for owner option: {0}".format(
208                     name))
209         config._cfgimpl_value_owners[name] = owner
210
211     def getowner(self, config):
212         "config *must* be only the **parent** config (not the toplevel config)"
213         return config._cfgimpl_value_owners[self._name]
214
215     def reset(self, config, idx=None):
216         """resets the default value and owner
217         :param idx: if not None, resets only the element at index idx
218         """
219         if self.is_multi():
220             if idx is not None:
221                 defval = self.getdefault()
222                 value = getattr(config, self._name)
223                 # if the default is ['a', 'b', 'c']
224                 if len(defval) > idx:
225                     # and idx = 2 -> there is a value in the default
226                     value.setoption(defval[idx], idx, who='default')
227                 else:
228                     # and idx = 4 -> there is actually no such value in the default
229                     value.setoption(self.default_multi, idx, who='default')
230             else:
231                 value = Multi(self.getdefault(), config, self)
232                 config.setoption(self._name, value, 'default')
233         else:
234             value = self.getdefault()
235             config.setoption(self._name, value, 'default')
236
237     def is_default_owner(self, config):
238         """
239         :param config: *must* be only the **parent** config
240         (not the toplevel config)
241         :return: boolean
242         """
243         return self.getowner(config) == 'default'
244
245     def setoption(self, config, value, who):
246         """changes the option's value with the value_owner's who
247         :param config: the parent config is necessary here to store the value
248         :param who : is **not necessarily** a owner because it cannot be a list
249         :type who: string """
250         name = self._name
251         if not self.validate(value):
252             raise ConfigError('invalid value %s for option %s' % (value, name))
253         if self.is_mandatory():
254             # value shall not be '' for a mandatory option
255             # so '' is considered as being None
256             if not self.is_multi() and value == '':
257                 value = None
258             if self.is_multi() and '' in value:
259                 value = Multi([{'': None}.get(i, i) for i in value], config, self)
260             if config.is_mandatory() and ((self.is_multi() and value == []) or \
261                 (not self.is_multi() and value is None)):
262                 raise MandatoryError('cannot change the value to %s for '
263               'option %s' % (value, name))
264         if name not in config._cfgimpl_values:
265             raise AttributeError('unknown option %s' % (name))
266
267         if config.is_frozen() and self.is_frozen():
268             raise TypeError('cannot change the value to %s for '
269                'option %s' % (str(value), name))
270         apply_requires(self, config)
271         if type(config._cfgimpl_values[name]) == Multi:
272             config._cfgimpl_previous_values[name] = list(config._cfgimpl_values[name])
273         else:
274             config._cfgimpl_previous_values[name] = config._cfgimpl_values[name]
275         config._cfgimpl_values[name] = value
276
277     def getkey(self, value):
278         return value
279     # ____________________________________________________________
280     "freeze utility"
281     def freeze(self):
282         self._frozen = True
283         return True
284     def unfreeze(self):
285         self._frozen = False
286     def is_frozen(self):
287         return self._frozen
288     # ____________________________________________________________
289     def is_multi(self):
290         return self.multi
291     def is_mandatory(self):
292         return self._mandatory
293
294 class ChoiceOption(Option):
295     opt_type = 'string'
296
297     def __init__(self, name, doc, values, default=None,
298                  requires=None, callback=None, callback_params=None,
299                  multi=False, mandatory=False, open_values=False):
300         self.values = values
301         if open_values not in [True, False]:
302             raise ConfigError('Open_values must be a boolean for '
303                               '{0}'.format(name))
304         self.open_values = open_values
305         super(ChoiceOption, self).__init__(name, doc, default=default,
306                            callback=callback, callback_params=callback_params,
307                            requires=requires, multi=multi, mandatory=mandatory)
308
309     def _validate(self, value):
310         if not self.open_values:
311             return value is None or value in self.values
312         else:
313             return True
314
315 class BoolOption(Option):
316     opt_type = 'bool'
317
318     def _validate(self, value):
319         return isinstance(value, bool)
320
321 # config level validator
322 #    def setoption(self, config, value, who):
323 #        name = self._name
324 #        if value and self._validator is not None:
325 #            toplevel = config._cfgimpl_get_toplevel()
326 #            self._validator(toplevel)
327 #        super(BoolOption, self).setoption(config, value, who)
328
329 class IntOption(Option):
330     opt_type = 'int'
331
332     def _validate(self, value):
333         return isinstance(value, int)
334
335 class FloatOption(Option):
336     opt_type = 'float'
337
338     def _validate(self, value):
339         return isinstance(value, float)
340
341 class StrOption(Option):
342     opt_type = 'string'
343
344     def _validate(self, value):
345         return isinstance(value, str)
346
347 class SymLinkOption(object):
348     opt_type = 'symlink'
349
350     def __init__(self, name, path):
351         self._name = name
352         self.path = path
353
354     def setoption(self, config, value, who):
355         setattr(config, self.path, value) # .setoption(self.path, value, who)
356
357 class IPOption(Option):
358     opt_type = 'ip'
359
360     def _validate(self, value):
361         # by now the validation is nothing but a string, use IPy instead
362         return isinstance(value, str)
363
364 class NetmaskOption(Option):
365     opt_type = 'netmask'
366
367     def _validate(self, value):
368         # by now the validation is nothing but a string, use IPy instead
369         return isinstance(value, str)
370
371 #class ArbitraryOption(Option):
372 #    def __init__(self, name, doc, default=None, defaultfactory=None,
373 #                                   requires=None, multi=False, mandatory=False):
374 #        super(ArbitraryOption, self).__init__(name, doc, requires=requires,
375 #                                               multi=multi, mandatory=mandatory)
376 #        self.defaultfactory = defaultfactory
377 #        if defaultfactory is not None:
378 #            assert default is None
379
380 #    def _validate(self, value):
381 #        return True
382
383 class OptionDescription(HiddenBaseType, DisabledBaseType):
384     "Config's schema (organisation) and container of Options"
385     "the group_type is an attribute useful for iteration on groups in a config"
386     group_type = 'default'
387     def __init__(self, name, doc, children, requires=None):
388         """
389         :param children: is a list of option descriptions (including
390         ``OptionDescription`` instances for nested namespaces).
391         """
392         self._name = name
393         self.doc = doc
394         self._children = children
395         self._requires = requires
396         self._build()
397         self.properties = [] # 'hidden', 'disabled'...
398
399     def getdoc(self):
400         return self.doc
401
402     def _build(self):
403         for child in self._children:
404             setattr(self, child._name, child)
405
406     def add_child(self, child):
407         "dynamically adds a configuration option"
408         #Nothing is static. Even the Mona Lisa is falling apart.
409         for ch in self._children:
410             if isinstance(ch, Option):
411                 if child._name == ch._name:
412                     raise ConflictConfigError("existing option : {0}".format(
413                                                                    child._name))
414         self._children.append(child)
415         setattr(self, child._name, child)
416
417     def update_child(self, child):
418         "modification of an existing option"
419         # XXX : corresponds to the `redefine`, is it usefull
420         pass
421
422     def getkey(self, config):
423         return tuple([child.getkey(getattr(config, child._name))
424                       for child in self._children])
425
426     def getpaths(self, include_groups=False, currpath=None):
427         """returns a list of all paths in self, recursively
428            currpath should not be provided (helps with recursion)
429         """
430         if currpath is None:
431             currpath = []
432         paths = []
433         for option in self._children:
434             attr = option._name
435             if attr.startswith('_cfgimpl'):
436                 continue
437             if isinstance(option, OptionDescription):
438                 if include_groups:
439                     paths.append('.'.join(currpath + [attr]))
440                 currpath.append(attr)
441                 paths += option.getpaths(include_groups=include_groups,
442                                         currpath=currpath)
443                 currpath.pop()
444             else:
445                 paths.append('.'.join(currpath + [attr]))
446         return paths
447     # ____________________________________________________________
448     def set_group_type(self, group_type):
449         ":param group_type: string in group_types"
450         if group_type in group_types:
451             self.group_type = group_type
452         else:
453             raise ConfigError('not allowed value for group_type : {0}'.format(
454                               group_type))
455
456     def get_group_type(self):
457         return self.group_type
458     # ____________________________________________________________
459     "actions API"
460     def hide(self):
461         super(OptionDescription, self).hide()
462         for child in self._children:
463             if isinstance(child, OptionDescription):
464                 child.hide()
465     def show(self):
466         super(OptionDescription, self).show()
467         for child in self._children:
468             if isinstance(child, OptionDescription):
469                 child.show()
470
471     def disable(self):
472         super(OptionDescription, self).disable()
473         for child in self._children:
474             if isinstance(child, OptionDescription):
475                 child.disable()
476     def enable(self):
477         super(OptionDescription, self).enable()
478         for child in self._children:
479             if isinstance(child, OptionDescription):
480                 child.enable()
481 # ____________________________________________________________
482
483 def validate_requires_arg(requires, name):
484     "malformed requirements"
485     config_action = []
486     for req in requires:
487         if not type(req) == tuple and len(req) != 3:
488             raise RequiresError("malformed requirements for option:"
489                                            " {0}".format(name))
490         action = req[2]
491         if action not in available_actions:
492             raise RequiresError("malformed requirements for option: {0}"
493                                 "unknown action: {1}".format(name, action))
494         if reverse_actions[action] in config_action:
495             raise RequiresError("inconsistency in action types for option: {0}"
496                                 "action: {1} in contradiction with {2}\n"
497                                 " ({3})".format(name, action,
498                                     reverse_actions[action], requires))
499         config_action.append(action)
500
501 def build_actions(requires):
502     "action are hide, show, enable, disable..."
503     trigger_actions = {}
504     for require in requires:
505         action = require[2]
506         trigger_actions.setdefault(action, []).append(require)
507     return trigger_actions
508
509 def apply_requires(opt, config):
510     "carries out the jit (just in time requirements between options"
511     if hasattr(opt, '_requires') and opt._requires is not None:
512         rootconfig = config._cfgimpl_get_toplevel()
513         validate_requires_arg(opt._requires, opt._name)
514         # filters the callbacks
515         trigger_actions = build_actions(opt._requires)
516         for requires in trigger_actions.values():
517             matches = False
518             for require in requires:
519                 name, expected, action = require
520                 path = config._cfgimpl_get_path() + '.' + opt._name
521                 if name.startswith(path):
522                     raise RequirementRecursionError("malformed requirements "
523                           "imbrication detected for option: '{0}' "
524                           "with requirement on: '{1}'".format(path, name))
525                 homeconfig, shortname = rootconfig._cfgimpl_get_home_by_path(name)
526                 try:
527                     value = homeconfig._getattr(shortname, permissive=True)
528                 except PropertiesOptionError, err:
529                     raise NotFoundError("required option has property error: "
530                                                              "{0} {1}".format(name, err.proptype))
531                 except Exception, err:
532                     raise NotFoundError("required option not found: "
533                                                              "{0}".format(name))
534                 if value == expected:
535                     getattr(opt, action)() #.hide() or show() or...
536                     # FIXME generic programming opt.property_launch(action, False)
537                     matches = True
538             # no callback has been triggered, then just reverse the action
539             if not matches:
540                 getattr(opt, reverse_actions[action])()