diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_config.rst --- a/doc/source/vmm_config.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,275 +0,0 @@ -: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.