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 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 byLazyConfigOption.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'
orTrue
. For a booleanFalse
, the value must set to'0'
,'off'
,'no'
,'false'
orFalse
.- Parameters
section (
basestring
) – The section’s nameoption (
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 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 combinationvalue (
basestring
) – the new value to be set
- Return type
None
- Raises
ConfigValueError – if a boolean value shout be set (
bool_new()
) and it failsValueError – 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()
.
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 sectionoption (
basestring
) – The name of the configuration option
- Return type
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.