:mod:`VirtualMailManager.Config` ---  Simplified configuration access

======================================================================

.. module:: VirtualMailManager.Config

  :synopsis: Simplified configuration access

.. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>

.. toctree::

   :maxdepth: 2

This module provides a few classes for simplified configuration handling

and 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, are

handled by :class:`LazyConfigOption` objects in the :attr:`LazyConfig._cfg`

*dict*.

``LazyConfig``'s setters and getters for options are taking a single string

for 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, and

instances 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.