tiramisu/config.py

   1 # -*- coding: utf-8 -*-
   2 "options handler global entry point"
   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 import weakref
  24 from tiramisu.error import PropertiesOptionError, ConfigError
  25 from tiramisu.option import OptionDescription, Option, SymLinkOption
  26 from tiramisu.setting import groups, Settings, default_encoding
  27 from tiramisu.storage import get_storages
  28 from tiramisu.value import Values
  29 from tiramisu.i18n import _
  30
  31
  32 class SubConfig(object):
  33     "sub configuration management entry"
  34     __slots__ = ('_impl_context', '_impl_descr', '_impl_path')
  35
  36     def __init__(self, descr, context, subpath=None):
  37         """ Configuration option management master class
  38
  39         :param descr: describes the configuration schema
  40         :type descr: an instance of ``option.OptionDescription``
  41         :param context: the current root config
  42         :type context: `Config`
  43         :type subpath: `str` with the path name
  44         """
  45         # main option description
  46         if descr is not None and not isinstance(descr, OptionDescription):
  47             raise TypeError(_('descr must be an optiondescription, not {0}'
  48                               ).format(type(descr)))
  49         self._impl_descr = descr
  50         # sub option descriptions
  51         if not isinstance(context, weakref.ReferenceType):
  52             raise ValueError('context must be a Weakref')
  53         self._impl_context = context
  54         self._impl_path = subpath
  55
  56     def cfgimpl_reset_cache(self, only_expired=False, only=('values',
  57                                                             'settings')):
  58         self._cfgimpl_get_context().cfgimpl_reset_cache(only_expired, only)
  59
  60     def cfgimpl_get_home_by_path(self, path, force_permissive=False,
  61                                  force_properties=None):
  62         """:returns: tuple (config, name)"""
  63         path = path.split('.')
  64         for step in path[:-1]:
  65             self = self._getattr(step,
  66                                  force_permissive=force_permissive,
  67                                  force_properties=force_properties)
  68         return self, path[-1]
  69
  70     def __hash__(self):
  71         return hash(self.cfgimpl_get_description().impl_getkey(self))
  72
  73     def __eq__(self, other):
  74         "Config's comparison"
  75         if not isinstance(other, Config):
  76             return False
  77         return self.cfgimpl_get_description().impl_getkey(self) == \
  78             other.cfgimpl_get_description().impl_getkey(other)
  79
  80     def __ne__(self, other):
  81         "Config's comparison"
  82         if not isinstance(other, Config):
  83             return True
  84         return not self == other
  85
  86     # ______________________________________________________________________
  87     def __iter__(self):
  88         """Pythonesque way of parsing group's ordered options.
  89         iteration only on Options (not OptionDescriptions)"""
  90         for child in self.cfgimpl_get_description().impl_getchildren():
  91             if not isinstance(child, OptionDescription):
  92                 try:
  93                     yield child._name, getattr(self, child._name)
  94                 except GeneratorExit:
  95                     raise StopIteration
  96                 except PropertiesOptionError:
  97                     pass  # option with properties
  98
  99     def iter_all(self):
 100         """A way of parsing options **and** groups.
 101         iteration on Options and OptionDescriptions."""
 102         for child in self.cfgimpl_get_description().impl_getchildren():
 103             try:
 104                 yield child._name, getattr(self, child._name)
 105             except GeneratorExit:
 106                 raise StopIteration
 107             except PropertiesOptionError:
 108                 pass  # option with properties
 109
 110     def iter_groups(self, group_type=None):
 111         """iteration on groups objects only.
 112         All groups are returned if `group_type` is `None`, otherwise the groups
 113         can be filtered by categories (families, or whatever).
 114
 115         :param group_type: if defined, is an instance of `groups.GroupType`
 116                            or `groups.MasterGroupType` that lives in
 117                            `setting.groups`
 118         """
 119         if group_type is not None and not isinstance(group_type,
 120                                                      groups.GroupType):
 121             raise TypeError(_("unknown group_type: {0}").format(group_type))
 122         for child in self.cfgimpl_get_description().impl_getchildren():
 123             if isinstance(child, OptionDescription):
 124                 try:
 125                     if group_type is None or (group_type is not None and
 126                                               child.impl_get_group_type()
 127                                               == group_type):
 128                         yield child._name, getattr(self, child._name)
 129                 except GeneratorExit:
 130                     raise StopIteration
 131                 except PropertiesOptionError:
 132                     pass
 133     # ______________________________________________________________________
 134
 135     def __str__(self):
 136         "Config's string representation"
 137         lines = []
 138         for name, grp in self.iter_groups():
 139             lines.append("[{0}]".format(name))
 140         for name, value in self:
 141             try:
 142                 lines.append("{0} = {1}".format(name, value))
 143             except UnicodeEncodeError:
 144                 lines.append("{0} = {1}".format(name,
 145                                                 value.encode(default_encoding)))
 146             except PropertiesOptionError:
 147                 pass
 148         return '\n'.join(lines)
 149
 150     __repr__ = __str__
 151
 152     def _cfgimpl_get_context(self):
 153         return self._impl_context()
 154
 155     def cfgimpl_get_description(self):
 156         if self._impl_descr is None:
 157             raise ConfigError(_('no option description found for this config'
 158                                 ' (may be metaconfig without meta)'))
 159         else:
 160             return self._impl_descr
 161
 162     def cfgimpl_get_settings(self):
 163         return self._cfgimpl_get_context()._impl_settings
 164
 165     def cfgimpl_get_values(self):
 166         return self._cfgimpl_get_context()._impl_values
 167
 168     # ____________________________________________________________
 169     # attribute methods
 170     def __setattr__(self, name, value):
 171         "attribute notation mechanism for the setting of the value of an option"
 172         if name.startswith('_impl_'):
 173             object.__setattr__(self, name, value)
 174             return
 175         self._setattr(name, value)
 176
 177     def _setattr(self, name, value, force_permissive=False):
 178         if '.' in name:
 179             homeconfig, name = self.cfgimpl_get_home_by_path(name)
 180             return homeconfig.__setattr__(name, value)
 181         child = getattr(self.cfgimpl_get_description(), name)
 182         if not isinstance(child, SymLinkOption):
 183             if self._impl_path is None:
 184                 path = name
 185             else:
 186                 path = self._impl_path + '.' + name
 187             self.cfgimpl_get_values().setitem(child, value, path,
 188                                               force_permissive=force_permissive)
 189         else:
 190             context = self._cfgimpl_get_context()
 191             path = context.cfgimpl_get_description().impl_get_path_by_opt(
 192                 child._opt)
 193             context._setattr(path, value, force_permissive=force_permissive)
 194
 195     def __delattr__(self, name):
 196         child = getattr(self.cfgimpl_get_description(), name)
 197         self.cfgimpl_get_values().__delitem__(child)
 198
 199     def __getattr__(self, name):
 200         return self._getattr(name)
 201
 202     def _getattr(self, name, force_permissive=False, force_properties=None,
 203                  validate=True):
 204         """
 205         attribute notation mechanism for accessing the value of an option
 206         :param name: attribute name
 207         :return: option's value if name is an option name, OptionDescription
 208                  otherwise
 209         """
 210         # attribute access by passing a path,
 211         # for instance getattr(self, "creole.general.family.adresse_ip_eth0")
 212         if '.' in name:
 213             homeconfig, name = self.cfgimpl_get_home_by_path(
 214                 name, force_permissive=force_permissive,
 215                 force_properties=force_properties)
 216             return homeconfig._getattr(name, force_permissive=force_permissive,
 217                                        force_properties=force_properties,
 218                                        validate=validate)
 219         opt_or_descr = getattr(self.cfgimpl_get_description(), name)
 220         if self._impl_path is None:
 221             subpath = name
 222         else:
 223             subpath = self._impl_path + '.' + name
 224         # symlink options
 225         if isinstance(opt_or_descr, SymLinkOption):
 226             context = self._cfgimpl_get_context()
 227             path = context.cfgimpl_get_description().impl_get_path_by_opt(
 228                 opt_or_descr._opt)
 229             return context._getattr(path, validate=validate,
 230                                     force_properties=force_properties,
 231                                     force_permissive=force_permissive)
 232         elif isinstance(opt_or_descr, OptionDescription):
 233             self.cfgimpl_get_settings().validate_properties(
 234                 opt_or_descr, True, False, path=subpath,
 235                 force_permissive=force_permissive,
 236                 force_properties=force_properties)
 237             return SubConfig(opt_or_descr, self._impl_context, subpath)
 238         else:
 239             return self.cfgimpl_get_values().getitem(
 240                 opt_or_descr, path=subpath,
 241                 validate=validate,
 242                 force_properties=force_properties,
 243                 force_permissive=force_permissive)
 244
 245     def find(self, bytype=None, byname=None, byvalue=None, type_='option'):
 246         """
 247             finds a list of options recursively in the config
 248
 249             :param bytype: Option class (BoolOption, StrOption, ...)
 250             :param byname: filter by Option._name
 251             :param byvalue: filter by the option's value
 252             :returns: list of matching Option objects
 253         """
 254         return self._cfgimpl_get_context()._find(bytype, byname, byvalue,
 255                                                  first=False,
 256                                                  type_=type_,
 257                                                  _subpath=self.cfgimpl_get_path()
 258                                                  )
 259
 260     def find_first(self, bytype=None, byname=None, byvalue=None,
 261                    type_='option', display_error=True):
 262         """
 263             finds an option recursively in the config
 264
 265             :param bytype: Option class (BoolOption, StrOption, ...)
 266             :param byname: filter by Option._name
 267             :param byvalue: filter by the option's value
 268             :returns: list of matching Option objects
 269         """
 270         return self._cfgimpl_get_context()._find(
 271             bytype, byname, byvalue, first=True, type_=type_,
 272             _subpath=self.cfgimpl_get_path(), display_error=display_error)
 273
 274     def _find(self, bytype, byname, byvalue, first, type_='option',
 275               _subpath=None, check_properties=True, display_error=True):
 276         """
 277         convenience method for finding an option that lives only in the subtree
 278
 279         :param first: return only one option if True, a list otherwise
 280         :return: find list or an exception if nothing has been found
 281         """
 282         def _filter_by_name():
 283             try:
 284                 if byname is None or path == byname or \
 285                         path.endswith('.' + byname):
 286                     return True
 287             except IndexError:
 288                 pass
 289             return False
 290
 291         def _filter_by_value():
 292             if byvalue is None:
 293                 return True
 294             try:
 295                 value = getattr(self, path)
 296                 if value == byvalue:
 297                     return True
 298             except PropertiesOptionError:  # a property is a restriction
 299                                            # upon the access of the value
 300                 pass
 301             return False
 302
 303         def _filter_by_type():
 304             if bytype is None:
 305                 return True
 306             if isinstance(option, bytype):
 307                 return True
 308             return False
 309
 310         if type_ not in ('option', 'path', 'value'):
 311             raise ValueError(_('unknown type_ type {0}'
 312                                'for _find').format(type_))
 313         find_results = []
 314         opts, paths = self.cfgimpl_get_description()._cache_paths
 315         for index in range(0, len(paths)):
 316             option = opts[index]
 317             if isinstance(option, OptionDescription):
 318                 continue
 319             path = paths[index]
 320             if _subpath is not None and not path.startswith(_subpath + '.'):
 321                 continue
 322             if not _filter_by_name():
 323                 continue
 324             if not _filter_by_value():
 325                 continue
 326             #remove option with propertyerror, ...
 327             if check_properties:
 328                 try:
 329                     value = getattr(self, path)
 330                 except PropertiesOptionError:
 331                     # a property restricts the access of the value
 332                     continue
 333             if not _filter_by_type():
 334                 continue
 335             if type_ == 'value':
 336                 retval = value
 337             elif type_ == 'path':
 338                 retval = path
 339             elif type_ == 'option':
 340                 retval = option
 341             if first:
 342                 return retval
 343             else:
 344                 find_results.append(retval)
 345         return self._find_return_results(find_results, display_error)
 346
 347     def _find_return_results(self, find_results, display_error):
 348         if find_results == []:
 349             if display_error:
 350                 raise AttributeError(_("no option found in config"
 351                                        " with these criteria"))
 352             else:
 353                 # translation is slow
 354                 raise AttributeError()
 355         else:
 356             return find_results
 357
 358     def make_dict(self, flatten=False, _currpath=None, withoption=None,
 359                   withvalue=None):
 360         """exports the whole config into a `dict`, for example:
 361
 362         >>> print cfg.make_dict()
 363         {'od2.var4': None, 'od2.var5': None, 'od2.var6': None}
 364
 365
 366
 367         :param flatten: returns a dict(name=value) instead of a dict(path=value)
 368                         ::
 369
 370                             >>> print cfg.make_dict(flatten=True)
 371                             {'var5': None, 'var4': None, 'var6': None}
 372
 373         :param withoption: returns the options that are present in the very same
 374                            `OptionDescription` than the `withoption` itself::
 375
 376                                 >>> print cfg.make_dict(withoption='var1')
 377                                 {'od2.var4': None, 'od2.var5': None,
 378                                 'od2.var6': None,
 379                                 'od2.var1': u'value',
 380                                 'od1.var1': None,
 381                                 'od1.var3': None,
 382                                 'od1.var2': None}
 383
 384         :param withvalue: returns the options that have the value `withvalue`
 385                           ::
 386
 387                             >>> print c.make_dict(withoption='var1',
 388                                                   withvalue=u'value')
 389                             {'od2.var4': None,
 390                             'od2.var5': None,
 391                             'od2.var6': None,
 392                             'od2.var1': u'value'}
 393
 394         :returns: dict of Option's name (or path) and values
 395         """
 396         pathsvalues = []
 397         if _currpath is None:
 398             _currpath = []
 399         if withoption is None and withvalue is not None:
 400             raise ValueError(_("make_dict can't filtering with value without "
 401                                "option"))
 402         if withoption is not None:
 403             mypath = self.cfgimpl_get_path()
 404             for path in self._cfgimpl_get_context()._find(bytype=Option,
 405                                                           byname=withoption,
 406                                                           byvalue=withvalue,
 407                                                           first=False,
 408                                                           type_='path',
 409                                                           _subpath=mypath):
 410                 path = '.'.join(path.split('.')[:-1])
 411                 opt = self._cfgimpl_get_context().cfgimpl_get_description(
 412                 ).impl_get_opt_by_path(path)
 413                 if mypath is not None:
 414                     if mypath == path:
 415                         withoption = None
 416                         withvalue = None
 417                         break
 418                     else:
 419                         tmypath = mypath + '.'
 420                         if not path.startswith(tmypath):
 421                             raise AttributeError(_('unexpected path {0}, '
 422                                                    'should start with {1}'
 423                                                    '').format(path, mypath))
 424                         path = path[len(tmypath):]
 425                 self._make_sub_dict(opt, path, pathsvalues, _currpath, flatten)
 426         #withoption can be set to None below !
 427         if withoption is None:
 428             for opt in self.cfgimpl_get_description().impl_getchildren():
 429                 path = opt._name
 430                 self._make_sub_dict(opt, path, pathsvalues, _currpath, flatten)
 431         if _currpath == []:
 432             options = dict(pathsvalues)
 433             return options
 434         return pathsvalues
 435
 436     def _make_sub_dict(self, opt, path, pathsvalues, _currpath, flatten):
 437         if isinstance(opt, OptionDescription):
 438             try:
 439                 pathsvalues += getattr(self, path).make_dict(flatten,
 440                                                              _currpath +
 441                                                              path.split('.'))
 442             except PropertiesOptionError:
 443                 pass  # this just a hidden or disabled option
 444         else:
 445             try:
 446                 value = self._getattr(opt._name)
 447                 if flatten:
 448                     name = opt._name
 449                 else:
 450                     name = '.'.join(_currpath + [opt._name])
 451                 pathsvalues.append((name, value))
 452             except PropertiesOptionError:
 453                 pass  # this just a hidden or disabled option
 454
 455     def cfgimpl_get_path(self):
 456         descr = self.cfgimpl_get_description()
 457         context_descr = self._cfgimpl_get_context().cfgimpl_get_description()
 458         return context_descr.impl_get_path_by_opt(descr)
 459
 460
 461 class CommonConfig(SubConfig):
 462     "abstract base class for the Config and the MetaConfig"
 463     __slots__ = ('_impl_values', '_impl_settings', '_impl_meta')
 464
 465     def _impl_build_all_paths(self):
 466         self.cfgimpl_get_description().impl_build_cache()
 467
 468     def read_only(self):
 469         "read only is a global config's setting, see `settings.py`"
 470         self.cfgimpl_get_settings().read_only()
 471
 472     def read_write(self):
 473         "read write is a global config's setting, see `settings.py`"
 474         self.cfgimpl_get_settings().read_write()
 475
 476     def getowner(self, opt):
 477         """convenience method to retrieve an option's owner
 478         from the config itself
 479         """
 480         if not isinstance(opt, Option) and not isinstance(opt, SymLinkOption):
 481             raise TypeError(_('opt in getowner must be an option not {0}'
 482                               '').format(type(opt)))
 483         return self.cfgimpl_get_values().getowner(opt)
 484
 485     def unwrap_from_path(self, path, force_permissive=False):
 486         """convenience method to extract and Option() object from the Config()
 487         and it is **fast**: finds the option directly in the appropriate
 488         namespace
 489
 490         :returns: Option()
 491         """
 492         if '.' in path:
 493             homeconfig, path = self.cfgimpl_get_home_by_path(
 494                 path, force_permissive=force_permissive)
 495             return getattr(homeconfig.cfgimpl_get_description(), path)
 496         return getattr(self.cfgimpl_get_description(), path)
 497
 498     def cfgimpl_get_path(self):
 499         return None
 500
 501     def cfgimpl_get_meta(self):
 502         return self._impl_meta
 503
 504     # information
 505     def impl_set_information(self, key, value):
 506         """updates the information's attribute
 507
 508         :param key: information's key (ex: "help", "doc"
 509         :param value: information's value (ex: "the help string")
 510         """
 511         self._impl_values.set_information(key, value)
 512
 513     def impl_get_information(self, key, default=None):
 514         """retrieves one information's item
 515
 516         :param key: the item string (ex: "help")
 517         """
 518         return self._impl_values.get_information(key, default)
 519
 520
 521 # ____________________________________________________________
 522 class Config(CommonConfig):
 523     "main configuration management entry"
 524     __slots__ = ('__weakref__', )
 525
 526     def __init__(self, descr, session_id=None, persistent=False):
 527         """ Configuration option management master class
 528
 529         :param descr: describes the configuration schema
 530         :type descr: an instance of ``option.OptionDescription``
 531         :param context: the current root config
 532         :type context: `Config`
 533         :param session_id: session ID is import with persistent Config to
 534         retrieve good session
 535         :type session_id: `str`
 536         :param persistent: if persistent, don't delete storage when leaving
 537         :type persistent: `boolean`
 538         """
 539         settings, values = get_storages(self, session_id, persistent)
 540         self._impl_settings = Settings(self, settings)
 541         self._impl_values = Values(self, values)
 542         super(Config, self).__init__(descr, weakref.ref(self))
 543         self._impl_build_all_paths()
 544         self._impl_meta = None
 545
 546     def cfgimpl_reset_cache(self,
 547                             only_expired=False,
 548                             only=('values', 'settings')):
 549         if 'values' in only:
 550             self.cfgimpl_get_values().reset_cache(only_expired=only_expired)
 551         if 'settings' in only:
 552             self.cfgimpl_get_settings().reset_cache(only_expired=only_expired)
 553
 554
 555 class MetaConfig(CommonConfig):
 556     __slots__ = ('_impl_children', '__weakref__')
 557
 558     def __init__(self, children, meta=True, session_id=None, persistent=False):
 559         if not isinstance(children, list):
 560             raise ValueError(_("metaconfig's children must be a list"))
 561         descr = None
 562         if meta:
 563             for child in children:
 564                 if not isinstance(child, CommonConfig):
 565                     raise TypeError(_("metaconfig's children "
 566                                       "must be config, not {0}"
 567                                       ).format(type(child)))
 568                 if descr is None:
 569                     descr = child.cfgimpl_get_description()
 570                 elif not descr is child.cfgimpl_get_description():
 571                     raise ValueError(_('all config in metaconfig must '
 572                                        'have the same optiondescription'))
 573                 if child.cfgimpl_get_meta() is not None:
 574                     raise ValueError(_("child has already a metaconfig's"))
 575                 child._impl_meta = self
 576
 577         self._impl_children = children
 578         settings, values = get_storages(self, session_id, persistent)
 579         self._impl_settings = Settings(self, settings)
 580         self._impl_values = Values(self, values)
 581         super(MetaConfig, self).__init__(descr, weakref.ref(self))
 582         self._impl_meta = None
 583
 584     def cfgimpl_get_children(self):
 585         return self._impl_children
 586
 587     def cfgimpl_get_context(self):
 588         "a meta config is a config wich has a setting, that is itself"
 589         return self
 590
 591     def cfgimpl_reset_cache(self,
 592                             only_expired=False,
 593                             only=('values', 'settings')):
 594         if 'values' in only:
 595             self.cfgimpl_get_values().reset_cache(only_expired=only_expired)
 596         if 'settings' in only:
 597             self.cfgimpl_get_settings().reset_cache(only_expired=only_expired)
 598         for child in self._impl_children:
 599             child.cfgimpl_reset_cache(only_expired=only_expired, only=only)
 600
 601     def set_contexts(self, path, value):
 602         for child in self._impl_children:
 603             try:
 604                 if not isinstance(child, MetaConfig):
 605                     setattr(child, path, value)
 606                 else:
 607                     child.set_contexts(path, value)
 608             except PropertiesOptionError:
 609                 pass
 610
 611     def find_first_contexts(self, byname=None, bypath=None, byvalue=None,
 612                             type_='path', display_error=True):
 613         ret = []
 614         try:
 615             if bypath is None and byname is not None and \
 616                     self.cfgimpl_get_description() is not None:
 617                 bypath = self._find(bytype=None, byvalue=None, byname=byname,
 618                                     first=True, type_='path',
 619                                     check_properties=False,
 620                                     display_error=display_error)
 621         except ConfigError:
 622             pass
 623         for child in self._impl_children:
 624             try:
 625                 if not isinstance(child, MetaConfig):
 626                     if bypath is not None:
 627                         if byvalue is not None:
 628                             if getattr(child, bypath) == byvalue:
 629                                 ret.append(child)
 630                         else:
 631                             #not raise
 632                             getattr(child, bypath)
 633                             ret.append(child)
 634                     else:
 635                         ret.append(child.find_first(byname=byname,
 636                                                     byvalue=byvalue,
 637                                                     type_=type_,
 638                                                     display_error=False))
 639                 else:
 640                     ret.extend(child.find_first_contexts(byname=byname,
 641                                                          bypath=bypath,
 642                                                          byvalue=byvalue,
 643                                                          type_=type_,
 644                                                          display_error=False))
 645             except AttributeError:
 646                 pass
 647         return self._find_return_results(ret, display_error)
 648
 649
 650 def mandatory_warnings(config):
 651     """convenience function to trace Options that are mandatory and
 652     where no value has been set
 653
 654     :returns: generator of mandatory Option's path
 655
 656     """
 657     #if value in cache, properties are not calculated
 658     config.cfgimpl_reset_cache(only=('values',))
 659     for path in config.cfgimpl_get_description().impl_getpaths(
 660             include_groups=True):
 661         try:
 662             config._getattr(path, force_properties=frozenset(('mandatory',)))
 663         except PropertiesOptionError as err:
 664             if err.proptype == ['mandatory']:
 665                 yield path
 666     config.cfgimpl_reset_cache(only=('values',))