doc/source/vmm_alias.rst
branchv0.6.x
changeset 220 8b8d632f0ef3
equal deleted inserted replaced
219:0b6ce895e1dc 220:8b8d632f0ef3
       
     1 :mod:`VirtualMailManager.Alias` --- Handling of alias e-mail addresses
       
     2 ======================================================================
       
     3 
       
     4 .. module:: VirtualMailManager.Alias
       
     5   :synopsis: Handling of alias e-mail addresses
       
     6 
       
     7 .. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
       
     8 
       
     9 .. toctree::
       
    10    :maxdepth: 2
       
    11 
       
    12 
       
    13 This module provides the :class:`Alias` class. The data are read from/stored
       
    14 in the ``alias`` table. This table is used by Postfix to rewrite recipient
       
    15 addresses.
       
    16 
       
    17 
       
    18 Alias
       
    19 ---------
       
    20 .. class:: Alias(dbh, address)
       
    21   
       
    22   Creates a new *Alias* instance. Alias instances provides the :func:`__len__`
       
    23   method. So the existence of an alias in the database can be tested with a
       
    24   simple if condition.
       
    25   
       
    26   :param dbh: a database connection
       
    27   :type dbh: :class:`pyPgSQL.PgSQL.Connection`
       
    28   :param address: the alias e-mail address.
       
    29   :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress`
       
    30 
       
    31   .. method:: add_destinations(destinations, expansion_limit [, warnings=None])
       
    32 
       
    33     Adds the *destinations* to the destinations of the alias. This method
       
    34     returns a ``set`` of all addresses which successfully were stored into the
       
    35     database.
       
    36 
       
    37     If one of the e-mail addresses in *destinations* is the same as the alias
       
    38     address, it will be silently discarded. Destination addresses, that are
       
    39     already assigned to the alias, will be also ignored.
       
    40 
       
    41     When the optional *warnings* list is given, all ignored addresses will be
       
    42     appended to it.
       
    43 
       
    44     :param destinations: The destination addresses of the alias
       
    45     :type destinations: :obj:`list` of
       
    46       :class:`VirtualMailManager.EmailAddress.EmailAddress` instances
       
    47     :param expansion_limit: The maximal number of destinations (see also:
       
    48       `virtual_alias_expansion_limit
       
    49       <http://www.postfix.org/postconf.5.html#virtual_alias_expansion_limit>`_)
       
    50     :type expansion_limit: :obj:`int`
       
    51     :param warnings: A optional list, to record all ignored addresses
       
    52     :type warnings: :obj:`list`
       
    53     :rtype: :obj:`set`
       
    54     :raise VirtualMailManager.errors.AliasError: if the additional
       
    55       *destinations* will exceed the *expansion_limit* or if the alias
       
    56       already exceeds its *expansion_limit*.
       
    57 
       
    58     .. seealso:: :mod:`VirtualMailManager.ext.postconf` -- to read actual
       
    59       values of Postfix configuration parameters.
       
    60 
       
    61 
       
    62   .. method:: del_destination(destination)
       
    63 
       
    64     Deletes the given *destination* address from the alias.
       
    65 
       
    66     :param destination: a destination address of the alias
       
    67     :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress`
       
    68     :rtype: :obj:`None`
       
    69     :raise VirtualMailManager.errors.AliasError: if the destination wasn't
       
    70       assigned to the alias or the alias doesn't exist.
       
    71 
       
    72 
       
    73   .. method:: delete()
       
    74     
       
    75     Deletes the alias with all its destinations.
       
    76 
       
    77     :rtype: :obj:`None`
       
    78     :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.
       
    79 
       
    80 
       
    81   .. method:: get_destinations()
       
    82 
       
    83     Returns an iterator for all destinations (``EmailAddress`` instances) of
       
    84     the alias.
       
    85 
       
    86     :rtype: :obj:`listiterator`
       
    87     :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.