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

New 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])

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