diff -r c0e1fb1b0145 -r a4aead244f75 doc/source/vmm_config.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/source/vmm_config.rst Thu Jun 28 19:26:50 2012 +0000 @@ -0,0 +1,275 @@ +:mod:`VirtualMailManager.Config` --- Simplified configuration access +====================================================================== + +.. module:: VirtualMailManager.Config + :synopsis: Simplified configuration access + +.. moduleauthor:: Pascal Volk + +.. 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.errors.VMMError: 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.errors.ConfigError: if the check fails + + .. method:: load() + + Loads the configuration read-only. + + :raise VirtualMailManager.errors.ConfigError: 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.