# HG changeset patch # User Pascal Volk # Date 1343571425 0 # Node ID 20141b967c0b658ee14f6eedc7462d345421150e # Parent 4f9079dd4b657488d8be3865ededb17ec3fa5cd2 doc: Moved API documentation to doc/api. diff -r 4f9079dd4b65 -r 20141b967c0b doc/Makefile --- a/doc/Makefile Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,89 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/vmm.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/vmm.qhc" - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/Makefile --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/Makefile Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,89 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/vmm.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/vmm.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/source/conf.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/conf.py Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,201 @@ +# -*- coding: utf-8 -*- +# +# vmm documentation build configuration file, created by +# sphinx-quickstart on Sun Feb 14 00:08:08 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# 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', 'sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'vmm' +copyright = u'2010, Pascal Volk' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.6' +# The full version, including alpha/beta/rc tags. +release = '0.6.x' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' +#html_theme = 'sphinxdoc' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'vmmdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'vmm.tex', u'vmm Documentation', + u'Pascal Volk', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} + +todo_include_todos = True diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/source/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/index.rst Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,29 @@ +====================== +VirtualMailManager API +====================== + +:Author: Pascal Volk +:Date: |today| +:Release: |version| + +Contents: + +.. toctree:: + :maxdepth: 1 + :numbered: + + vmm.rst + vmm_config.rst + vmm_emailaddress.rst + vmm_alias.rst + vmm_relocated.rst + vmm_errors.rst + vmm_constants_error.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm.rst Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,132 @@ +:mod:`VirtualMailManager` --- Initialization code and some functions +===================================================================== + +.. module:: VirtualMailManager + :synopsis: Initialization code and some functions + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + +When the VirtualMailManager module, or one of its sub modules, is imported, +the following actions will be performed: + + - :func:`locale.setlocale` (with :const:`locale.LC_ALL`) is called, to set + :const:`ENCODING` + - :func:`gettext.install` is called, to have 18N support. + +Constants and data +------------------ + +.. data:: ENCODING + + The systems current character encoding, e.g. ``'UTF-8'`` or + ``'ANSI_X3.4-1968'`` (aka ASCII). + + +Functions +--------- + +.. function:: ace2idna(domainname) + + Converts the idn domain name *domainname* into punycode. + + :param domainname: the domain-ace representation (``xn--…``) + :type domainname: str + :rtype: unicode + +.. function:: check_domainname(domainname) + + Returns the validated domain name *domainname*. + + It also converts the name of the domain from IDN to ASCII, if necessary. + + :param domainname: the name of the domain + :type domainname: :obj:`basestring` + :rtype: str + :raise VirtualMailManager.errors.VMMError: if the domain name is + too long or doesn't look like a valid domain name (label.label.label). + +.. function:: check_localpart(localpart) + + Returns the validated local-part *localpart* of an e-mail address. + + :param localpart: The local-part of an e-mail address. + :type localpart: str + :rtype: str + :raise VirtualMailManager.errors.VMMError: if the local-part is too + long or contains invalid characters. + +.. function:: exec_ok(binary) + + Checks if the *binary* exists and if it is executable. + + :param binary: path to the binary + :type binary: str + :rtype: str + :raise VirtualMailManager.errors.VMMError: if *binary* isn't a file + or is not executable. + +.. function:: expand_path(path) + + Expands paths, starting with ``.`` or ``~``, to an absolute path. + + :param path: Path to a file or directory + :type path: str + :rtype: str + +.. function:: get_unicode(string) + + Converts `string` to `unicode`, if necessary. + + :param string: The string taht should be converted + :type string: str + :rtype: unicode + +.. function:: idn2ascii(domainname) + + Converts the idn domain name *domainname* into punycode. + + :param domainname: the unicode representation of the domain name + :type domainname: unicode + :rtype: str + +.. function:: is_dir(path) + + Checks if *path* is a directory. + + :param path: Path to a directory + :type path: str + :rtype: str + :raise VirtualMailManager.errors.VMMError: if *path* is not a directory. + + +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.errors.VMMError: '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 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm_alias.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm_alias.rst Sun Jul 29 14:17:05 2012 +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 + +.. 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 + `_) + :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 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm_config.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm_config.rst Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,275 @@ +:mod:`VirtualMailManager.Config` --- Simplified configuration access +====================================================================== + +.. module:: VirtualMailManager.Config + :synopsis: Simplified configuration access + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + + +This module provides a few classes for simplified configuration handling +and the validation of the setting's *type* and *value*. + +:class:`LazyConfig` is derived from Python's +:class:`ConfigParser.RawConfigParser`. It doesn't use ``RawConfigParser``'s +``DEFAULT`` section. All settings and their defaults, if supposed, are +handled by :class:`LazyConfigOption` objects in the :attr:`LazyConfig._cfg` +*dict*. + +``LazyConfig``'s setters and getters for options are taking a single string +for the *section* and *option* argument, e.g. ``config.pget('database.user')`` +instead of ``config.get('database', 'user')``. + + + +LazyConfig +---------- +.. class:: LazyConfig + + Bases: :class:`ConfigParser.RawConfigParser` + + .. versionadded:: 0.6.0 + + .. attribute:: _cfg + + a multi dimensional :class:`dict`, containing *sections* and *options*, + represented by :class:`LazyConfigOption` objects. + + For example:: + + from VirtualMailManager.Config import LazyConfig, LazyConfigOption + + class FooConfig(LazyConfig): + def __init__(self, ...): + LazyConfig.__init__(self) + ... + LCO = LazyConfigOption + self._cfg = { + 'database': {# section database: + 'host': LCO(str, '::1', self.get), # options of the + 'name': LCO(str, 'dbx', self.get), # database section. + 'pass': LCO(str, None, self.get), # No defaults for the + 'user': LCO(str, None, self.get), # user and pass options + } + } + + ... + + + .. method:: bool_new(value) + + Converts the string *value* into a `bool` and returns it. + + | ``'1'``, ``'on'``, ``'yes'`` and ``'true'`` will become :const:`True` + | ``'0'``, ``'off'``, ``'no'`` and ``'false'`` will become :const:`False` + + :param value: one of the above mentioned strings + :type value: :obj:`basestring` + :rtype: bool + :raise ConfigValueError: for all other values, except ``bool``\ s + + .. method:: dget(option) + + Like :meth:`pget`, but returns the *option*'s default value, from + :attr:`_cfg` (defined by :attr:`LazyConfigOption.default`) if the *option* + is not configured in a ini-like configuration file. + + :param option: the section.option combination + :type option: :obj:`basestring` + :raise NoDefaultError: if the *option* couldn't be found in the + configuration file and no default value was passed to + :class:`LazyConfigOption`'s constructor for the requested *option*. + + .. method:: getboolean(section, option) + + Returns the boolean value of the *option*, in the given *section*. + + For a boolean :const:`True`, the value must be set to ``'1'``, ``'on'``, + ``'yes'``, ``'true'`` or :const:`True`. For a boolean :const:`False`, the + value must set to ``'0'``, ``'off'``, ``'no'``, ``'false'`` or + :const:`False`. + + :param section: The section's name + :type section: :obj:`basestring` + :param option: The option's name + :type option: :obj:`basestring` + :rtype: bool + :raise ValueError: if the option has an other value than the values + mentioned above. + + .. method:: has_option(option) + + Checks if the *option* (section\ **.**\ option) is a known configuration + option. + + :param option: The option's name + :type option: :obj:`basestring` + :rtype: bool + + .. method:: has_section(section) + + Checks if *section* is a known configuration section. + + :param section: The section's name + :type section: :obj:`basestring` + :rtype: bool + + .. method:: items(section) + + Returns an iterator for ``key, value`` :obj:`tuple`\ s for each option in + the given *section*. + + :param section: The section's name + :type section: :obj:`basestring` + :raise NoSectionError: if the given *section* is not known. + + .. method:: pget(option) + + Polymorphic getter which returns the *option*'s value (by calling + :attr:`LazyConfigOption.getter`) with the appropriate type, defined by + :attr:`LazyConfigOption.cls`. + + :param option: the section.option combination + :type option: :obj:`basestring` + + .. method:: sections() + + Returns an iterator object for all configuration sections from the + :attr:`_cfg` dictionary. + + :rtype: :obj:`dictionary-keyiterator` + + .. method:: set(option, value) + + Like :meth:`ConfigParser.RawConfigParser.set`, but converts the *option*'s + new *value* (by calling :attr:`LazyConfigOption.cls`) to the appropriate + type/class. When the ``LazyConfigOption``'s optional parameter *validate* + was not :const:`None`, the new *value* will be also validated. + + :param option: the section.option combination + :type option: :obj:`basestring` + :param value: the new value to be set + :type value: :obj:`basestring` + :rtype: :const:`None` + :raise ConfigValueError: if a boolean value shout be set (:meth:`bool_new`) + and it fails + :raise ValueError: if an other setter (:attr:`LazyConfigOption.cls`) or + validator (:attr:`LazyConfigOption.validate`) fails. + :raise VirtualMailManager.errors.VMMError: if + :attr:`LazyConfigOption.validate` is set to + :func:`VirtualMailManager.exec_ok` or :func:`VirtualMailManager.is_dir`. + + +LazyConfigOption +---------------- +LazyConfigOption instances are required by :class:`LazyConfig` instances, and +instances of classes derived from `LazyConfig`, like the :class:`Config` +class. + +.. class:: LazyConfigOption (cls, default, getter[, validate=None]) + + .. versionadded:: 0.6.0 + + The constructor's parameters are: + + ``cls`` : :obj:`type` + The class/type of the option's value. + ``default`` : :obj:`str` or the one defined by ``cls`` + Default value of the option. Use :const:`None` if the option shouldn't + have a default value. + ``getter``: :obj:`callable` + A method's name of :class:`ConfigParser.RawConfigParser` and derived + classes, to get a option's value, e.g. `self.getint`. + ``validate`` : :obj:`callable` or :const:`None` + :const:`None` or any function, which takes one argument and returns the + validated argument with the appropriate type (for example: + :meth:`LazyConfig.bool_new`). The function should raise a + :exc:`ConfigValueError` if the validation fails. This function checks the + new value when :meth:`LazyConfig.set()` is called. + + Each LazyConfigOption object has the following read-only attributes: + + .. attribute:: cls + + The class of the option's value e.g. `str`, `unicode` or `bool`. Used as + setter method when :meth:`LazyConfig.set` (or the ``set()`` method of a + derived class) is called. + + .. attribute:: default + + The option's default value, may be ``None`` + + .. attribute:: getter + + A method's name of :class:`ConfigParser.RawConfigParser` and derived + classes, to get a option's value, e.g. ``self.getint``. + + .. attribute:: validate + + A method or function to validate the option's new value. + + +Config +------ +The final configuration class of the virtual mail manager. + +.. class:: Config (filename) + + Bases: :class:`LazyConfig` + + :param filename: absolute path to the configuration file. + :type filename: :obj:`basestring` + + .. attribute:: _cfg + + The configuration ``dict``, containing all configuration sections and + options, as described in :attr:`LazyConfig._cfg`. + + .. method:: check() + + Checks all section's options for settings w/o a default value. + + :raise VirtualMailManager.errors.ConfigError: if the check fails + + .. method:: load() + + Loads the configuration read-only. + + :raise VirtualMailManager.errors.ConfigError: if the + configuration syntax is invalid + + .. method:: unicode(section, option) + + Returns the value of the *option* from *section*, converted to Unicode. + This method is intended for the :attr:`LazyConfigOption.getter`. + + :param section: The name of the configuration section + :type section: :obj:`basestring` + :param option: The name of the configuration option + :type option: :obj:`basestring` + :rtype: :obj:`unicode` + + +Exceptions +---------- + +.. exception:: BadOptionError(msg) + + Bases: :exc:`ConfigParser.Error` + + Raised when a option isn't in the format 'section.option'. + +.. exception:: ConfigValueError(msg) + + Bases: :exc:`ConfigParser.Error` + + Raised when creating or validating of new values fails. + +.. exception:: NoDefaultError(section, option) + + Bases: :exc:`ConfigParser.Error` + + Raised when the requested option has no default value. diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm_constants_error.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm_constants_error.rst Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,227 @@ +: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.errors`. + +.. 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 + + obsolete? + +.. data:: ALIAS_EXCEEDS_EXPANSION_LIMIT + + The Alias has reached or exceeds its expansion limit + +.. data:: ALIAS_EXISTS + + Alias with the given destination exists already + + obsolete? + +.. 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 + + obsolete? + +.. 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 + + obsolete? + +.. data:: UNKNOWN_MAILLOCATION_ID + + There is no MailLocation entry with the given ID + + obsolete? + +.. data:: UNKNOWN_SERVICE + + The specified service is unknown + +.. data:: UNKNOWN_TRANSPORT_ID + + There is no Transport entry with the given ID + +.. data:: UNKNOWN_MAILLOCATION_NAME + + The given mail_location directory couldn't be accepted + +.. data:: VMM_ERROR + + Internal error + +.. data:: VMM_TOO_MANY_FAILURES + + Too many errors in interactive mode diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm_emailaddress.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm_emailaddress.rst Sun Jul 29 14:17:05 2012 +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.errors.EmailAddressError: if the + *address* is syntactically wrong. + :raise VirtualMailManager.errors.VMMError: 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 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm_errors.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm_errors.rst Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,122 @@ +:mod:`VirtualMailManager.errors` --- Exception classes +====================================================== + +.. module:: VirtualMailManager.errors + :synopsis: Exception classes + +.. moduleauthor:: Pascal Volk + +.. toctree:: + :maxdepth: 2 + +Exceptions, used by VirtualMailManager's classes. + + +Exceptions +---------- + +.. exception:: VMMError(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. + + The *msg* and *code* are accessible via the both attributes: + + .. attribute:: msg + + The error message of the exception. + + + .. attribute:: code + + The numerical error code of the exception. + + +.. exception:: ConfigError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for configuration (:mod:`VirtualMailManager.Config`) + exceptions. + + +.. exception:: PermissionError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for file permission exceptions. + + +.. exception:: NotRootError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for non-root exceptions. + + +.. exception:: DomainError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for Domain (:mod:`VirtualMailManager.Domain`) exceptions. + + +.. exception:: AliasDomainError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for AliasDomain (:mod:`VirtualMailManager.AliasDomain`) + exceptions. + + +.. exception:: AccountError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for Account (:mod:`VirtualMailManager.Account`) exceptions. + + +.. exception:: AliasError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for Alias (:mod:`VirtualMailManager.Alias`) exceptions. + + +.. exception:: EmailAddressError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for EmailAddress (:mod:`VirtualMailManager.EmailAddress`) + exceptions. + + +.. exception:: MailLocationError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for MailLocation (:mod:`VirtualMailManager.MailLocation`) + exceptions. + + +.. exception:: RelocatedError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for Relocated (:mod:`VirtualMailManager.Relocated`) + exceptions. + + +.. exception:: TransportError(msg, code) + + Bases: :exc:`VirtualMailManager.errors.VMMError` + + Exception class for Transport (:mod:`VirtualMailManager.Transport`) + exceptions. + diff -r 4f9079dd4b65 -r 20141b967c0b doc/api/source/vmm_relocated.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/api/source/vmm_relocated.rst Sun Jul 29 14:17:05 2012 +0000 @@ -0,0 +1,60 @@ +: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:`get_info` to get the + destination address of the relocated user. To set or update the destination + of the relocated user use :meth:`set_destination`. Use :meth:`delete` in + order to delete the relocated user from the database. + + :param dbh: a database connection + :type dbh: :class:`pyPgSQL.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.errors.RelocatedError: if the relocated user + doesn't exist. + + Deletes the relocated user from the database. + + + .. method:: get_info() + + :rtype: :class:`VirtualMailManager.EmailAddress.EmailAddress` + :raise VirtualMailManager.errors.RelocatedError: if the relocated user + doesn't exist. + + Returns the destination e-mail address of the relocated user. + + + .. method:: set_destination(destination) + + :param destination: the new address where the relocated user has moved to + :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress` + :rtype: :obj:`None` + :raise VirtualMailManager.errors.RelocatedError: 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. diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/conf.py --- a/doc/source/conf.py Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,201 +0,0 @@ -# -*- coding: utf-8 -*- -# -# vmm documentation build configuration file, created by -# sphinx-quickstart on Sun Feb 14 00:08:08 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.append(os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# 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', 'sphinx.ext.todo'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'vmm' -copyright = u'2010, Pascal Volk' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.6' -# The full version, including alpha/beta/rc tags. -release = '0.6.x' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'default' -#html_theme = 'sphinxdoc' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['.static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'vmmdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'vmm.tex', u'vmm Documentation', - u'Pascal Volk', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_use_modindex = True - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} - -todo_include_todos = True diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/index.rst --- a/doc/source/index.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ -====================== -VirtualMailManager API -====================== - -:Author: Pascal Volk -:Date: |today| -:Release: |version| - -Contents: - -.. toctree:: - :maxdepth: 1 - :numbered: - - vmm.rst - vmm_config.rst - vmm_emailaddress.rst - vmm_alias.rst - vmm_relocated.rst - vmm_errors.rst - vmm_constants_error.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/vmm.rst --- a/doc/source/vmm.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,132 +0,0 @@ -:mod:`VirtualMailManager` --- Initialization code and some functions -===================================================================== - -.. module:: VirtualMailManager - :synopsis: Initialization code and some functions - -.. moduleauthor:: Pascal Volk - -.. toctree:: - :maxdepth: 2 - -When the VirtualMailManager module, or one of its sub modules, is imported, -the following actions will be performed: - - - :func:`locale.setlocale` (with :const:`locale.LC_ALL`) is called, to set - :const:`ENCODING` - - :func:`gettext.install` is called, to have 18N support. - -Constants and data ------------------- - -.. data:: ENCODING - - The systems current character encoding, e.g. ``'UTF-8'`` or - ``'ANSI_X3.4-1968'`` (aka ASCII). - - -Functions ---------- - -.. function:: ace2idna(domainname) - - Converts the idn domain name *domainname* into punycode. - - :param domainname: the domain-ace representation (``xn--…``) - :type domainname: str - :rtype: unicode - -.. function:: check_domainname(domainname) - - Returns the validated domain name *domainname*. - - It also converts the name of the domain from IDN to ASCII, if necessary. - - :param domainname: the name of the domain - :type domainname: :obj:`basestring` - :rtype: str - :raise VirtualMailManager.errors.VMMError: if the domain name is - too long or doesn't look like a valid domain name (label.label.label). - -.. function:: check_localpart(localpart) - - Returns the validated local-part *localpart* of an e-mail address. - - :param localpart: The local-part of an e-mail address. - :type localpart: str - :rtype: str - :raise VirtualMailManager.errors.VMMError: if the local-part is too - long or contains invalid characters. - -.. function:: exec_ok(binary) - - Checks if the *binary* exists and if it is executable. - - :param binary: path to the binary - :type binary: str - :rtype: str - :raise VirtualMailManager.errors.VMMError: if *binary* isn't a file - or is not executable. - -.. function:: expand_path(path) - - Expands paths, starting with ``.`` or ``~``, to an absolute path. - - :param path: Path to a file or directory - :type path: str - :rtype: str - -.. function:: get_unicode(string) - - Converts `string` to `unicode`, if necessary. - - :param string: The string taht should be converted - :type string: str - :rtype: unicode - -.. function:: idn2ascii(domainname) - - Converts the idn domain name *domainname* into punycode. - - :param domainname: the unicode representation of the domain name - :type domainname: unicode - :rtype: str - -.. function:: is_dir(path) - - Checks if *path* is a directory. - - :param path: Path to a directory - :type path: str - :rtype: str - :raise VirtualMailManager.errors.VMMError: if *path* is not a directory. - - -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.errors.VMMError: '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 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_alias.rst --- a/doc/source/vmm_alias.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,87 +0,0 @@ -:mod:`VirtualMailManager.Alias` --- Handling of alias e-mail addresses -====================================================================== - -.. module:: VirtualMailManager.Alias - :synopsis: Handling of alias e-mail addresses - -.. moduleauthor:: Pascal Volk - -.. 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 - `_) - :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 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_config.rst --- a/doc/source/vmm_config.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,275 +0,0 @@ -:mod:`VirtualMailManager.Config` --- Simplified configuration access -====================================================================== - -.. module:: VirtualMailManager.Config - :synopsis: Simplified configuration access - -.. moduleauthor:: Pascal Volk - -.. toctree:: - :maxdepth: 2 - - -This module provides a few classes for simplified configuration handling -and the validation of the setting's *type* and *value*. - -:class:`LazyConfig` is derived from Python's -:class:`ConfigParser.RawConfigParser`. It doesn't use ``RawConfigParser``'s -``DEFAULT`` section. All settings and their defaults, if supposed, are -handled by :class:`LazyConfigOption` objects in the :attr:`LazyConfig._cfg` -*dict*. - -``LazyConfig``'s setters and getters for options are taking a single string -for the *section* and *option* argument, e.g. ``config.pget('database.user')`` -instead of ``config.get('database', 'user')``. - - - -LazyConfig ----------- -.. class:: LazyConfig - - Bases: :class:`ConfigParser.RawConfigParser` - - .. versionadded:: 0.6.0 - - .. attribute:: _cfg - - a multi dimensional :class:`dict`, containing *sections* and *options*, - represented by :class:`LazyConfigOption` objects. - - For example:: - - from VirtualMailManager.Config import LazyConfig, LazyConfigOption - - class FooConfig(LazyConfig): - def __init__(self, ...): - LazyConfig.__init__(self) - ... - LCO = LazyConfigOption - self._cfg = { - 'database': {# section database: - 'host': LCO(str, '::1', self.get), # options of the - 'name': LCO(str, 'dbx', self.get), # database section. - 'pass': LCO(str, None, self.get), # No defaults for the - 'user': LCO(str, None, self.get), # user and pass options - } - } - - ... - - - .. method:: bool_new(value) - - Converts the string *value* into a `bool` and returns it. - - | ``'1'``, ``'on'``, ``'yes'`` and ``'true'`` will become :const:`True` - | ``'0'``, ``'off'``, ``'no'`` and ``'false'`` will become :const:`False` - - :param value: one of the above mentioned strings - :type value: :obj:`basestring` - :rtype: bool - :raise ConfigValueError: for all other values, except ``bool``\ s - - .. method:: dget(option) - - Like :meth:`pget`, but returns the *option*'s default value, from - :attr:`_cfg` (defined by :attr:`LazyConfigOption.default`) if the *option* - is not configured in a ini-like configuration file. - - :param option: the section.option combination - :type option: :obj:`basestring` - :raise NoDefaultError: if the *option* couldn't be found in the - configuration file and no default value was passed to - :class:`LazyConfigOption`'s constructor for the requested *option*. - - .. method:: getboolean(section, option) - - Returns the boolean value of the *option*, in the given *section*. - - For a boolean :const:`True`, the value must be set to ``'1'``, ``'on'``, - ``'yes'``, ``'true'`` or :const:`True`. For a boolean :const:`False`, the - value must set to ``'0'``, ``'off'``, ``'no'``, ``'false'`` or - :const:`False`. - - :param section: The section's name - :type section: :obj:`basestring` - :param option: The option's name - :type option: :obj:`basestring` - :rtype: bool - :raise ValueError: if the option has an other value than the values - mentioned above. - - .. method:: has_option(option) - - Checks if the *option* (section\ **.**\ option) is a known configuration - option. - - :param option: The option's name - :type option: :obj:`basestring` - :rtype: bool - - .. method:: has_section(section) - - Checks if *section* is a known configuration section. - - :param section: The section's name - :type section: :obj:`basestring` - :rtype: bool - - .. method:: items(section) - - Returns an iterator for ``key, value`` :obj:`tuple`\ s for each option in - the given *section*. - - :param section: The section's name - :type section: :obj:`basestring` - :raise NoSectionError: if the given *section* is not known. - - .. method:: pget(option) - - Polymorphic getter which returns the *option*'s value (by calling - :attr:`LazyConfigOption.getter`) with the appropriate type, defined by - :attr:`LazyConfigOption.cls`. - - :param option: the section.option combination - :type option: :obj:`basestring` - - .. method:: sections() - - Returns an iterator object for all configuration sections from the - :attr:`_cfg` dictionary. - - :rtype: :obj:`dictionary-keyiterator` - - .. method:: set(option, value) - - Like :meth:`ConfigParser.RawConfigParser.set`, but converts the *option*'s - new *value* (by calling :attr:`LazyConfigOption.cls`) to the appropriate - type/class. When the ``LazyConfigOption``'s optional parameter *validate* - was not :const:`None`, the new *value* will be also validated. - - :param option: the section.option combination - :type option: :obj:`basestring` - :param value: the new value to be set - :type value: :obj:`basestring` - :rtype: :const:`None` - :raise ConfigValueError: if a boolean value shout be set (:meth:`bool_new`) - and it fails - :raise ValueError: if an other setter (:attr:`LazyConfigOption.cls`) or - validator (:attr:`LazyConfigOption.validate`) fails. - :raise VirtualMailManager.errors.VMMError: if - :attr:`LazyConfigOption.validate` is set to - :func:`VirtualMailManager.exec_ok` or :func:`VirtualMailManager.is_dir`. - - -LazyConfigOption ----------------- -LazyConfigOption instances are required by :class:`LazyConfig` instances, and -instances of classes derived from `LazyConfig`, like the :class:`Config` -class. - -.. class:: LazyConfigOption (cls, default, getter[, validate=None]) - - .. versionadded:: 0.6.0 - - The constructor's parameters are: - - ``cls`` : :obj:`type` - The class/type of the option's value. - ``default`` : :obj:`str` or the one defined by ``cls`` - Default value of the option. Use :const:`None` if the option shouldn't - have a default value. - ``getter``: :obj:`callable` - A method's name of :class:`ConfigParser.RawConfigParser` and derived - classes, to get a option's value, e.g. `self.getint`. - ``validate`` : :obj:`callable` or :const:`None` - :const:`None` or any function, which takes one argument and returns the - validated argument with the appropriate type (for example: - :meth:`LazyConfig.bool_new`). The function should raise a - :exc:`ConfigValueError` if the validation fails. This function checks the - new value when :meth:`LazyConfig.set()` is called. - - Each LazyConfigOption object has the following read-only attributes: - - .. attribute:: cls - - The class of the option's value e.g. `str`, `unicode` or `bool`. Used as - setter method when :meth:`LazyConfig.set` (or the ``set()`` method of a - derived class) is called. - - .. attribute:: default - - The option's default value, may be ``None`` - - .. attribute:: getter - - A method's name of :class:`ConfigParser.RawConfigParser` and derived - classes, to get a option's value, e.g. ``self.getint``. - - .. attribute:: validate - - A method or function to validate the option's new value. - - -Config ------- -The final configuration class of the virtual mail manager. - -.. class:: Config (filename) - - Bases: :class:`LazyConfig` - - :param filename: absolute path to the configuration file. - :type filename: :obj:`basestring` - - .. attribute:: _cfg - - The configuration ``dict``, containing all configuration sections and - options, as described in :attr:`LazyConfig._cfg`. - - .. method:: check() - - Checks all section's options for settings w/o a default value. - - :raise VirtualMailManager.errors.ConfigError: if the check fails - - .. method:: load() - - Loads the configuration read-only. - - :raise VirtualMailManager.errors.ConfigError: if the - configuration syntax is invalid - - .. method:: unicode(section, option) - - Returns the value of the *option* from *section*, converted to Unicode. - This method is intended for the :attr:`LazyConfigOption.getter`. - - :param section: The name of the configuration section - :type section: :obj:`basestring` - :param option: The name of the configuration option - :type option: :obj:`basestring` - :rtype: :obj:`unicode` - - -Exceptions ----------- - -.. exception:: BadOptionError(msg) - - Bases: :exc:`ConfigParser.Error` - - Raised when a option isn't in the format 'section.option'. - -.. exception:: ConfigValueError(msg) - - Bases: :exc:`ConfigParser.Error` - - Raised when creating or validating of new values fails. - -.. exception:: NoDefaultError(section, option) - - Bases: :exc:`ConfigParser.Error` - - Raised when the requested option has no default value. diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_constants_error.rst --- a/doc/source/vmm_constants_error.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,227 +0,0 @@ -: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.errors`. - -.. 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 - - obsolete? - -.. data:: ALIAS_EXCEEDS_EXPANSION_LIMIT - - The Alias has reached or exceeds its expansion limit - -.. data:: ALIAS_EXISTS - - Alias with the given destination exists already - - obsolete? - -.. 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 - - obsolete? - -.. 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 - - obsolete? - -.. data:: UNKNOWN_MAILLOCATION_ID - - There is no MailLocation entry with the given ID - - obsolete? - -.. data:: UNKNOWN_SERVICE - - The specified service is unknown - -.. data:: UNKNOWN_TRANSPORT_ID - - There is no Transport entry with the given ID - -.. data:: UNKNOWN_MAILLOCATION_NAME - - The given mail_location directory couldn't be accepted - -.. data:: VMM_ERROR - - Internal error - -.. data:: VMM_TOO_MANY_FAILURES - - Too many errors in interactive mode diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_emailaddress.rst --- a/doc/source/vmm_emailaddress.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ -: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.errors.EmailAddressError: if the - *address* is syntactically wrong. - :raise VirtualMailManager.errors.VMMError: 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 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_errors.rst --- a/doc/source/vmm_errors.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,122 +0,0 @@ -:mod:`VirtualMailManager.errors` --- Exception classes -====================================================== - -.. module:: VirtualMailManager.errors - :synopsis: Exception classes - -.. moduleauthor:: Pascal Volk - -.. toctree:: - :maxdepth: 2 - -Exceptions, used by VirtualMailManager's classes. - - -Exceptions ----------- - -.. exception:: VMMError(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. - - The *msg* and *code* are accessible via the both attributes: - - .. attribute:: msg - - The error message of the exception. - - - .. attribute:: code - - The numerical error code of the exception. - - -.. exception:: ConfigError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for configuration (:mod:`VirtualMailManager.Config`) - exceptions. - - -.. exception:: PermissionError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for file permission exceptions. - - -.. exception:: NotRootError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for non-root exceptions. - - -.. exception:: DomainError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for Domain (:mod:`VirtualMailManager.Domain`) exceptions. - - -.. exception:: AliasDomainError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for AliasDomain (:mod:`VirtualMailManager.AliasDomain`) - exceptions. - - -.. exception:: AccountError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for Account (:mod:`VirtualMailManager.Account`) exceptions. - - -.. exception:: AliasError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for Alias (:mod:`VirtualMailManager.Alias`) exceptions. - - -.. exception:: EmailAddressError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for EmailAddress (:mod:`VirtualMailManager.EmailAddress`) - exceptions. - - -.. exception:: MailLocationError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for MailLocation (:mod:`VirtualMailManager.MailLocation`) - exceptions. - - -.. exception:: RelocatedError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for Relocated (:mod:`VirtualMailManager.Relocated`) - exceptions. - - -.. exception:: TransportError(msg, code) - - Bases: :exc:`VirtualMailManager.errors.VMMError` - - Exception class for Transport (:mod:`VirtualMailManager.Transport`) - exceptions. - diff -r 4f9079dd4b65 -r 20141b967c0b doc/source/vmm_relocated.rst --- a/doc/source/vmm_relocated.rst Sun Jul 22 20:19:07 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,60 +0,0 @@ -: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:`get_info` to get the - destination address of the relocated user. To set or update the destination - of the relocated user use :meth:`set_destination`. Use :meth:`delete` in - order to delete the relocated user from the database. - - :param dbh: a database connection - :type dbh: :class:`pyPgSQL.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.errors.RelocatedError: if the relocated user - doesn't exist. - - Deletes the relocated user from the database. - - - .. method:: get_info() - - :rtype: :class:`VirtualMailManager.EmailAddress.EmailAddress` - :raise VirtualMailManager.errors.RelocatedError: if the relocated user - doesn't exist. - - Returns the destination e-mail address of the relocated user. - - - .. method:: set_destination(destination) - - :param destination: the new address where the relocated user has moved to - :type destination: :class:`VirtualMailManager.EmailAddress.EmailAddress` - :rtype: :obj:`None` - :raise VirtualMailManager.errors.RelocatedError: 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.