--- a/doc/api/source/vmm_config.rst Mon Mar 24 19:22:04 2014 +0200
+++ /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 <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.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.