# 2. `VirtualMailManager.Config` — Simplified configuration access

This module provides a few classes for simplified configuration handling and the validation of the setting’s type and value.

`LazyConfig` is derived from Python’s `ConfigParser.RawConfigParser`. It doesn’t use `RawConfigParser`’s `DEFAULT` section. All settings and their defaults, if supposed, are handled by `LazyConfigOption` objects in the `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')`.

## 2.1. LazyConfig

class VirtualMailManager.Config.LazyConfig

  Bases: `ConfigParser.RawConfigParser`

  Added in version 0.6.0.

  _cfg

    a multi dimensional `dict`, containing sections and options, represented by `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
                    }
                }

            ...

  bool_new(value)

    Converts the string value into a bool and returns it.

    `'1'`, `'on'`, `'yes'` and `'true'` will become `True`
    `'0'`, `'off'`, `'no'` and `'false'` will become `False`
    Parameters:

      value (`basestring`) – one of the above mentioned strings

    Return type:

      bool

    Raises:

      ConfigValueError – for all other values, except `bool`s

  dget(option)

    Like `pget()`, but returns the option’s default value, from `_cfg` (defined by `LazyConfigOption.default`) if the option is not configured in a ini-like configuration file.

    Parameters:

      option (`basestring`) – the section.option combination

    Raises:

      NoDefaultError – if the option couldn’t be found in the configuration file and no default value was passed to `LazyConfigOption`’s constructor for the requested option.

  getboolean(section, option)

    Returns the boolean value of the option, in the given section.

    For a boolean `True`, the value must be set to `'1'`, `'on'`, `'yes'`, `'true'` or `True`. For a boolean `False`, the value must set to `'0'`, `'off'`, `'no'`, `'false'` or `False`.

    Parameters:

      - section (`basestring`) – The section’s name

      - option (`basestring`) – The option’s name

    Return type:

      bool

    Raises:

      ValueError – if the option has an other value than the values mentioned above.

  has_option(option)

    Checks if the option (section.option) is a known configuration option.

    Parameters:

      option (`basestring`) – The option’s name

    Return type:

      bool

  has_section(section)

    Checks if section is a known configuration section.

    Parameters:

      section (`basestring`) – The section’s name

    Return type:

      bool

  items(section)

    Returns an iterator for `key, value` `tuple`s for each option in the given section.

    Parameters:

      section (`basestring`) – The section’s name

    Raises:

      NoSectionError – if the given section is not known.

  pget(option)

    Polymorphic getter which returns the option’s value (by calling `LazyConfigOption.getter`) with the appropriate type, defined by `LazyConfigOption.cls`.

    Parameters:

      option (`basestring`) – the section.option combination

  sections()

    Returns an iterator object for all configuration sections from the `_cfg` dictionary.

    Return type:

      `dictionary-keyiterator`

  set(option, value)

    Like `ConfigParser.RawConfigParser.set()`, but converts the option’s new value (by calling `LazyConfigOption.cls`) to the appropriate type/class. When the `LazyConfigOption`’s optional parameter validate was not `None`, the new value will be also validated.

    Parameters:

      - option (`basestring`) – the section.option combination

      - value (`basestring`) – the new value to be set

    Return type:

      `None`

    Raises:

      - ConfigValueError – if a boolean value shout be set (`bool_new()`) and it fails

      - ValueError – if an other setter (`LazyConfigOption.cls`) or validator (`LazyConfigOption.validate`) fails.

      - VirtualMailManager.errors.VMMError – if `LazyConfigOption.validate` is set to `VirtualMailManager.exec_ok()` or `VirtualMailManager.is_dir()`.

## 2.2. LazyConfigOption

LazyConfigOption instances are required by `LazyConfig` instances, and instances of classes derived from LazyConfig, like the `Config` class.

class VirtualMailManager.Config.LazyConfigOption(cls, default, getter[, validate=None])

  Added in version 0.6.0.

  The constructor’s parameters are:

  `cls` `type`

    The class/type of the option’s value.

  `default` `str` or the one defined by `cls`

    Default value of the option. Use `None` if the option shouldn’t have a default value.

  `getter`: `callable`

    A method’s name of `ConfigParser.RawConfigParser` and derived classes, to get a option’s value, e.g. self.getint.

  `validate` `callable` or `None`

    `None` or any function, which takes one argument and returns the validated argument with the appropriate type (for example: `LazyConfig.bool_new()`). The function should raise a `ConfigValueError` if the validation fails. This function checks the new value when `LazyConfig.set()` is called.

  Each LazyConfigOption object has the following read-only attributes:

  cls

    The class of the option’s value e.g. str, unicode or bool. Used as setter method when `LazyConfig.set()` (or the `set()` method of a derived class) is called.

  default

    The option’s default value, may be `None`

  getter

    A method’s name of `ConfigParser.RawConfigParser` and derived classes, to get a option’s value, e.g. `self.getint`.

  validate

    A method or function to validate the option’s new value.

## 2.3. Config

The final configuration class of the virtual mail manager.

class VirtualMailManager.Config.Config(filename)

  Bases: `LazyConfig`

  Parameters:

    filename (`basestring`) – absolute path to the configuration file.

  _cfg

    The configuration `dict`, containing all configuration sections and options, as described in `LazyConfig._cfg`.

  check()

    Checks all section’s options for settings w/o a default value.

    Raises:

      VirtualMailManager.errors.ConfigError – if the check fails

  load()

    Loads the configuration read-only.

    Raises:

      VirtualMailManager.errors.ConfigError – if the configuration syntax is invalid

  unicode(section, option)

    Returns the value of the option from section, converted to Unicode. This method is intended for the `LazyConfigOption.getter`.

    Parameters:

      - section (`basestring`) – The name of the configuration section

      - option (`basestring`) – The name of the configuration option

    Return type:

      `unicode`

## 2.4. Exceptions

exception VirtualMailManager.Config.BadOptionError(msg)

  Bases: `ConfigParser.Error`

  Raised when a option isn’t in the format ‘section.option’.

exception VirtualMailManager.Config.ConfigValueError(msg)

  Bases: `ConfigParser.Error`

  Raised when creating or validating of new values fails.

exception VirtualMailManager.Config.NoDefaultError(section, option)

  Bases: `ConfigParser.Error`

  Raised when the requested option has no default value.