+
−:mod:`VirtualMailManager.Alias` --- Handling of alias e-mail addresses
+
−======================================================================
+
−
+
−.. module:: VirtualMailManager.Alias
+
−  :synopsis: Handling of alias e-mail addresses
+
−
+
−.. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
+
−
+
−.. toctree::
+
−   :maxdepth: 2
+
−
+
−
+
−This module provides the :class:`Alias` class. The data are read from/stored
+
−in the ``alias`` table. This table is used by Postfix to rewrite recipient
+
−addresses.
+
−
+
−
+
−Alias
+
−---------
+
−.. class:: Alias(dbh, address)
+
−  
+
−  Creates a new *Alias* instance. Alias instances provides the :func:`__len__`
+
−  method. So the existence of an alias in the database can be tested with a
+
−  simple if condition.
+
−  
+
−  :param dbh: a database connection
+
−  :type dbh: :class:`pyPgSQL.PgSQL.Connection`
+
−  :param address: the alias e-mail address.
+
−  :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress`
+
−
+
−  .. method:: add_destinations(destinations, expansion_limit [, warnings=None])
+
−
+
−    Adds the *destinations* to the destinations of the alias. This method
+
−    returns a ``set`` of all addresses which successfully were stored into the
+
−    database.
+
−
+
−    If one of the e-mail addresses in *destinations* is the same as the alias
+
−    address, it will be silently discarded. Destination addresses, that are
+
−    already assigned to the alias, will be also ignored.
+
−
+
−    When the optional *warnings* list is given, all ignored addresses will be
+
−    appended to it.
+
−
+
−    :param destinations: The destination addresses of the alias
+
−    :type destinations: :obj:`list` of
+
−      :class:`VirtualMailManager.EmailAddress.EmailAddress` instances
+
−    :param expansion_limit: The maximal number of destinations (see also:
+
−      `virtual_alias_expansion_limit
+
−      <http://www.postfix.org/postconf.5.html#virtual_alias_expansion_limit>`_)
+
−    :type expansion_limit: :obj:`int`
+
−    :param warnings: A optional list, to record all ignored addresses
+
−    :type warnings: :obj:`list`
+
−    :rtype: :obj:`set`
+
−    :raise VirtualMailManager.errors.AliasError: if the additional
+
−      *destinations* will exceed the *expansion_limit* or if the alias
+
−      already exceeds its *expansion_limit*.
+
−
+
−    .. seealso:: :mod:`VirtualMailManager.ext.postconf` -- to read actual
+
−      values of Postfix configuration parameters.
+
−
+
−
+
−  .. method:: del_destination(destination)
+
−
+
−    Deletes the given *destination* address from the alias.
+
−
+
−    :param destination: a destination address of the alias
+
−    :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress`
+
−    :rtype: :obj:`None`
+
−    :raise VirtualMailManager.errors.AliasError: if the destination wasn't
+
−      assigned to the alias or the alias doesn't exist.
+
−
+
−
+
−  .. method:: delete()
+
−    
+
−    Deletes the alias with all its destinations.
+
−
+
−    :rtype: :obj:`None`
+
−    :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.
+
−
+
−
+
−  .. method:: get_destinations()
+
−
+
−    Returns an iterator for all destinations (``EmailAddress`` instances) of
+
−    the alias.
+
−
+
−    :rtype: :obj:`listiterator`
+
−    :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.