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 byLazyConfigOption
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 becomeTrue
'0'
,'off'
,'no'
and'false'
will becomeFalse
Parameters: value ( basestring
) – one of the above mentioned stringsReturn 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 byLazyConfigOption.default
) if the option is not configured in a ini-like configuration file.Parameters: option ( basestring
) – the section.option combinationRaises: 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'
orTrue
. For a booleanFalse
, the value must set to'0'
,'off'
,'no'
,'false'
orFalse
.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.
- section (
-
has_option
(option)¶ Checks if the option (section.option) is a known configuration option.
Parameters: option ( basestring
) – The option’s nameReturn type: bool
-
has_section
(section)¶ Checks if section is a known configuration section.
Parameters: section ( basestring
) – The section’s nameReturn 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 nameRaises: 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 byLazyConfigOption.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 callingLazyConfigOption.cls
) to the appropriate type/class. When theLazyConfigOption
‘s optional parameter validate was notNone
, 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 toVirtualMailManager.exec_ok()
orVirtualMailManager.is_dir()
.
- option (
-
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
: - The class/type of the option’s value.
default
: - 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
: 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 aConfigValueError
if the validation fails. This function checks the new value whenLazyConfig.set()
is called.
type
str
or the one defined bycls
callable
orNone
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 theset()
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 inLazyConfig._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: - section (
-
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.