new api documentation
[tiramisu.git] / tiramisu / setting.py
1 # -*- coding: utf-8 -*-
2 "sets the options of the configuration objects Config object itself"
3 # Copyright (C) 2012-2013 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 time import time
24 from copy import copy
25 from tiramisu.error import RequirementRecursionError, PropertiesOptionError
26 from tiramisu.i18n import _
27
28
29 expires_time = 5
30 ro_remove = ('permissive', 'hidden')
31 ro_append = ('frozen', 'disabled', 'validator', 'everything_frozen', 'mandatory')
32 rw_remove = ('permissive', 'everything_frozen', 'mandatory')
33 rw_append = ('frozen', 'disabled', 'validator', 'hidden')
34
35
36 class _const:
37     """convenient class that emulates a module
38     and builds constants (that is, unique names)"""
39     class ConstError(TypeError):
40         pass
41
42     def __setattr__(self, name, value):
43         if name in self.__dict__:
44             raise self.ConstError, _("Can't rebind group ({})").format(name)
45         self.__dict__[name] = value
46
47     def __delattr__(self, name):
48         if name in self.__dict__:
49             raise self.ConstError, _("Can't unbind group ({})").format(name)
50         raise ValueError(name)
51
52
53 # ____________________________________________________________
54 class GroupModule(_const):
55     "emulates a module to manage unique group (OptionDescription) names"
56     class GroupType(str):
57         """allowed normal group (OptionDescription) names
58         *normal* means : groups that are not master
59         """
60         pass
61
62     class DefaultGroupType(GroupType):
63         """groups that are default (typically 'default')"""
64         pass
65
66     class MasterGroupType(GroupType):
67         """allowed normal group (OptionDescription) names
68         *master* means : groups that have the 'master' attribute set
69         """
70         pass
71 # setting.groups (emulates a module)
72 groups = GroupModule()
73
74
75 def populate_groups():
76     "populates the available groups in the appropriate namespaces"
77     groups.master = groups.MasterGroupType('master')
78     groups.default = groups.DefaultGroupType('default')
79     groups.family = groups.GroupType('family')
80
81 # names are in the module now
82 populate_groups()
83
84
85 # ____________________________________________________________
86 class OwnerModule(_const):
87     """emulates a module to manage unique owner names.
88
89     owners are living in `Config._cfgimpl_value_owners`
90     """
91     class Owner(str):
92         """allowed owner names
93         """
94         pass
95
96     class DefaultOwner(Owner):
97         """groups that are default (typically 'default')"""
98         pass
99 # setting.owners (emulates a module)
100 owners = OwnerModule()
101
102
103 def populate_owners():
104     """populates the available owners in the appropriate namespaces
105
106     - 'user' is the generic is the generic owner.
107     - 'default' is the config owner after init time
108     """
109     setattr(owners, 'default', owners.DefaultOwner('default'))
110     setattr(owners, 'user', owners.Owner('user'))
111
112     def add_owner(name):
113         """
114         :param name: the name of the new owner
115         """
116         setattr(owners, name, owners.Owner(name))
117     setattr(owners, 'add_owner', add_owner)
118
119 # names are in the module now
120 populate_owners()
121
122
123 class MultiTypeModule(_const):
124     class MultiType(str):
125         pass
126
127     class DefaultMultiType(MultiType):
128         pass
129
130     class MasterMultiType(MultiType):
131         pass
132
133     class SlaveMultiType(MultiType):
134         pass
135
136 multitypes = MultiTypeModule()
137
138
139 def populate_multitypes():
140     setattr(multitypes, 'default', multitypes.DefaultMultiType('default'))
141     setattr(multitypes, 'master', multitypes.MasterMultiType('master'))
142     setattr(multitypes, 'slave', multitypes.SlaveMultiType('slave'))
143
144 populate_multitypes()
145
146
147 class Property(object):
148     "a property is responsible of the option's value access rules"
149     __slots__ = ('_setting', '_properties', '_opt')
150
151     def __init__(self, setting, prop, opt=None):
152         self._opt = opt
153         self._setting = setting
154         self._properties = prop
155
156     def append(self, propname):
157         self._properties.add(propname)
158         self._setting._set_properties(self._properties, self._opt)
159         self._setting.context.cfgimpl_reset_cache()
160
161     def remove(self, propname):
162         if propname in self._properties:
163             self._properties.remove(propname)
164             self._setting._set_properties(self._properties, self._opt)
165             self._setting.context.cfgimpl_reset_cache()
166
167     def __contains__(self, propname):
168         return propname in self._properties
169
170     def __repr__(self):
171         return str(list(self._properties))
172
173
174 #____________________________________________________________
175 class Setting(object):
176     "``Config()``'s configuration options"
177     __slots__ = ('context', '_properties', '_permissives', '_owner', '_cache')
178
179     def __init__(self, context):
180         # properties attribute: the name of a property enables this property
181         # key is None for global properties
182         self._properties = {None: set(('expire', 'validator'))}
183         # permissive properties
184         self._permissives = {}
185         # generic owner
186         self._owner = owners.user
187         self.context = context
188         self._cache = {}
189
190     #____________________________________________________________
191     # properties methods
192     def __contains__(self, propname):
193         return propname in self._get_properties()
194
195     def __repr__(self):
196         return str(list(self._get_properties()))
197
198     def __getitem__(self, opt):
199         return Property(self, self._get_properties(opt), opt)
200
201     def __setitem__(self, opt, value):
202         raise ValueError('you must only append/remove properties')
203
204     def _get_properties(self, opt=None, is_apply_req=True):
205         if opt is None:
206             props = self._properties.get(opt, set())
207         else:
208             exp = None
209             if opt in self._cache:
210                 exp = time()
211                 props, created = self._cache[opt]
212                 if exp < created:
213                     return props
214             if is_apply_req:
215                 apply_requires(opt, self.context)
216             props = self._properties.get(opt, opt._properties)
217             self._set_cache(opt, props, exp)
218         return props
219
220     def append(self, propname):
221         "puts property propname in the Config's properties attribute"
222         Property(self, self._get_properties()).append(propname)
223
224     def remove(self, propname):
225         "deletes property propname in the Config's properties attribute"
226         Property(self, self._get_properties()).remove(propname)
227
228     def _set_properties(self, properties, opt=None):
229         """save properties for specified opt
230         (never save properties if same has option properties)
231         """
232         if opt is None:
233             self._properties[opt] = properties
234         else:
235             if opt._properties == properties:
236                 if opt in self._properties:
237                     del(self._properties[opt])
238             else:
239                 self._properties[opt] = properties
240
241     #____________________________________________________________
242     def validate_properties(self, opt_or_descr, is_descr, is_write,
243                             value=None, force_permissive=False,
244                             force_properties=None):
245         #opt properties
246         properties = copy(self._get_properties(opt_or_descr))
247         #remove opt permissive
248         properties -= self._get_permissive(opt_or_descr)
249         #remove global permissive if need
250         self_properties = copy(self._get_properties())
251         if force_permissive is True or 'permissive' in self_properties:
252             properties -= self._get_permissive()
253
254         #global properties
255         if force_properties is not None:
256             self_properties.update(force_properties)
257
258         #calc properties
259         properties &= self_properties
260         #mandatory and frozen are special properties
261         if is_descr:
262             properties -= frozenset(('mandatory', 'frozen'))
263         else:
264             if 'mandatory' in properties and \
265                     not self.context.cfgimpl_get_values()._is_empty(opt_or_descr,
266                                                                     value):
267                 properties.remove('mandatory')
268             if is_write and 'everything_frozen' in self_properties:
269                 properties.add('frozen')
270             elif 'frozen' in properties and not is_write:
271                 properties.remove('frozen')
272
273         if properties != frozenset():
274             if 'frozen' in properties:
275                 raise_text = 'cannot change the value for option {0} this option is frozen'
276             else:
277                 raise_text = "trying to access to an option named: {0} with properties {1}"
278             raise PropertiesOptionError(_(raise_text).format(opt_or_descr._name,
279                                         str(properties)),
280                                         list(properties))
281
282     def _get_permissive(self, opt=None):
283         return self._permissives.get(opt, frozenset())
284
285     def set_permissive(self, permissive, opt=None):
286         if not isinstance(permissive, tuple):
287             raise TypeError(_('permissive must be a tuple'))
288         self._permissives[opt] = frozenset(permissive)
289
290     #____________________________________________________________
291     def setowner(self, owner):
292         ":param owner: sets the default value for owner at the Config level"
293         if not isinstance(owner, owners.Owner):
294             raise TypeError(_("invalid generic owner {0}").format(str(owner)))
295         self._owner = owner
296
297     def getowner(self):
298         return self._owner
299
300     #____________________________________________________________
301     def _read(self, remove, append):
302         for prop in remove:
303             self.remove(prop)
304         for prop in append:
305             self.append(prop)
306
307     def read_only(self):
308         "convenience method to freeze, hidde and disable"
309         self._read(ro_remove, ro_append)
310
311     def read_write(self):
312         "convenience method to freeze, hidde and disable"
313         self._read(rw_remove, rw_append)
314
315     def _set_cache(self, opt, props, exp):
316         if 'expire' in self:
317             if exp is None:
318                 exp = time()
319             self._cache[opt] = (props, time() + expires_time)
320
321     def reset_cache(self, only_expired):
322         if only_expired:
323             exp = time()
324             keys = self._cache.keys()
325             for key in keys:
326                 props, created = self._cache[key]
327                 if exp > created:
328                     del(self._cache[key])
329         else:
330             self._cache.clear()
331
332
333 def apply_requires(opt, config):
334     "carries out the jit (just in time requirements between options"
335     def build_actions(requires):
336         "action are hide, show, enable, disable..."
337         trigger_actions = {}
338         for require in requires:
339             action = require[2]
340             trigger_actions.setdefault(action, []).append(require)
341         return trigger_actions
342     #for symlink
343     if hasattr(opt, '_requires') and opt._requires is not None:
344         # filters the callbacks
345         settings = config.cfgimpl_get_settings()
346         setting = Property(settings, settings._get_properties(opt, False), opt)
347         trigger_actions = build_actions(opt._requires)
348         descr = config.cfgimpl_get_context().cfgimpl_get_description()
349         optpath = descr.impl_get_path_by_opt(opt)
350         for requires in trigger_actions.values():
351             matches = False
352             for require in requires:
353                 if len(require) == 3:
354                     option, expected, action = require
355                     inverse = False
356                 elif len(require) == 4:
357                     option, expected, action, inverse = require
358                 path = descr.impl_get_path_by_opt(option)
359                 if path == optpath or path.startswith(optpath + '.'):
360                     raise RequirementRecursionError(_("malformed requirements "
361                                                     "imbrication detected for option: '{0}' "
362                                                     "with requirement on: '{1}'").format(optpath, path))
363                 try:
364                     value = config.cfgimpl_get_context()._getattr(path, force_permissive=True)
365                 except PropertiesOptionError, err:
366                     properties = err.proptype
367                     raise PropertiesOptionError(_("option '{0}' has requirement's property error: "
368                                                   "{1} {2}").format(opt._name, path, properties), properties)
369                 except AttributeError:
370                     raise AttributeError(_("required option not found: "
371                                          "{0}").format(path))
372                 if value == expected:
373                     if inverse:
374                         setting.remove(action)
375                     else:
376                         setting.append(action)
377                     matches = True
378             # no requirement has been triggered, then just reverse the action
379             if not matches:
380                 if inverse:
381                     setting.append(action)
382                 else:
383                     setting.remove(action)