doc/source/vmm_config.rst
author martin f. krafft <madduck@madduck.net>
Sat, 14 Apr 2012 12:37:08 +0200
branchv0.6.x
changeset 534 6a27c7529cd7
parent 216 0c8c053b451c
permissions -rw-r--r--
Change 'force' argument to reset user records for tid/ssid/qid If domain{quotalimit,transport,serviceset} are run with 'force' and settings are inheritable from the domain, then rather than to copy the ID to the user table, the affected field in the user records should be set to NULL so that the domain default is used.

: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.