doc/source/vmm_alias.rst
author martin f. krafft <madduck@madduck.net>
Wed, 11 Apr 2012 16:23:27 +0200
branchv0.6.x
changeset 518 5ec2068d02af
parent 220 8b8d632f0ef3
permissions -rw-r--r--
Enable interpolation of alias destinations This patch modifies the virtual_alias_maps function so that the destination address is parsed for the place holders %n, %d and %=, which are replaced with the localpart, the domain or the full address with '@' replaced by '=' of the queried key. In combination with alias domains, this allows for domain-specific recipients. E.g. given example.org and its alias domain example.com, defining an alias postmaster@example.org → postmaster+%d@example.org will cause mail to postmaster@example.*com* to go to postmaster+example.*com*@example.org.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
220
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     1
:mod:`VirtualMailManager.Alias` --- Handling of alias e-mail addresses
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     2
======================================================================
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     3
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     4
.. module:: VirtualMailManager.Alias
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     5
  :synopsis: Handling of alias e-mail addresses
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     6
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     7
.. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     8
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     9
.. toctree::
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    10
   :maxdepth: 2
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    11
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    12
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    13
This module provides the :class:`Alias` class. The data are read from/stored
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    14
in the ``alias`` table. This table is used by Postfix to rewrite recipient
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    15
addresses.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    16
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    17
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    18
Alias
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    19
---------
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    20
.. class:: Alias(dbh, address)
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    21
  
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    22
  Creates a new *Alias* instance. Alias instances provides the :func:`__len__`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    23
  method. So the existence of an alias in the database can be tested with a
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    24
  simple if condition.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    25
  
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    26
  :param dbh: a database connection
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    27
  :type dbh: :class:`pyPgSQL.PgSQL.Connection`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    28
  :param address: the alias e-mail address.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    29
  :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    30
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    31
  .. method:: add_destinations(destinations, expansion_limit [, warnings=None])
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    32
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    33
    Adds the *destinations* to the destinations of the alias. This method
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    34
    returns a ``set`` of all addresses which successfully were stored into the
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    35
    database.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    36
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    37
    If one of the e-mail addresses in *destinations* is the same as the alias
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    38
    address, it will be silently discarded. Destination addresses, that are
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    39
    already assigned to the alias, will be also ignored.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    40
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    41
    When the optional *warnings* list is given, all ignored addresses will be
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    42
    appended to it.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    43
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    44
    :param destinations: The destination addresses of the alias
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    45
    :type destinations: :obj:`list` of
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    46
      :class:`VirtualMailManager.EmailAddress.EmailAddress` instances
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    47
    :param expansion_limit: The maximal number of destinations (see also:
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    48
      `virtual_alias_expansion_limit
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    49
      <http://www.postfix.org/postconf.5.html#virtual_alias_expansion_limit>`_)
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    50
    :type expansion_limit: :obj:`int`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    51
    :param warnings: A optional list, to record all ignored addresses
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    52
    :type warnings: :obj:`list`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    53
    :rtype: :obj:`set`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    54
    :raise VirtualMailManager.errors.AliasError: if the additional
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    55
      *destinations* will exceed the *expansion_limit* or if the alias
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    56
      already exceeds its *expansion_limit*.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    57
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    58
    .. seealso:: :mod:`VirtualMailManager.ext.postconf` -- to read actual
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    59
      values of Postfix configuration parameters.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    60
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    61
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    62
  .. method:: del_destination(destination)
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    63
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    64
    Deletes the given *destination* address from the alias.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    65
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    66
    :param destination: a destination address of the alias
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    67
    :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    68
    :rtype: :obj:`None`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    69
    :raise VirtualMailManager.errors.AliasError: if the destination wasn't
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    70
      assigned to the alias or the alias doesn't exist.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    71
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    72
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    73
  .. method:: delete()
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    74
    
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    75
    Deletes the alias with all its destinations.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    76
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    77
    :rtype: :obj:`None`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    78
    :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    79
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    80
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    81
  .. method:: get_destinations()
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    82
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    83
    Returns an iterator for all destinations (``EmailAddress`` instances) of
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    84
    the alias.
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    85
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    86
    :rtype: :obj:`listiterator`
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    87
    :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.