# HG changeset patch # User Pascal Volk # Date 1266984108 0 # Node ID 77ac6f57285547a9a0e674438a772845485f8c15 # Parent 0b129678cfe11bd58bc8c22eda5a4c1eb68d2d36 doc: extended documentation. diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/conf.py --- a/doc/source/conf.py Mon Feb 22 10:44:13 2010 +0000 +++ b/doc/source/conf.py Wed Feb 24 04:01:48 2010 +0000 @@ -22,7 +22,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.intersphinx'] +extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] @@ -197,3 +197,5 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} + +todo_include_todos = True diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/index.rst --- a/doc/source/index.rst Mon Feb 22 10:44:13 2010 +0000 +++ b/doc/source/index.rst Wed Feb 24 04:01:48 2010 +0000 @@ -14,6 +14,10 @@ vmm.rst vmm_config.rst + vmm_emailaddress.rst + vmm_relocated.rst + vmm_exceptions.rst + vmm_constants_error.rst Indices and tables ================== diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/vmm.rst --- a/doc/source/vmm.rst Mon Feb 22 10:44:13 2010 +0000 +++ b/doc/source/vmm.rst Wed Feb 24 04:01:48 2010 +0000 @@ -118,28 +118,28 @@ Examples -------- - >>> from VirtualMailManager import * - >>> ace2idna('xn--pypal-4ve.tld') - u'p\u0430ypal.tld' - >>> idn2ascii(u'öko.de') - 'xn--ko-eka.de' - >>> check_domainname(u'pаypal.tld') - 'xn--pypal-4ve.tld' - >>> check_localpart('john.doe') - 'john.doe' - >>> exec_ok('usr/bin/vim') - Traceback (most recent call last): - File "", line 1, in - File "./VirtualMailManager/__init__.py", line 93, in exec_ok - NO_SUCH_BINARY) - VirtualMailManager.Exceptions.VMMException: 'usr/bin/vim' is not a file - >>> exec_ok('/usr/bin/vim') - '/usr/bin/vim' - >>> expand_path('.') - '/home/user/hg/vmm' - >>> get_unicode('hello world') - u'hello world' - >>> is_dir('~/hg') - '/home/user/hg' - >>> + >>> from VirtualMailManager import * + >>> ace2idna('xn--pypal-4ve.tld') + u'p\u0430ypal.tld' + >>> idn2ascii(u'öko.de') + 'xn--ko-eka.de' + >>> check_domainname(u'pаypal.tld') + 'xn--pypal-4ve.tld' + >>> check_localpart('john.doe') + 'john.doe' + >>> exec_ok('usr/bin/vim') + Traceback (most recent call last): + File "", line 1, in + File "./VirtualMailManager/__init__.py", line 93, in exec_ok + NO_SUCH_BINARY) + VirtualMailManager.Exceptions.VMMException: 'usr/bin/vim' is not a file + >>> exec_ok('/usr/bin/vim') + '/usr/bin/vim' + >>> expand_path('.') + '/home/user/hg/vmm' + >>> get_unicode('hello world') + u'hello world' + >>> is_dir('~/hg') + '/home/user/hg' + >>> diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/vmm_constants_error.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/source/vmm_constants_error.rst Wed Feb 24 04:01:48 2010 +0000 @@ -0,0 +1,213 @@ +:mod:`VirtualMailManager.constants.ERROR` --- Error codes +========================================================= + +.. module:: VirtualMailManager.constants.ERROR + :synopsis: VirtualMailManager's error codes + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + +Error codes, used by all :mod:`VirtualMailManager.Exceptions`. + +.. data:: ACCOUNT_AND_ALIAS_PRESENT + + Can't delete the Domain - there are accounts and aliases assigned + +.. data:: ACCOUNT_EXISTS + + The Account exists already + +.. data:: ACCOUNT_PRESENT + + Can't delete the Domain - there are accounts + +.. data:: ALIASDOMAIN_EXISTS + + Can't save/switch the destination of the AliasDomain - old and new destination + are the same. + +.. data:: ALIASDOMAIN_ISDOMAIN + + Can't create AliasDomain - there is already a Domain with the given name + + .. todo:: Move the related check to the Handler class + +.. data:: ALIASDOMAIN_NO_DOMDEST + + Can't save/switch the destination of an AliasDomain if the destination was + omitted + +.. data:: ALIAS_ADDR_DEST_IDENTICAL + + The alias address and its destination are the same + +.. data:: ALIAS_EXCEEDS_EXPANSION_LIMIT + + The Alias has reached or exceeds its expansion limit + +.. data:: ALIAS_EXISTS + + Alias with the given destination exists already + +.. data:: ALIAS_MISSING_DEST + + obsolete? + +.. data:: ALIAS_PRESENT + + Can't delete Domain or Account - there are aliases assigned + +.. data:: CONF_ERROR + + Syntax error in the configuration file or missing settings w/o a default value + +.. data:: CONF_NOFILE + + The configuration file couldn't be found + +.. data:: CONF_NOPERM + + The user's permissions are insufficient + +.. data:: CONF_WRONGPERM + + Configuration file has the wrong access mode + +.. data:: DATABASE_ERROR + + A database error occurred + +.. data:: DOMAINDIR_GROUP_MISMATCH + + Domain directory is owned by the wrong group + +.. data:: DOMAIN_ALIAS_EXISTS + + Can't create Domain - there is already an AliasDomain with the same name + + .. todo:: Move the related check to the Handler class + +.. data:: DOMAIN_EXISTS + + The Domain is already available in the database + +.. data:: DOMAIN_INVALID + + The domain name is invalid + +.. data:: DOMAIN_NO_NAME + + Missing the domain name + +.. data:: DOMAIN_TOO_LONG + + The length of domain is > 255 + +.. data:: FOUND_DOTS_IN_PATH + + Can't delete directory with ``.`` or ``..`` in path + + .. todo:: check if we can solve this issue with expand_path() + +.. data:: INVALID_ADDRESS + + The specified value doesn't look like a e-mail address + +.. data:: INVALID_AGUMENT + + The given argument is invalid + +.. data:: INVALID_OPTION + + The given option is invalid + +.. data:: INVALID_SECTION + + The section is not a known configuration section + +.. data:: LOCALPART_INVALID + + The local-part of an e-mail address was omitted or is invalid + +.. data:: LOCALPART_TOO_LONG + + The local-part (w/o a extension) is too long (> 64) + +.. data:: MAILDIR_PERM_MISMATCH + + The Maildir is owned by the wrong user/group + +.. data:: MAILLOCATION_INIT + + Can't create a new MailLocation instance + +.. data:: NOT_EXECUTABLE + + The binary is not executable + +.. data:: NO_SUCH_ACCOUNT + + No Account with the given e-mail address + +.. data:: NO_SUCH_ALIAS + + No Alias with the given e-mail address + +.. data:: NO_SUCH_ALIASDOMAIN + + The given domain is not an AliasDomain + +.. data:: NO_SUCH_BINARY + + Can't find the file at the specified location + +.. data:: NO_SUCH_DIRECTORY + + There is no directory with the given path + +.. data:: NO_SUCH_DOMAIN + + No Domain with the given name + +.. data:: NO_SUCH_RELOCATED + + There is no Relocated user with the given e-mail address + +.. data:: RELOCATED_ADDR_DEST_IDENTICAL + + The e-mail address of the Relocated user an its destination are the same + +.. data:: RELOCATED_EXISTS + + Can't create Account or Alias, there is already a Relocated user with the + given e-mail address + +.. data:: RELOCATED_MISSING_DEST + + obsolete? + +.. data:: TRANSPORT_INIT + + Can't initialize a new Transport instance + +.. data:: UNKNOWN_MAILLOCATION_ID + + There is no MailLocation entry with the given ID + +.. data:: UNKNOWN_SERVICE + + The specified service is unknown + +.. data:: UNKNOWN_TRANSPORT_ID + + There is no Transport entry with the given ID + +.. data:: VMM_ERROR + + Internal error + +.. data:: VMM_TOO_MANY_FAILURES + + Too many errors in interactive mode diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/vmm_emailaddress.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/source/vmm_emailaddress.rst Wed Feb 24 04:01:48 2010 +0000 @@ -0,0 +1,61 @@ +:mod:`VirtualMailManager.EmailAddress` --- Handling of e-mail addresses +======================================================================= + +.. module:: VirtualMailManager.EmailAddress + :synopsis: Handling of e-mail addresses + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + + +This module provides the :class:`EmailAddress` class to handle validated e-mail +addresses. + + +EmailAddress +------------ + +.. class:: EmailAddress(address) + + Creates a new EmailAddress instance. + + :param address: string representation of an e-mail addresses + :type address: :obj:`basestring` + :raise VirtualMailManager.Exceptions.VMMEmailAddressException: if the + *address* is syntactically wrong. + :raise VirtualMailManager.Exceptions.VMMException: if the validation of the + local-part or domain name fails. + + An EmailAddress instance has the both read-only attributes: + + .. attribute:: localpart + + The local-part of the address *local-part@domain* + + + .. attribute:: domainname + + The domain part of the address *local-part@domain* + + +Examples +-------- + + >>> from VirtualMailManager.EmailAddress import EmailAddress + >>> john = EmailAddress('john.doe@example.com') + >>> john.localpart + 'john.doe' + >>> john.domainname + 'example.com' + >>> jane = EmailAddress('jane.doe@example.com') + >>> jane != john + True + >>> EmailAddress('info@xn--pypal-4ve.tld') == EmailAddress(u'info@pаypal.tld') + True + >>> jane + EmailAddress('jane.doe@example.com') + >>> print john + john.doe@example.com + >>> diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/vmm_exceptions.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/source/vmm_exceptions.rst Wed Feb 24 04:01:48 2010 +0000 @@ -0,0 +1,118 @@ +:mod:`VirtualMailManager.Exceptions` --- Exception classes +========================================================== + +.. module:: VirtualMailManager.Exceptions + :synopsis: Exception classes + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + +Exceptions, used by VirtualMailManager's classes. + + +Exceptions +---------- + +.. exception:: VMMException(msg, code) + + Bases: :exc:`exceptions.Exception` + + :param msg: the error message + :type msg: :obj:`basestring` + :param code: the error code (one of :mod:`VirtualMailManager.constants.ERROR`) + :type code: :obj:`int` + + Base class for all other Exceptions in the VirtualMailManager package. + + + .. method:: msg + + :rtype: :obj:`basestring` + + Returns the error message of the exception. + + + .. method:: code + + :rtype: :obj:`int` + + Returns the numerical error code of the exception. + + +.. exception:: VMMConfigException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for configuration (:mod:`VirtualMailManager.Config`) + exceptions. + + +.. exception:: VMMNotRootException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for non-root exceptions. + + +.. exception:: VMMDomainException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for Domain (:mod:`VirtualMailManager.Domain`) exceptions. + + +.. exception:: VMMAliasDomainException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for AliasDomain (:mod:`VirtualMailManager.AliasDomain`) + exceptions. + + +.. exception:: VMMAccountException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for Account (:mod:`VirtualMailManager.Account`) exceptions. + + +.. exception:: VMMAliasException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for Alias (:mod:`VirtualMailManager.Alias`) exceptions. + + +.. exception:: VMMEmailAddressException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for EmailAddress (:mod:`VirtualMailManager.EmailAddress`) + exceptions. + + +.. exception:: VMMMailLocationException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for MailLocation (:mod:`VirtualMailManager.MailLocation`) + exceptions. + + +.. exception:: VMMRelocatedException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for Relocated (:mod:`VirtualMailManager.Relocated`) + exceptions. + + +.. exception:: VMMTransportException(msg, code) + + Bases: :exc:`VirtualMailManager.Exceptions.VMMException` + + Exception class for Transport (:mod:`VirtualMailManager.Transport`) + exceptions. + diff -r 0b129678cfe1 -r 77ac6f572855 doc/source/vmm_relocated.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/source/vmm_relocated.rst Wed Feb 24 04:01:48 2010 +0000 @@ -0,0 +1,61 @@ +:mod:`VirtualMailManager.Relocated` --- Handling of relocated users +=================================================================== + +.. module:: VirtualMailManager.Relocated + :synopsis: Handling of relocated users + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + + +This module provides the :class:`Relocated` class. The data are read +from/stored in the ``relocated`` table. An optional lookup table, used +by Postfix for the "``user has moved to new_location``" reject/bounce message. + + +Relocated +--------- +.. class:: Relocated(dbh, address) + + Creates a new *Relocated* instance. If the relocated user with the given + *address* is already stored in the database use :meth:`getInfo` to get the + destination address of the relocated user. To set or update the destination + of the relocated user use :meth:`setDestination`. Use :meth:`delete` in + order to delete the relocated user from the database. + + :param dbh: a database connection + :type dbh: :class:`PgSQL.Connection` + :param address: the e-mail address of the relocated user. + :type address: :class:`VirtualMailManager.EmailAddress.EmailAddress` + + + .. method:: delete() + + :rtype: :obj:`None` + :raise VirtualMailManager.Exceptions.VMMRelocatedException: if the + relocated user doesn't exist. + + Deletes the relocated user from the database. + + + .. method:: getInfo() + + :rtype: :class:`VirtualMailManager.EmailAddress.EmailAddress` + :raise VirtualMailManager.Exceptions.VMMRelocatedException: if the + relocated user doesn't exist. + + Returns the destination e-mail address of the relocated user. + + + .. method:: setDestination(destination) + + :param destination: the new address where the relocated user has moved to + :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress` + :rtype: :obj:`None` + :raise VirtualMailManager.Exceptions.VMMRelocatedException: if the + *destination* address is already saved or is the same as the relocated + user's address. + + Sets or updates the *destination* address of the relocated user.