doc/source/vmm_relocated.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:
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     1
:mod:`VirtualMailManager.Relocated` --- Handling of relocated users
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     2
===================================================================
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     3
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     4
.. module:: VirtualMailManager.Relocated
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     5
  :synopsis: Handling of relocated users
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     6
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     7
.. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     8
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
     9
.. toctree::
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    10
   :maxdepth: 2
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    11
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    12
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    13
This module provides the :class:`Relocated` class. The data are read
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    14
from/stored in the ``relocated`` table. An optional lookup table, used
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    15
by Postfix for the "``user has moved to new_location``" reject/bounce message.
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    16
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    17
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    18
Relocated
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    19
---------
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    20
.. class:: Relocated(dbh, address)
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    21
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    22
  Creates a new *Relocated* instance. If the relocated user with the given
215
33f727efa7c4 PEP-8-ified the work of the last days.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 212
diff changeset
    23
  *address* is already stored in the database use :meth:`get_info` to get the
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    24
  destination address of the relocated user. To set or update the destination
215
33f727efa7c4 PEP-8-ified the work of the last days.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 212
diff changeset
    25
  of the relocated user use :meth:`set_destination`. Use :meth:`delete` in
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    26
  order to delete the relocated user from the database.
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    27
  
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    28
  :param dbh: a database connection
220
8b8d632f0ef3 doc: Added the alias documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 216
diff changeset
    29
  :type dbh: :class:`pyPgSQL.PgSQL.Connection`
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    30
  :param address: the e-mail address of the relocated user.
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    31
  :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress`
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    32
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    33
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    34
  .. method:: delete()
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    35
  
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    36
    :rtype: :obj:`None`
216
0c8c053b451c Moved VirtualMailManager/Exceptions to VirtualMailManager/errors.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 215
diff changeset
    37
    :raise VirtualMailManager.errors.RelocatedError: if the relocated user
0c8c053b451c Moved VirtualMailManager/Exceptions to VirtualMailManager/errors.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 215
diff changeset
    38
      doesn't exist.
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    39
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    40
    Deletes the relocated user from the database.
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    41
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    42
215
33f727efa7c4 PEP-8-ified the work of the last days.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 212
diff changeset
    43
  .. method:: get_info()
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    44
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    45
    :rtype: :class:`VirtualMailManager.EmailAddress.EmailAddress`
216
0c8c053b451c Moved VirtualMailManager/Exceptions to VirtualMailManager/errors.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 215
diff changeset
    46
    :raise VirtualMailManager.errors.RelocatedError: if the relocated user
0c8c053b451c Moved VirtualMailManager/Exceptions to VirtualMailManager/errors.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 215
diff changeset
    47
      doesn't exist.
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    48
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    49
    Returns the destination e-mail address of the relocated user.
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    50
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    51
215
33f727efa7c4 PEP-8-ified the work of the last days.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 212
diff changeset
    52
  .. method:: set_destination(destination)
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    53
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    54
    :param destination: the new address where the relocated user has moved to
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    55
    :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress`
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    56
    :rtype: :obj:`None`
216
0c8c053b451c Moved VirtualMailManager/Exceptions to VirtualMailManager/errors.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 215
diff changeset
    57
    :raise VirtualMailManager.errors.RelocatedError: if the *destination*
0c8c053b451c Moved VirtualMailManager/Exceptions to VirtualMailManager/errors.
Pascal Volk <neverseen@users.sourceforge.net>
parents: 215
diff changeset
    58
      address is already saved or is the same as the relocated user's address.
212
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    59
77ac6f572855 doc: extended documentation.
Pascal Volk <neverseen@users.sourceforge.net>
parents:
diff changeset
    60
    Sets or updates the *destination* address of the relocated user.