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
:type
- The class/type of the option’s value.
default
:str
or the one defined bycls
- 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
orNone
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.
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.