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