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