:mod:`VirtualMailManager.Config` --- Simplified configuration access======================================================================..module:: VirtualMailManager.Config:synopsis: Simplified configuration access..moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>..toctree:::maxdepth: 2This module provides a few classes for simplified configuration handlingand the validation of the setting's *type* and *value*.:class:`LazyConfig` is derived from Python's:class:`ConfigParser.RawConfigParser`. It doesn't use ``RawConfigParser``'s``DEFAULT`` section. All settings and their defaults, if supposed, arehandled by :class:`LazyConfigOption` objects in the :attr:`LazyConfig._cfg`*dict*.``LazyConfig``'s setters and getters for options are taking a single stringfor the *section* and *option* argument, e.g. ``config.pget('database.user')``instead of ``config.get('database', 'user')``.LazyConfig----------..class:: LazyConfig Bases: :class:`ConfigParser.RawConfigParser` ..versionadded:: 0.6.0 ..attribute:: _cfg a multi dimensional :class:`dict`, containing *sections* and *options*, represented by :class:`LazyConfigOption` objects. For example:: from VirtualMailManager.Config import LazyConfig, LazyConfigOption class FooConfig(LazyConfig): def __init__(self, ...): LazyConfig.__init__(self) ... LCO = LazyConfigOption self._cfg = { 'database': {# section database: 'host': LCO(str, '::1', self.get), # options of the 'name': LCO(str, 'dbx', self.get), # database section. 'pass': LCO(str, None, self.get), # No defaults for the 'user': LCO(str, None, self.get), # user and pass options } } ... ..method:: bool_new(value) Converts the string *value* into a `bool` and returns it.|``'1'``, ``'on'``, ``'yes'`` and ``'true'`` will become :const:`True`|``'0'``, ``'off'``, ``'no'`` and ``'false'`` will become :const:`False`:param value: one of the above mentioned strings:type value::obj:`basestring`:rtype: bool:raise ConfigValueError: for all other values, except ``bool``\ s .. method:: dget(option) Like :meth:`pget`, but returns the *option*'s default value, from :attr:`_cfg` (defined by :attr:`LazyConfigOption.default`) if the *option* is not configured in a ini-like configuration file. :param option: the section.option combination :type option: :obj:`basestring` :raise NoDefaultError: if the *option* couldn't be found in the configuration file and no default value was passed to :class:`LazyConfigOption`'s constructor for the requested *option*. .. method:: getboolean(section, option) Returns the boolean value of the *option*, in the given *section*. For a boolean :const:`True`, the value must be set to ``'1'``, ``'on'``, ``'yes'``, ``'true'`` or :const:`True`. For a boolean :const:`False`, the value must set to ``'0'``, ``'off'``, ``'no'``, ``'false'`` or :const:`False`. :param section: The section's name :type section: :obj:`basestring` :param option: The option's name :type option: :obj:`basestring` :rtype: bool :raise ValueError: if the option has an other value than the values mentioned above. .. method:: has_option(option) Checks if the *option* (section\ **.**\ option) is a known configuration option. :param option: The option's name :type option: :obj:`basestring` :rtype: bool .. method:: has_section(section) Checks if *section* is a known configuration section. :param section: The section's name :type section: :obj:`basestring` :rtype: bool .. method:: items(section) Returns an iterator for ``key, value``:obj:`tuple`\ s for each option in the given *section*.:param section: The section's name:type section::obj:`basestring`:raise NoSectionError: if the given *section* is not known. ..method:: pget(option) Polymorphic getter which returns the *option*'s value (by calling:attr:`LazyConfigOption.getter`) with the appropriate type, defined by:attr:`LazyConfigOption.cls`.:param option: the section.option combination:type option::obj:`basestring` ..method:: sections() Returns an iterator object for all configuration sections from the:attr:`_cfg` dictionary.:rtype::obj:`dictionary-keyiterator` ..method:: set(option, value) Like :meth:`ConfigParser.RawConfigParser.set`, but converts the *option*'s new *value* (by calling :attr:`LazyConfigOption.cls`) to the appropriate type/class. When the ``LazyConfigOption``'s optional parameter *validate* was not :const:`None`, the new *value* will be also validated.:param option: the section.option combination:type option::obj:`basestring`:param value: the new value to be set:type value::obj:`basestring`:rtype::const:`None`:raise ConfigValueError: if a boolean value shout be set (:meth:`bool_new`) and it fails:raise ValueError: if an other setter (:attr:`LazyConfigOption.cls`) or validator (:attr:`LazyConfigOption.validate`) fails.:raise VirtualMailManager.errors.VMMError: if:attr:`LazyConfigOption.validate` is set to:func:`VirtualMailManager.exec_ok` or :func:`VirtualMailManager.is_dir`.LazyConfigOption----------------LazyConfigOption instances are required by :class:`LazyConfig` instances, andinstances of classes derived from `LazyConfig`, like the :class:`Config`class...class:: LazyConfigOption (cls, default, getter[, validate=None]) ..versionadded:: 0.6.0 The constructor's parameters are:``cls`` : :obj:`type` The class/type of the option's value.``default`` : :obj:`str` or the one defined by ``cls`` Default value of the option. Use :const:`None` if the option shouldn't have a default value.``getter``: :obj:`callable` A method's name of :class:`ConfigParser.RawConfigParser` and derived classes, to get a option's value, e.g. `self.getint`.``validate`` : :obj:`callable` or :const:`None`:const:`None` or any function, which takes one argument and returns the validated argument with the appropriate type (for example::meth:`LazyConfig.bool_new`). The function should raise a :exc:`ConfigValueError` if the validation fails. This function checks the new value when :meth:`LazyConfig.set()` is called. Each LazyConfigOption object has the following read-only attributes: ..attribute:: cls The class of the option's value e.g. `str`, `unicode` or `bool`. Used as setter method when :meth:`LazyConfig.set` (or the ``set()`` method of a derived class) is called. ..attribute:: default The option's default value, may be ``None`` ..attribute:: getter A method's name of :class:`ConfigParser.RawConfigParser` and derived classes, to get a option's value, e.g. ``self.getint``. ..attribute:: validate A method or function to validate the option's new value.Config------The final configuration class of the virtual mail manager...class:: Config (filename) Bases: :class:`LazyConfig`:param filename: absolute path to the configuration file.:type filename::obj:`basestring` ..attribute:: _cfg The configuration ``dict``, containing all configuration sections and options, as described in :attr:`LazyConfig._cfg`. ..method:: check() Checks all section's options for settings w/o a default value.:raise VirtualMailManager.errors.ConfigError: if the check fails ..method:: load() Loads the configuration read-only.:raise VirtualMailManager.errors.ConfigError: if the configuration syntax is invalid ..method:: unicode(section, option) Returns the value of the *option* from *section*, converted to Unicode. This method is intended for the :attr:`LazyConfigOption.getter`.:param section: The name of the configuration section:type section::obj:`basestring`:param option: The name of the configuration option:type option::obj:`basestring`:rtype::obj:`unicode`Exceptions----------..exception:: BadOptionError(msg) Bases: :exc:`ConfigParser.Error` Raised when a option isn't in the format 'section.option'...exception:: ConfigValueError(msg) Bases: :exc:`ConfigParser.Error` Raised when creating or validating of new values fails...exception:: NoDefaultError(section, option) Bases: :exc:`ConfigParser.Error` Raised when the requested option has no default value.