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.