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 bools

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 tuples 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:

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:

clstype

The class/type of the option’s value.

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

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