doc/source/vmm_alias.rst
author Pascal Volk <neverseen@users.sourceforge.net>
Fri, 04 Nov 2011 03:25:29 +0000
branchv0.6.x
changeset 448 45c917e6a386
parent 220 8b8d632f0ef3
permissions -rw-r--r--
VMM/cli/subcommands: domainservices: Don't fail when neither a service nor the keyword force was provided.
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.