doc/api/source/vmm_config.rst
changeset 578 20141b967c0b
parent 216 0c8c053b451c
equal deleted inserted replaced
577:4f9079dd4b65 578:20141b967c0b
       
     1 :mod:`VirtualMailManager.Config` ---  Simplified configuration access
       
     2 ======================================================================
       
     3 
       
     4 .. module:: VirtualMailManager.Config
       
     5   :synopsis: Simplified configuration access
       
     6 
       
     7 .. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
       
     8 
       
     9 .. toctree::
       
    10    :maxdepth: 2
       
    11 
       
    12 
       
    13 This module provides a few classes for simplified configuration handling
       
    14 and the validation of the setting's  *type* and *value*.
       
    15 
       
    16 :class:`LazyConfig` is derived from Python's
       
    17 :class:`ConfigParser.RawConfigParser`. It doesn't use ``RawConfigParser``'s
       
    18 ``DEFAULT`` section. All settings and their defaults, if supposed, are
       
    19 handled by :class:`LazyConfigOption` objects in the :attr:`LazyConfig._cfg`
       
    20 *dict*.
       
    21 
       
    22 ``LazyConfig``'s setters and getters for options are taking a single string
       
    23 for the *section* and *option* argument, e.g. ``config.pget('database.user')``
       
    24 instead of ``config.get('database', 'user')``.
       
    25 
       
    26 
       
    27 
       
    28 LazyConfig
       
    29 ----------
       
    30 .. class:: LazyConfig
       
    31 
       
    32   Bases: :class:`ConfigParser.RawConfigParser`
       
    33 
       
    34   .. versionadded:: 0.6.0
       
    35 
       
    36   .. attribute:: _cfg
       
    37 
       
    38     a multi dimensional :class:`dict`, containing *sections* and *options*,
       
    39     represented by :class:`LazyConfigOption` objects.
       
    40 
       
    41     For example::
       
    42 
       
    43       from VirtualMailManager.Config import LazyConfig, LazyConfigOption
       
    44 
       
    45       class FooConfig(LazyConfig):
       
    46           def __init__(self, ...):
       
    47               LazyConfig.__init__(self)
       
    48               ...
       
    49               LCO = LazyConfigOption
       
    50               self._cfg = {
       
    51                   'database': {# section database:
       
    52                       'host': LCO(str, '::1', self.get), # options of the
       
    53                       'name': LCO(str, 'dbx', self.get), # database section.
       
    54                       'pass': LCO(str, None, self.get),  # No defaults for the
       
    55                       'user': LCO(str, None, self.get),  # user and pass options
       
    56                   }
       
    57               }
       
    58 
       
    59           ...
       
    60 
       
    61 
       
    62   .. method:: bool_new(value)
       
    63 
       
    64     Converts the string *value* into a `bool` and returns it.
       
    65 
       
    66     | ``'1'``, ``'on'``, ``'yes'`` and ``'true'`` will become :const:`True`
       
    67     | ``'0'``, ``'off'``, ``'no'`` and ``'false'`` will become :const:`False`
       
    68 
       
    69     :param value: one of the above mentioned strings
       
    70     :type value: :obj:`basestring`
       
    71     :rtype: bool
       
    72     :raise ConfigValueError: for all other values, except ``bool``\ s
       
    73 
       
    74   .. method:: dget(option)
       
    75 
       
    76     Like :meth:`pget`, but returns the *option*'s default value, from
       
    77     :attr:`_cfg` (defined by :attr:`LazyConfigOption.default`) if the *option*
       
    78     is not configured in a ini-like configuration file.
       
    79 
       
    80     :param option: the section.option combination
       
    81     :type option: :obj:`basestring`
       
    82     :raise NoDefaultError: if the *option* couldn't be found in the
       
    83       configuration file and no default value was passed to
       
    84       :class:`LazyConfigOption`'s constructor for the requested *option*.
       
    85 
       
    86   .. method:: getboolean(section, option)
       
    87 
       
    88     Returns the boolean value of the *option*, in the given *section*.
       
    89 
       
    90     For a boolean :const:`True`, the value must be set to ``'1'``, ``'on'``,
       
    91     ``'yes'``, ``'true'`` or :const:`True`. For a boolean :const:`False`, the
       
    92     value must set to ``'0'``, ``'off'``, ``'no'``, ``'false'`` or
       
    93     :const:`False`.
       
    94 
       
    95     :param section: The section's name
       
    96     :type section: :obj:`basestring`
       
    97     :param option: The option's name
       
    98     :type option: :obj:`basestring`
       
    99     :rtype: bool
       
   100     :raise ValueError: if the option has an other value than the values
       
   101       mentioned above.
       
   102 
       
   103   .. method:: has_option(option)
       
   104 
       
   105     Checks if the *option* (section\ **.**\ option) is a known configuration
       
   106     option.
       
   107 
       
   108     :param option: The option's name
       
   109     :type option: :obj:`basestring`
       
   110     :rtype: bool
       
   111 
       
   112   .. method:: has_section(section)
       
   113 
       
   114     Checks if *section* is a known configuration section.
       
   115 
       
   116     :param section: The section's name
       
   117     :type section: :obj:`basestring`
       
   118     :rtype: bool
       
   119 
       
   120   .. method:: items(section)
       
   121 
       
   122     Returns an iterator for ``key, value`` :obj:`tuple`\ s for each option in
       
   123     the given *section*.
       
   124 
       
   125     :param section: The section's name
       
   126     :type section: :obj:`basestring`
       
   127     :raise NoSectionError: if the given *section* is not known.
       
   128 
       
   129   .. method:: pget(option)
       
   130 
       
   131     Polymorphic getter which returns the *option*'s value (by calling
       
   132     :attr:`LazyConfigOption.getter`) with the appropriate type, defined by
       
   133     :attr:`LazyConfigOption.cls`.
       
   134 
       
   135     :param option: the section.option combination
       
   136     :type option: :obj:`basestring`
       
   137 
       
   138   .. method:: sections()
       
   139 
       
   140     Returns an iterator object for all configuration sections from the
       
   141     :attr:`_cfg` dictionary.
       
   142 
       
   143     :rtype: :obj:`dictionary-keyiterator`
       
   144 
       
   145   .. method:: set(option, value)
       
   146 
       
   147     Like :meth:`ConfigParser.RawConfigParser.set`, but converts the *option*'s
       
   148     new *value* (by calling :attr:`LazyConfigOption.cls`) to the appropriate
       
   149     type/class. When the ``LazyConfigOption``'s optional parameter *validate*
       
   150     was not :const:`None`, the new *value* will be also validated.
       
   151 
       
   152     :param option: the section.option combination
       
   153     :type option: :obj:`basestring`
       
   154     :param value: the new value to be set
       
   155     :type value: :obj:`basestring`
       
   156     :rtype: :const:`None`
       
   157     :raise ConfigValueError: if a boolean value shout be set (:meth:`bool_new`)
       
   158       and it fails
       
   159     :raise ValueError: if an other setter (:attr:`LazyConfigOption.cls`) or
       
   160       validator (:attr:`LazyConfigOption.validate`) fails.
       
   161     :raise VirtualMailManager.errors.VMMError: if
       
   162       :attr:`LazyConfigOption.validate` is set to
       
   163       :func:`VirtualMailManager.exec_ok` or :func:`VirtualMailManager.is_dir`.
       
   164 
       
   165 
       
   166 LazyConfigOption
       
   167 ----------------
       
   168 LazyConfigOption instances are required by :class:`LazyConfig` instances, and
       
   169 instances of classes derived from `LazyConfig`, like the :class:`Config`
       
   170 class.
       
   171 
       
   172 .. class:: LazyConfigOption (cls, default, getter[, validate=None])
       
   173 
       
   174   .. versionadded:: 0.6.0
       
   175 
       
   176   The constructor's parameters are:
       
   177 
       
   178   ``cls`` : :obj:`type`
       
   179     The class/type of the option's value.
       
   180   ``default`` : :obj:`str` or the one defined by ``cls``
       
   181     Default value of the option. Use :const:`None` if the option shouldn't
       
   182     have a default value.
       
   183   ``getter``: :obj:`callable`
       
   184     A method's name of :class:`ConfigParser.RawConfigParser` and derived
       
   185     classes, to get a option's value, e.g. `self.getint`.
       
   186   ``validate`` : :obj:`callable` or :const:`None`
       
   187     :const:`None` or any function, which takes one argument and returns the
       
   188     validated argument with the appropriate type (for example:
       
   189     :meth:`LazyConfig.bool_new`). The function should raise a 
       
   190     :exc:`ConfigValueError` if the validation fails. This function checks the
       
   191     new value when :meth:`LazyConfig.set()` is called.
       
   192 
       
   193   Each LazyConfigOption object has the following read-only attributes:
       
   194 
       
   195   .. attribute:: cls
       
   196 
       
   197     The class of the option's value e.g. `str`, `unicode` or `bool`. Used as
       
   198     setter method when :meth:`LazyConfig.set` (or the ``set()`` method of a
       
   199     derived class) is called.
       
   200 
       
   201   .. attribute:: default
       
   202 
       
   203     The option's default value, may be ``None``
       
   204 
       
   205   .. attribute:: getter
       
   206 
       
   207     A method's name of :class:`ConfigParser.RawConfigParser` and derived
       
   208     classes, to get a option's value, e.g. ``self.getint``.
       
   209 
       
   210   .. attribute:: validate
       
   211 
       
   212     A method or function to validate the option's new value.
       
   213 
       
   214 
       
   215 Config
       
   216 ------
       
   217 The final configuration class of the virtual mail manager.
       
   218 
       
   219 .. class:: Config (filename)
       
   220 
       
   221   Bases: :class:`LazyConfig`
       
   222 
       
   223   :param filename: absolute path to the configuration file.
       
   224   :type filename: :obj:`basestring`
       
   225 
       
   226   .. attribute:: _cfg
       
   227 
       
   228     The configuration ``dict``, containing all configuration sections and
       
   229     options, as described in :attr:`LazyConfig._cfg`.
       
   230 
       
   231   .. method:: check()
       
   232 
       
   233     Checks all section's options for settings w/o a default value.
       
   234 
       
   235     :raise VirtualMailManager.errors.ConfigError: if the check fails
       
   236 
       
   237   .. method:: load()
       
   238 
       
   239     Loads the configuration read-only.
       
   240 
       
   241     :raise VirtualMailManager.errors.ConfigError: if the
       
   242       configuration syntax is invalid
       
   243 
       
   244   .. method:: unicode(section, option)
       
   245 
       
   246     Returns the value of the *option* from *section*, converted to Unicode.
       
   247     This method is intended for the :attr:`LazyConfigOption.getter`.
       
   248 
       
   249     :param section: The name of the configuration section
       
   250     :type section: :obj:`basestring`
       
   251     :param option: The name of the configuration option
       
   252     :type option: :obj:`basestring`
       
   253     :rtype: :obj:`unicode`
       
   254 
       
   255 
       
   256 Exceptions
       
   257 ----------
       
   258 
       
   259 .. exception:: BadOptionError(msg)
       
   260 
       
   261   Bases: :exc:`ConfigParser.Error`
       
   262 
       
   263   Raised when a option isn't in the format 'section.option'.
       
   264 
       
   265 .. exception:: ConfigValueError(msg)
       
   266 
       
   267   Bases: :exc:`ConfigParser.Error`
       
   268 
       
   269   Raised when creating or validating of new values fails.
       
   270 
       
   271 .. exception:: NoDefaultError(section, option)
       
   272 
       
   273   Bases: :exc:`ConfigParser.Error`
       
   274 
       
   275   Raised when the requested option has no default value.