# HG changeset patch
# User Pascal Volk <neverseen@users.sourceforge.net>
# Date 1267304329 0
# Node ID 8b8d632f0ef3f4315601d00b5195cbad3e4b5782
# Parent  0b6ce895e1dc653e752b5ed520f3684b91699add
doc: Added the alias documentation.

diff -r 0b6ce895e1dc -r 8b8d632f0ef3 doc/source/index.rst
--- a/doc/source/index.rst	Sat Feb 27 10:51:04 2010 +0000
+++ b/doc/source/index.rst	Sat Feb 27 20:58:49 2010 +0000
@@ -15,6 +15,7 @@
    vmm.rst
    vmm_config.rst
    vmm_emailaddress.rst
+   vmm_alias.rst
    vmm_relocated.rst
    vmm_errors.rst
    vmm_constants_error.rst
diff -r 0b6ce895e1dc -r 8b8d632f0ef3 doc/source/vmm_alias.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/source/vmm_alias.rst	Sat Feb 27 20:58:49 2010 +0000
@@ -0,0 +1,87 @@
+:mod:`VirtualMailManager.Alias` --- Handling of alias e-mail addresses
+======================================================================
+
+.. module:: VirtualMailManager.Alias
+  :synopsis: Handling of alias e-mail addresses
+
+.. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
+
+.. toctree::
+   :maxdepth: 2
+
+
+This module provides the :class:`Alias` class. The data are read from/stored
+in the ``alias`` table. This table is used by Postfix to rewrite recipient
+addresses.
+
+
+Alias
+---------
+.. class:: Alias(dbh, address)
+  
+  Creates a new *Alias* instance. Alias instances provides the :func:`__len__`
+  method. So the existence of an alias in the database can be tested with a
+  simple if condition.
+  
+  :param dbh: a database connection
+  :type dbh: :class:`pyPgSQL.PgSQL.Connection`
+  :param address: the alias e-mail address.
+  :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress`
+
+  .. method:: add_destinations(destinations, expansion_limit [, warnings=None])
+
+    Adds the *destinations* to the destinations of the alias. This method
+    returns a ``set`` of all addresses which successfully were stored into the
+    database.
+
+    If one of the e-mail addresses in *destinations* is the same as the alias
+    address, it will be silently discarded. Destination addresses, that are
+    already assigned to the alias, will be also ignored.
+
+    When the optional *warnings* list is given, all ignored addresses will be
+    appended to it.
+
+    :param destinations: The destination addresses of the alias
+    :type destinations: :obj:`list` of
+      :class:`VirtualMailManager.EmailAddress.EmailAddress` instances
+    :param expansion_limit: The maximal number of destinations (see also:
+      `virtual_alias_expansion_limit
+      <http://www.postfix.org/postconf.5.html#virtual_alias_expansion_limit>`_)
+    :type expansion_limit: :obj:`int`
+    :param warnings: A optional list, to record all ignored addresses
+    :type warnings: :obj:`list`
+    :rtype: :obj:`set`
+    :raise VirtualMailManager.errors.AliasError: if the additional
+      *destinations* will exceed the *expansion_limit* or if the alias
+      already exceeds its *expansion_limit*.
+
+    .. seealso:: :mod:`VirtualMailManager.ext.postconf` -- to read actual
+      values of Postfix configuration parameters.
+
+
+  .. method:: del_destination(destination)
+
+    Deletes the given *destination* address from the alias.
+
+    :param destination: a destination address of the alias
+    :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress`
+    :rtype: :obj:`None`
+    :raise VirtualMailManager.errors.AliasError: if the destination wasn't
+      assigned to the alias or the alias doesn't exist.
+
+
+  .. method:: delete()
+    
+    Deletes the alias with all its destinations.
+
+    :rtype: :obj:`None`
+    :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.
+
+
+  .. method:: get_destinations()
+
+    Returns an iterator for all destinations (``EmailAddress`` instances) of
+    the alias.
+
+    :rtype: :obj:`listiterator`
+    :raise VirtualMailManager.errors.AliasError: if the alias doesn't exist.
diff -r 0b6ce895e1dc -r 8b8d632f0ef3 doc/source/vmm_constants_error.rst
--- a/doc/source/vmm_constants_error.rst	Sat Feb 27 10:51:04 2010 +0000
+++ b/doc/source/vmm_constants_error.rst	Sat Feb 27 20:58:49 2010 +0000
@@ -43,6 +43,8 @@
 
   The alias address and its destination are the same
 
+  obsolete?
+
 .. data:: ALIAS_EXCEEDS_EXPANSION_LIMIT
 
   The Alias has reached or exceeds its expansion limit
@@ -51,6 +53,8 @@
 
   Alias with the given destination exists already
 
+  obsolete?
+
 .. data:: ALIAS_MISSING_DEST
 
   obsolete?
diff -r 0b6ce895e1dc -r 8b8d632f0ef3 doc/source/vmm_relocated.rst
--- a/doc/source/vmm_relocated.rst	Sat Feb 27 10:51:04 2010 +0000
+++ b/doc/source/vmm_relocated.rst	Sat Feb 27 20:58:49 2010 +0000
@@ -26,7 +26,7 @@
   order to delete the relocated user from the database.
   
   :param dbh: a database connection
-  :type dbh: :class:`PgSQL.Connection`
+  :type dbh: :class:`pyPgSQL.PgSQL.Connection`
   :param address: the e-mail address of the relocated user.
   :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress`