doc/source/vmm_alias.rst
author martin f. krafft <madduck@madduck.net>
Sat, 14 Apr 2012 12:37:08 +0200
branchv0.6.x
changeset 534 6a27c7529cd7
parent 220 8b8d632f0ef3
permissions -rw-r--r--
Change 'force' argument to reset user records for tid/ssid/qid If domain{quotalimit,transport,serviceset} are run with 'force' and settings are inheritable from the domain, then rather than to copy the ID to the user table, the affected field in the user records should be set to NULL so that the domain default is used.
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.