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