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