--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/source/vmm_config.rst Mon Feb 22 10:20:46 2010 +0000
@@ -0,0 +1,275 @@
+:mod:`VirtualMailManager.Config` --- Simplified configuration access
+======================================================================
+
+.. module:: VirtualMailManager.Config
+ :synopsis: Simplified configuration access
+
+.. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
+
+.. toctree::
+ :maxdepth: 2
+
+
+This module provides a few classes for simplified configuration handling
+and the validation of the setting's *type* and *value*.
+
+:class:`LazyConfig` is derived from Python's
+:class:`ConfigParser.RawConfigParser`. It doesn't use ``RawConfigParser``'s
+``DEFAULT`` section. All settings and their defaults, if supposed, are
+handled by :class:`LazyConfigOption` objects in the :attr:`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')``.
+
+
+
+LazyConfig
+----------
+.. class:: LazyConfig
+
+ Bases: :class:`ConfigParser.RawConfigParser`
+
+ .. versionadded:: 0.6.0
+
+ .. attribute:: _cfg
+
+ a multi dimensional :class:`dict`, containing *sections* and *options*,
+ represented by :class:`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
+ }
+ }
+
+ ...
+
+
+ .. method:: bool_new(value)
+
+ Converts the string *value* into a `bool` and returns it.
+
+ | ``'1'``, ``'on'``, ``'yes'`` and ``'true'`` will become :const:`True`
+ | ``'0'``, ``'off'``, ``'no'`` and ``'false'`` will become :const:`False`
+
+ :param value: one of the above mentioned strings
+ :type value: :obj:`basestring`
+ :rtype: bool
+ :raise ConfigValueError: for all other values, except ``bool``\ s
+
+ .. method:: dget(option)
+
+ Like :meth:`pget`, but returns the *option*'s default value, from
+ :attr:`_cfg` (defined by :attr:`LazyConfigOption.default`) if the *option*
+ is not configured in a ini-like configuration file.
+
+ :param option: the section.option combination
+ :type option: :obj:`basestring`
+ :raise NoDefaultError: if the *option* couldn't be found in the
+ configuration file and no default value was passed to
+ :class:`LazyConfigOption`'s constructor for the requested *option*.
+
+ .. method:: getboolean(section, option)
+
+ Returns the boolean value of the *option*, in the given *section*.
+
+ For a boolean :const:`True`, the value must be set to ``'1'``, ``'on'``,
+ ``'yes'``, ``'true'`` or :const:`True`. For a boolean :const:`False`, the
+ value must set to ``'0'``, ``'off'``, ``'no'``, ``'false'`` or
+ :const:`False`.
+
+ :param section: The section's name
+ :type section: :obj:`basestring`
+ :param option: The option's name
+ :type option: :obj:`basestring`
+ :rtype: bool
+ :raise ValueError: if the option has an other value than the values
+ mentioned above.
+
+ .. method:: has_option(option)
+
+ Checks if the *option* (section\ **.**\ option) is a known configuration
+ option.
+
+ :param option: The option's name
+ :type option: :obj:`basestring`
+ :rtype: bool
+
+ .. method:: has_section(section)
+
+ Checks if *section* is a known configuration section.
+
+ :param section: The section's name
+ :type section: :obj:`basestring`
+ :rtype: bool
+
+ .. method:: items(section)
+
+ Returns an iterator for ``key, value`` :obj:`tuple`\ s for each option in
+ the given *section*.
+
+ :param section: The section's name
+ :type section: :obj:`basestring`
+ :raise NoSectionError: if the given *section* is not known.
+
+ .. method:: pget(option)
+
+ Polymorphic getter which returns the *option*'s value (by calling
+ :attr:`LazyConfigOption.getter`) with the appropriate type, defined by
+ :attr:`LazyConfigOption.cls`.
+
+ :param option: the section.option combination
+ :type option: :obj:`basestring`
+
+ .. method:: sections()
+
+ Returns an iterator object for all configuration sections from the
+ :attr:`_cfg` dictionary.
+
+ :rtype: :obj:`dictionary-keyiterator`
+
+ .. method:: set(option, value)
+
+ Like :meth:`ConfigParser.RawConfigParser.set`, but converts the *option*'s
+ new *value* (by calling :attr:`LazyConfigOption.cls`) to the appropriate
+ type/class. When the ``LazyConfigOption``'s optional parameter *validate*
+ was not :const:`None`, the new *value* will be also validated.
+
+ :param option: the section.option combination
+ :type option: :obj:`basestring`
+ :param value: the new value to be set
+ :type value: :obj:`basestring`
+ :rtype: :const:`None`
+ :raise ConfigValueError: if a boolean value shout be set (:meth:`bool_new`)
+ and it fails
+ :raise ValueError: if an other setter (:attr:`LazyConfigOption.cls`) or
+ validator (:attr:`LazyConfigOption.validate`) fails.
+ :raise VirtualMailManager.Exceptions.VMMException: if
+ :attr:`LazyConfigOption.validate` is set to
+ :func:`VirtualMailManager.exec_ok` or :func:`VirtualMailManager.is_dir`.
+
+
+LazyConfigOption
+----------------
+LazyConfigOption instances are required by :class:`LazyConfig` instances, and
+instances of classes derived from `LazyConfig`, like the :class:`Config`
+class.
+
+.. class:: LazyConfigOption (cls, default, getter[, validate=None])
+
+ .. versionadded:: 0.6.0
+
+ The constructor's parameters are:
+
+ ``cls`` : :obj:`type`
+ The class/type of the option's value.
+ ``default`` : :obj:`str` or the one defined by ``cls``
+ Default value of the option. Use :const:`None` if the option shouldn't
+ have a default value.
+ ``getter``: :obj:`callable`
+ A method's name of :class:`ConfigParser.RawConfigParser` and derived
+ classes, to get a option's value, e.g. `self.getint`.
+ ``validate`` : :obj:`callable` or :const:`None`
+ :const:`None` or any function, which takes one argument and returns the
+ validated argument with the appropriate type (for example:
+ :meth:`LazyConfig.bool_new`). The function should raise a
+ :exc:`ConfigValueError` if the validation fails. This function checks the
+ new value when :meth:`LazyConfig.set()` is called.
+
+ Each LazyConfigOption object has the following read-only attributes:
+
+ .. attribute:: cls
+
+ The class of the option's value e.g. `str`, `unicode` or `bool`. Used as
+ setter method when :meth:`LazyConfig.set` (or the ``set()`` method of a
+ derived class) is called.
+
+ .. attribute:: default
+
+ The option's default value, may be ``None``
+
+ .. attribute:: getter
+
+ A method's name of :class:`ConfigParser.RawConfigParser` and derived
+ classes, to get a option's value, e.g. ``self.getint``.
+
+ .. attribute:: validate
+
+ A method or function to validate the option's new value.
+
+
+Config
+------
+The final configuration class of the virtual mail manager.
+
+.. class:: Config (filename)
+
+ Bases: :class:`LazyConfig`
+
+ :param filename: absolute path to the configuration file.
+ :type filename: :obj:`basestring`
+
+ .. attribute:: _cfg
+
+ The configuration ``dict``, containing all configuration sections and
+ options, as described in :attr:`LazyConfig._cfg`.
+
+ .. method:: check()
+
+ Checks all section's options for settings w/o a default value.
+
+ :raise VirtualMailManager.Exceptions.VMMConfigException: if the check fails
+
+ .. method:: load()
+
+ Loads the configuration read-only.
+
+ :raise VirtualMailManager.Exceptions.VMMConfigException: if the
+ configuration syntax is invalid
+
+ .. method:: unicode(section, option)
+
+ Returns the value of the *option* from *section*, converted to Unicode.
+ This method is intended for the :attr:`LazyConfigOption.getter`.
+
+ :param section: The name of the configuration section
+ :type section: :obj:`basestring`
+ :param option: The name of the configuration option
+ :type option: :obj:`basestring`
+ :rtype: :obj:`unicode`
+
+
+Exceptions
+----------
+
+.. exception:: BadOptionError (msg)
+
+ Bases: :exc:`ConfigParser.Error`
+
+ Raised when a option isn't in the format 'section.option'.
+
+.. exception:: ConfigValueError (msg)
+
+ Bases: :exc:`ConfigParser.Error`
+
+ Raised when creating or validating of new values fails.
+
+.. exception:: NoDefaultError (section, option)
+
+ Bases: :exc:`ConfigParser.Error`
+
+ Raised when the requested option has no default value.