doc/source/vmm_alias.rst
author martin f. krafft <madduck@madduck.net>
Sun, 15 Apr 2012 17:51:00 +0200
branchv0.6.x
changeset 550 867d950ce7b7
parent 220 8b8d632f0ef3
permissions -rw-r--r--
Fix transport_maps function for non-existent domains The postfix_transport_maps function had a bug causing 2012-04-15 17:40:22 CEST LOG: statement: SELECT transport FROM postfix_transport_map('logcheck', 'domine.madduck.net'); 2012-04-15 17:40:22 CEST ERROR: query returned no rows when the domain was not in the database. This would make did be NULL and make the query fail. This patch moves the tid query until after a check for did. If the latter is NULL, the function RETURNs (rather than fails).

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