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