diff options
30 files changed, 2224 insertions, 483 deletions
diff --git a/mail/.gitignore b/mail/.gitignore index 3a80621..7ac8289 100644 --- a/mail/.gitignore +++ b/mail/.gitignore @@ -20,3 +20,5 @@ local/ share/ MANIFEST twistd.pid +_trial_temp +_trial_temp.lock diff --git a/mail/CHANGELOG b/mail/CHANGELOG index 08d20cc..4c3da7b 100644 --- a/mail/CHANGELOG +++ b/mail/CHANGELOG @@ -1,4 +1,11 @@ -0.3.9 Apr 4: +0.3.10 Sept 26, 2014: + o MessageCollection iterator now creates the LeapMessage with the + collection reference, so setFlags will work properly. + o account#addMailbox can't allow empty mailbox names since it makes + it impossible to create it later (mailbox#__init__ will throw an + error), which makes it impossible to getMailbox or even delete it. + +0.3.9 Apr 4, 2014: o Footer url shouldn't end in period. Closes #4791. o Handle non-ascii headers. Closes #5021. o Soledad writer consumes messages eagerly. Fixes failing @@ -50,9 +57,7 @@ o Makes efficient use of indexes and count method. Closes #4616. o Handle correctly unicode characters in emails. Closes #4838. --- 2014 -- - -0.3.8 Dec 6: +0.3.8 Dec 6, 2013: o Fail gracefully when failing to decrypt incoming messages. Closes #4589. o Fix a bug when adding a message with empty flags. Closes #4496 @@ -68,7 +73,7 @@ threads. Closes #4606 o Set remote mail polling time to 60 seconds. Closes #4499 -0.3.7 Nov 15: +0.3.7 Nov 15, 2013: o Uses deferToThread for sendMail. Closes #3937 o Update pkey to allow multiple accounts. Solves: #4394 o Change SMTP service name from "relay" to "gateway". Closes #4416. @@ -88,7 +93,7 @@ o Correctly handle email headers when gatewaying messages. Also add OpenPGP header. Closes #4322 and #4447. -0.3.6 Nov 1: +0.3.6 Nov 1, 2013: o Add support for non-ascii characters in emails. Closes #4000. o Default to UTF-8 when there is no charset parsed from the mail contents. @@ -98,20 +103,20 @@ o Notify MUA of new mail, using IDLE as advertised. Closes: #3671 o Use TLS wrapper mode instead of STARTTLS. Closes #3637. -0.3.5 Oct 18: +0.3.5 Oct 18, 2013: o Do not log mail doc contents. o Comply with RFC 3156. Closes #4029. -0.3.4 Oct 4: +0.3.4 Oct 4, 2013: o Improve charset handling when exposing mails to the mail client. Related to #3660. o Return Twisted's smtp Port object to be able to stop listening to it whenever we want. Related to #3873. -0.3.3 Sep 20: +0.3.3 Sep 20, 2013: o Remove cleartext mail from logs. Closes: #3877. -0.3.2 Sep 6: +0.3.2 Sep 6, 2013: o Make mail services bind to 127.0.0.1. Closes: #3627. o Signal unread message to UI when message is saved locally. Closes: #3654. @@ -119,7 +124,7 @@ o Use dirspec instead of plain xdg. Closes #3574. o SMTP service invocation returns factory instance. -0.3.1 Aug 23: +0.3.1 Aug 23, 2013: o Avoid logging dummy password on imap server. Closes: #3416 o Do not fail while processing an empty mail, just skip it. Fixes #3457. @@ -138,7 +143,7 @@ o Improve packaging: add versioneer, parse_requirements, classifiers. -0.3.0 Aug 9: +0.3.0 Aug 9, 2013: o Add dependency for leap.keymanager. o User 1984 default port for imap. o Add client certificate authentication. Closes #3376. diff --git a/mail/README.rst b/mail/README.rst index 9090d7c..317389a 100644 --- a/mail/README.rst +++ b/mail/README.rst @@ -5,11 +5,22 @@ Mail services for the LEAP Client. .. image:: https://pypip.in/v/leap.mail/badge.png :target: https://crate.io/packages/leap.mail +.. image:: https://readthedocs.org/projects/leapmail/badge/?version=latest + :target: http://leapmail.readthedocs.org/en/latest/ + :alt: Documentation Status More info: https://leap.se running tests ------------- -* nosetests --with-progressive leap.mail.imap.test_imap -* trial leap.mail.smtp +Use trial to run the test suite:: + + trial leap.mail + +... and all its goodies. To run all imap tests in a loop until some of them +fails:: + + trial -u leap.mail.imap + +Read the *trial* manpage for more options . diff --git a/mail/docs/Makefile b/mail/docs/Makefile new file mode 100644 index 0000000..388b6c6 --- /dev/null +++ b/mail/docs/Makefile @@ -0,0 +1,179 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @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 " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @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." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +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/leapmail.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/leapmail.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/leapmail" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/leapmail" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +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." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +build_rtd: + curl -X POST http://readthedocs.org/build/leapmail diff --git a/mail/docs/api/Makefile b/mail/docs/api/Makefile new file mode 100644 index 0000000..ebcd0f4 --- /dev/null +++ b/mail/docs/api/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @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 " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @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." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +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/mail.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/mail.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/mail" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/mail" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +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." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/mail/docs/api/conf.py b/mail/docs/api/conf.py new file mode 100644 index 0000000..2199c2f --- /dev/null +++ b/mail/docs/api/conf.py @@ -0,0 +1,331 @@ +# -*- coding: utf-8 -*- +# +# mail documentation build configuration file, created by +# sphinx-quickstart on Mon Aug 25 19:47:12 2014. +# +# 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 +import 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.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# 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.autodoc', + 'sphinx.ext.viewcode', +] + +# 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-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'mail' +copyright = u'2014, Author' + +# 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 = '' +# The full version, including alpha/beta/rc tags. +release = '' + +# 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 patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# 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 = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# 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 +# "<project> v<release> 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# 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_domain_indices = 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, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'maildoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'mail.tex', u'mail Documentation', + u'Author', '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 + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'mail', u'mail Documentation', + [u'Author'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'mail', u'mail Documentation', + u'Author', 'mail', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'mail' +epub_author = u'Author' +epub_publisher = u'Author' +epub_copyright = u'2014, Author' + +# The basename for the epub file. It defaults to the project name. +#epub_basename = u'mail' + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the PIL. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True diff --git a/mail/docs/api/index.rst b/mail/docs/api/index.rst new file mode 100644 index 0000000..f5531df --- /dev/null +++ b/mail/docs/api/index.rst @@ -0,0 +1,23 @@ +.. mail documentation master file, created by + sphinx-quickstart on Mon Aug 25 19:47:12 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to mail's documentation! +================================ + +Contents: + +.. toctree:: + :maxdepth: 4 + + mail + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/mail/docs/api/mail.imap.rst b/mail/docs/api/mail.imap.rst new file mode 100644 index 0000000..051ded6 --- /dev/null +++ b/mail/docs/api/mail.imap.rst @@ -0,0 +1,118 @@ +mail.imap package +================= + +Subpackages +----------- + +.. toctree:: + + mail.imap.service + mail.imap.tests + +Submodules +---------- + +mail.imap.account module +------------------------ + +.. automodule:: mail.imap.account + :members: + :undoc-members: + :show-inheritance: + +mail.imap.fetch module +---------------------- + +.. automodule:: mail.imap.fetch + :members: + :undoc-members: + :show-inheritance: + +mail.imap.fields module +----------------------- + +.. automodule:: mail.imap.fields + :members: + :undoc-members: + :show-inheritance: + +mail.imap.index module +---------------------- + +.. automodule:: mail.imap.index + :members: + :undoc-members: + :show-inheritance: + +mail.imap.interfaces module +--------------------------- + +.. automodule:: mail.imap.interfaces + :members: + :undoc-members: + :show-inheritance: + +mail.imap.mailbox module +------------------------ + +.. automodule:: mail.imap.mailbox + :members: + :undoc-members: + :show-inheritance: + +mail.imap.memorystore module +---------------------------- + +.. automodule:: mail.imap.memorystore + :members: + :undoc-members: + :show-inheritance: + +mail.imap.messageparts module +----------------------------- + +.. automodule:: mail.imap.messageparts + :members: + :undoc-members: + :show-inheritance: + +mail.imap.messages module +------------------------- + +.. automodule:: mail.imap.messages + :members: + :undoc-members: + :show-inheritance: + +mail.imap.parser module +----------------------- + +.. automodule:: mail.imap.parser + :members: + :undoc-members: + :show-inheritance: + +mail.imap.server module +----------------------- + +.. automodule:: mail.imap.server + :members: + :undoc-members: + :show-inheritance: + +mail.imap.soledadstore module +----------------------------- + +.. automodule:: mail.imap.soledadstore + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: mail.imap + :members: + :undoc-members: + :show-inheritance: diff --git a/mail/docs/api/mail.imap.service.rst b/mail/docs/api/mail.imap.service.rst new file mode 100644 index 0000000..c288813 --- /dev/null +++ b/mail/docs/api/mail.imap.service.rst @@ -0,0 +1,30 @@ +mail.imap.service package +========================= + +Submodules +---------- + +mail.imap.service.imap module +----------------------------- + +.. automodule:: mail.imap.service.imap + :members: + :undoc-members: + :show-inheritance: + +mail.imap.service.manhole module +-------------------------------- + +.. automodule:: mail.imap.service.manhole + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: mail.imap.service + :members: + :undoc-members: + :show-inheritance: diff --git a/mail/docs/api/mail.imap.tests.rst b/mail/docs/api/mail.imap.tests.rst new file mode 100644 index 0000000..b6717a3 --- /dev/null +++ b/mail/docs/api/mail.imap.tests.rst @@ -0,0 +1,38 @@ +mail.imap.tests package +======================= + +Submodules +---------- + +mail.imap.tests.imapclient module +--------------------------------- + +.. automodule:: mail.imap.tests.imapclient + :members: + :undoc-members: + :show-inheritance: + +mail.imap.tests.test_imap module +-------------------------------- + +.. automodule:: mail.imap.tests.test_imap + :members: + :undoc-members: + :show-inheritance: + +mail.imap.tests.walktree module +------------------------------- + +.. automodule:: mail.imap.tests.walktree + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: mail.imap.tests + :members: + :undoc-members: + :show-inheritance: diff --git a/mail/docs/api/mail.rst b/mail/docs/api/mail.rst new file mode 100644 index 0000000..2713207 --- /dev/null +++ b/mail/docs/api/mail.rst @@ -0,0 +1,70 @@ +mail package +============ + +Subpackages +----------- + +.. toctree:: + + mail.imap + mail.smtp + +Submodules +---------- + +mail.decorators module +---------------------- + +.. automodule:: mail.decorators + :members: + :undoc-members: + :show-inheritance: + +mail.load_tests module +---------------------- + +.. automodule:: mail.load_tests + :members: + :undoc-members: + :show-inheritance: + +mail.messageflow module +----------------------- + +.. automodule:: mail.messageflow + :members: + :undoc-members: + :show-inheritance: + +mail.size module +---------------- + +.. automodule:: mail.size + :members: + :undoc-members: + :show-inheritance: + +mail.utils module +----------------- + +.. automodule:: mail.utils + :members: + :undoc-members: + :show-inheritance: + +mail.walk module +---------------- + +.. automodule:: mail.walk + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: mail + :members: + :undoc-members: + :show-inheritance: diff --git a/mail/docs/api/mail.smtp.rst b/mail/docs/api/mail.smtp.rst new file mode 100644 index 0000000..da67279 --- /dev/null +++ b/mail/docs/api/mail.smtp.rst @@ -0,0 +1,37 @@ +mail.smtp package +================= + +Subpackages +----------- + +.. toctree:: + + mail.smtp.tests + +Submodules +---------- + +mail.smtp.gateway module +------------------------ + +.. automodule:: mail.smtp.gateway + :members: + :undoc-members: + :show-inheritance: + +mail.smtp.rfc3156 module +------------------------ + +.. automodule:: mail.smtp.rfc3156 + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: mail.smtp + :members: + :undoc-members: + :show-inheritance: diff --git a/mail/docs/api/mail.smtp.tests.rst b/mail/docs/api/mail.smtp.tests.rst new file mode 100644 index 0000000..c313fb3 --- /dev/null +++ b/mail/docs/api/mail.smtp.tests.rst @@ -0,0 +1,22 @@ +mail.smtp.tests package +======================= + +Submodules +---------- + +mail.smtp.tests.test_gateway module +----------------------------------- + +.. automodule:: mail.smtp.tests.test_gateway + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: mail.smtp.tests + :members: + :undoc-members: + :show-inheritance: diff --git a/mail/docs/api/make.bat b/mail/docs/api/make.bat new file mode 100644 index 0000000..63cd17f --- /dev/null +++ b/mail/docs/api/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ 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. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. xml to make Docutils-native XML files
+ echo. pseudoxml to make pseudoxml-XML files for display purposes
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\mail.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\mail.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdf" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdfja" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf-ja
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+if "%1" == "xml" (
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.
+ goto end
+)
+
+if "%1" == "pseudoxml" (
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+ goto end
+)
+
+:end
diff --git a/mail/docs/api/modules.rst b/mail/docs/api/modules.rst new file mode 100644 index 0000000..7827779 --- /dev/null +++ b/mail/docs/api/modules.rst @@ -0,0 +1,7 @@ +mail +==== + +.. toctree:: + :maxdepth: 4 + + mail diff --git a/mail/docs/conf.py b/mail/docs/conf.py new file mode 100644 index 0000000..8e08f09 --- /dev/null +++ b/mail/docs/conf.py @@ -0,0 +1,334 @@ +# -*- coding: utf-8 -*- +# +# leap.mail documentation build configuration file, created by +# sphinx-quickstart on Mon Aug 25 19:19:48 2014. +# +# 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 +import 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.insert(0, os.path.abspath('../src')) +sys.path.insert(0, os.path.abspath('../src/leap')) +sys.path.insert(0, os.path.abspath('../src/leap/mail')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# 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.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', +] + +# 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-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'leap.mail' +copyright = u'2014, Kali Kaneko' + +# 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.3.9' +# The full version, including alpha/beta/rc tags. +release = '0.3.9' + +# 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 patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# 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 = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# 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 +# "<project> v<release> 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# 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_domain_indices = 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, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'leapmaildoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'leapmail.tex', u'leap.mail Documentation', + u'Kali Kaneko', '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 + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'leapmail', u'leap.mail Documentation', + [u'Kali Kaneko'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'leapmail', u'leap.mail Documentation', + u'Kali Kaneko', 'leapmail', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'leap.mail' +epub_author = u'Kali Kaneko' +epub_publisher = u'Kali Kaneko' +epub_copyright = u'2014, Kali Kaneko' + +# The basename for the epub file. It defaults to the project name. +#epub_basename = u'leap.mail' + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the PIL. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True diff --git a/mail/docs/index.rst b/mail/docs/index.rst new file mode 100644 index 0000000..4801833 --- /dev/null +++ b/mail/docs/index.rst @@ -0,0 +1,66 @@ +.. leap.mail documentation master file, created by + sphinx-quickstart on Mon Aug 25 19:19:48 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to leap.mail's documentation! +===================================== + +This is the documentation for the ``leap.imap`` module. It is a twisted package +that exposes two services, ``smtp`` and ``imap``, that run local proxies and interact +with a remote ``LEAP`` provider that offers *a soledad syncronization endpoint* +and receive the outgoing email. + +See :ref:`the life cycle of a leap email <mail_journey>` for an overview of the life cycle +of an email through ``LEAP`` providers. + +``Soledad`` stores its documents as local ``sqlcipher`` tables, and syncs +against the soledad sync service in the provider. + + +.. TODO clear document types documentation. + +The data model at the present moment consists of several *document types* that split email into +different documents that are stored in ``Soledad``. The idea behind this is to +keep clear the separation between *mutable* and *inmutable* parts, and still being able to +reconstruct arbitrarily nested email structures easily. + +In the coming releases we are going to be working towards the goal of exposing +a protocol-agnostic email public API, so that third party mail clients can +manipulate the data layer without having to resort to handling the sql tables or +doing direct u1db calls. The code will be transitioning towards a LEAPMail +public API that we can stabilize as soon as possible, and leaving the IMAP +server as another code entity that uses this lower layer. + + +.. +.. Contents: +.. toctree:: + :maxdepth: 2 + +.. intro +.. tutorial + + +API documentation +----------------- + +If you were looking for the documentation of the ``leap.mail`` module, you will +find it here. Beware that the public API will still be unstable for the next +development cycles. + +.. toctree:: + :maxdepth: 2 + + api/mail + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/mail/docs/intro.rst b/mail/docs/intro.rst new file mode 100644 index 0000000..6090a90 --- /dev/null +++ b/mail/docs/intro.rst @@ -0,0 +1,4 @@ +Introduction +============ + +leap.mail intro diff --git a/mail/docs/mail_journey.rst b/mail/docs/mail_journey.rst new file mode 100644 index 0000000..7e64f18 --- /dev/null +++ b/mail/docs/mail_journey.rst @@ -0,0 +1,40 @@ +.. _mail_journey: + +The life cycle of a LEAP Email +============================== +The following are just some notes to facilitate the understanding of the +leap.mail internals to developers and collaborators. + +Server-side: receiving mail from the outside world +-------------------------------------------------- + +1. the mx server receives an email, it gets through all the postfix validation and it's written into disk +2. ``leap_mx`` gets that write in disk notification and encrypts the incoming mail to its intended recipient's pubkey +3. that encrypted blob gets written into couchdb in a way soledad will catch it in the next sync + + +Client-side: fetching and processing incoming email +--------------------------------------------------- +you have an imap and an smtp local server. For IMAP: + +1. soledad syncs +2. **fetch** module sees if there's new encrypted mail for the current user from leap_mx +3. if there is, the mail is decrypted using the user private key, and splitted + into several parts according to the internal mail data model (separating + mutable and inmutable email parts). Those documents it encrypts it properly + like other soledad documents and deletes the pubkey encrypted doc +4. desktop client is notified that there are N new mails +5. when a MUA connects to the **imap** local server, the different documents are glued + together and presented as response to the different imap commands. + + +Client side: sending email +-------------------------- + +1. you write an email to a recipient and hit send +2. the **smtp** local server gets that mail, it checks from whom it is and to whom it is for +3. it signs the mail with the ``From:``'s privkey +4. it retrieves ``To:``'s pubkey with the keymanager and if it finds it encrypts the mail to him/her +5. if it didn't find it and you don't have your client configured to "always encrypt", it goes out with just the signature +6. else, it fails out complaining about this conflict +7. that mail gets relayed to the provider's **smtp** server diff --git a/mail/docs/tutorial.rst b/mail/docs/tutorial.rst new file mode 100644 index 0000000..5cf7d02 --- /dev/null +++ b/mail/docs/tutorial.rst @@ -0,0 +1,3 @@ +Tutorial +======== +`leap.mail` tutorial diff --git a/mail/src/leap/mail/imap/account.py b/mail/src/leap/mail/imap/account.py index 199a2a4..70ed13b 100644 --- a/mail/src/leap/mail/imap/account.py +++ b/mail/src/leap/mail/imap/account.py @@ -129,8 +129,9 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): def mailboxes(self): """ A list of the current mailboxes for this account. + :rtype: set """ - return self.__mailboxes + return sorted(self.__mailboxes) def _load_mailboxes(self): self.__mailboxes.update( @@ -149,7 +150,7 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): def getMailbox(self, name): """ - Returns a Mailbox with that name, without selecting it. + Return a Mailbox with that name, without selecting it. :param name: name of the mailbox :type name: str @@ -165,9 +166,9 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): return SoledadMailbox(name, self._soledad, memstore=self._memstore) - ## - ## IAccount - ## + # + # IAccount + # def addMailbox(self, name, creation_ts=None): """ @@ -186,10 +187,12 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): """ name = self._parse_mailbox_name(name) + leap_assert(name, "Need a mailbox name to create a mailbox") + if name in self.mailboxes: raise imap4.MailboxCollision(repr(name)) - if not creation_ts: + if creation_ts is None: # by default, we pass an int value # taken from the current time # we make sure to take enough decimals to get a unique @@ -278,15 +281,15 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): """ name = self._parse_mailbox_name(name) - if not name in self.mailboxes: + if name not in self.mailboxes: raise imap4.MailboxException("No such mailbox: %r" % name) - mbox = self.getMailbox(name) if force is False: # See if this box is flagged \Noselect # XXX use mbox.flags instead? - if self.NOSELECT_FLAG in mbox.getFlags(): + mbox_flags = mbox.getFlags() + if self.NOSELECT_FLAG in mbox_flags: # Check for hierarchically inferior mailboxes with this one # as part of their root. for others in self.mailboxes: @@ -294,16 +297,16 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): raise imap4.MailboxException, ( "Hierarchically inferior mailboxes " "exist and \\Noselect is set") + self.__mailboxes.discard(name) mbox.destroy() - self._load_mailboxes() # XXX FIXME --- not honoring the inferior names... # if there are no hierarchically inferior names, we will # delete it from our ken. - #if self._inferiorNames(name) > 1: - # ??! -- can this be rite? - #self._index.removeMailbox(name) + # if self._inferiorNames(name) > 1: + # ??! -- can this be rite? + # self._index.removeMailbox(name) def rename(self, oldname, newname): """ @@ -332,6 +335,7 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): self._memstore.rename_fdocs_mailbox(old, new) mbox = self._get_mailbox_by_name(old) mbox.content[self.MBOX_KEY] = new + self.__mailboxes.discard(old) self._soledad.put_doc(mbox) self._load_mailboxes() @@ -374,7 +378,7 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): """ # maybe we should store subscriptions in another # document... - if not name in self.mailboxes: + if name not in self.mailboxes: self.addMailbox(name) mbox = self._get_mailbox_by_name(name) @@ -428,9 +432,9 @@ class SoledadBackedAccount(WithMsgFields, IndexedDB, MBoxParser): wildcard = imap4.wildcardToRegexp(wildcard, '/') return [(i, self.getMailbox(i)) for i in ref if wildcard.match(i)] - ## - ## INamespacePresenter - ## + # + # INamespacePresenter + # def getPersonalNamespaces(self): return [["", "/"]] diff --git a/mail/src/leap/mail/imap/mailbox.py b/mail/src/leap/mail/imap/mailbox.py index 47c7ff1..34cf535 100644 --- a/mail/src/leap/mail/imap/mailbox.py +++ b/mail/src/leap/mail/imap/mailbox.py @@ -214,6 +214,7 @@ class SoledadMailbox(WithMsgFields, MBoxParser): """ return self._memstore.get_mbox_doc(self.mbox) + # XXX the memstore->soledadstore method in memstore is not complete def getFlags(self): """ Returns the flags defined for this mailbox. @@ -221,21 +222,12 @@ class SoledadMailbox(WithMsgFields, MBoxParser): :returns: tuple of flags for this mailbox :rtype: tuple of str """ - flags = self.INIT_FLAGS - - # XXX returning fixed flags always - # Since I have not found a case where the client - # wants to modify this, as a way of speeding up - # selects. To do it right, we probably should keep - # track of the set of all flags used by msgs - # in this mailbox. Does it matter? - #mbox = self._get_mbox_doc() - #if not mbox: - #return None - #flags = mbox.content.get(self.FLAGS_KEY, []) + flags = self._memstore.get_mbox_flags(self.mbox) + if not flags: + flags = self.INIT_FLAGS return map(str, flags) - # XXX move to memstore->soledadstore + # XXX the memstore->soledadstore method in memstore is not complete def setFlags(self, flags): """ Sets flags for this mailbox. @@ -243,15 +235,10 @@ class SoledadMailbox(WithMsgFields, MBoxParser): :param flags: a tuple with the flags :type flags: tuple of str """ + # XXX this is setting (overriding) old flags. leap_assert(isinstance(flags, tuple), "flags expected to be a tuple") - mbox = self._get_mbox_doc() - if not mbox: - return None - mbox.content[self.FLAGS_KEY] = map(str, flags) - logger.debug("Writing mbox document for %r to Soledad" - % (self.mbox,)) - self._soledad.put_doc(mbox) + self._memstore.set_mbox_flags(self.mbox, flags) # XXX SHOULD BETTER IMPLEMENT ADD_FLAG, REMOVE_FLAG. @@ -301,6 +288,9 @@ class SoledadMailbox(WithMsgFields, MBoxParser): primed = self._last_uid_primed.get(self.mbox, False) if not primed: mbox = self._get_mbox_doc() + if mbox is None: + # memory-only store + return last = mbox.content.get('lastuid', 0) logger.info("Priming Soledad last_uid to %s" % (last,)) self._memstore.set_last_soledad_uid(self.mbox, last) @@ -469,6 +459,8 @@ class SoledadMailbox(WithMsgFields, MBoxParser): notify_on_disk=notify_on_disk) if PROFILE_CMD: do_profile_cmd(d, "APPEND") + + # XXX should review now that we're not using qtreactor. # A better place for this would be the COPY/APPEND dispatcher # in server.py, but qtreactor hangs when I do that, so this seems # to work fine for now. @@ -531,6 +523,8 @@ class SoledadMailbox(WithMsgFields, MBoxParser): Should cleanup resources, and set the \\Noselect flag on the mailbox. """ + # XXX this will overwrite all the existing flags! + # should better simply addFlag self.setFlags((self.NOSELECT_FLAG,)) self.deleteAllDocs() @@ -538,6 +532,10 @@ class SoledadMailbox(WithMsgFields, MBoxParser): # we should postpone the removal # XXX move to memory store?? + mbox_doc = self._get_mbox_doc() + if mbox_doc is None: + # memory-only store! + return self._soledad.delete_doc(self._get_mbox_doc()) def _close_cb(self, result): @@ -640,7 +638,7 @@ class SoledadMailbox(WithMsgFields, MBoxParser): # switch to content-hash based index + local UID table. sequence = False - #sequence = True if uid == 0 else False + # sequence = True if uid == 0 else False messages_asked = self._bound_seq(messages_asked) seq_messg = self._filter_msg_seq(messages_asked) diff --git a/mail/src/leap/mail/imap/memorystore.py b/mail/src/leap/mail/imap/memorystore.py index d383b79..5eea4ef 100644 --- a/mail/src/leap/mail/imap/memorystore.py +++ b/mail/src/leap/mail/imap/memorystore.py @@ -27,6 +27,7 @@ from copy import copy from enum import Enum from twisted.internet import defer +from twisted.internet import reactor from twisted.internet.task import LoopingCall from twisted.python import log from zope.interface import implements @@ -111,12 +112,14 @@ class MemoryStore(object): :param write_period: the interval to dump messages to disk, in seconds. :type write_period: int """ - from twisted.internet import reactor self.reactor = reactor self._permanent_store = permanent_store self._write_period = write_period + if permanent_store is None: + self._mbox_closed = defaultdict(lambda: False) + # Internal Storage: messages """ flags document store. @@ -201,6 +204,12 @@ class MemoryStore(object): """ self._known_uids = defaultdict(set) + """ + mbox-flags is a dict containing flags for each mailbox. this is + modified from mailbox.getFlags / mailbox.setFlags + """ + self._mbox_flags = defaultdict(set) + # New and dirty flags, to set MessageWrapper State. self._new = set([]) self._new_queue = set([]) @@ -367,8 +376,8 @@ class MemoryStore(object): # TODO --- this has to be deferred to thread, # TODO add hdoc and cdocs sizes too # it's slowing things down here. - #key = mbox, uid - #self._sizes[key] = size.get_size(self._fdoc_store[key]) + # key = mbox, uid + # self._sizes[key] = size.get_size(self._fdoc_store[key]) def purge_fdoc_store(self, mbox): """ @@ -616,7 +625,7 @@ class MemoryStore(object): :type value: int """ # can be long??? - #leap_assert_type(value, int) + # leap_assert_type(value, int) logger.info("setting last soledad uid for %s to %s" % (mbox, value)) # if we already have a value here, don't do anything @@ -1223,7 +1232,10 @@ class MemoryStore(object): :type mbox: str or unicode :rtype: SoledadDocument or None. """ - return self.permanent_store.get_mbox_document(mbox) + if self.permanent_store is not None: + return self.permanent_store.get_mbox_document(mbox) + else: + return None def get_mbox_closed(self, mbox): """ @@ -1233,7 +1245,10 @@ class MemoryStore(object): :type mbox: str or unicode :rtype: bool """ - return self.permanent_store.get_mbox_closed(mbox) + if self.permanent_store is not None: + return self.permanent_store.get_mbox_closed(mbox) + else: + return self._mbox_closed[mbox] def set_mbox_closed(self, mbox, closed): """ @@ -1242,7 +1257,25 @@ class MemoryStore(object): :param mbox: the mailbox :type mbox: str or unicode """ - self.permanent_store.set_mbox_closed(mbox, closed) + if self.permanent_store is not None: + self.permanent_store.set_mbox_closed(mbox, closed) + else: + self._mbox_closed[mbox] = closed + + def get_mbox_flags(self, mbox): + """ + Get the flags for a given mbox. + :rtype: list + """ + return sorted(self._mbox_flags[mbox]) + + def set_mbox_flags(self, mbox, flags): + """ + Set the mbox flags + """ + self._mbox_flags[mbox] = set(flags) + # TODO + # This should write to the permanent store!!! # Rename flag-documents diff --git a/mail/src/leap/mail/imap/messages.py b/mail/src/leap/mail/imap/messages.py index b0b2f95..0356600 100644 --- a/mail/src/leap/mail/imap/messages.py +++ b/mail/src/leap/mail/imap/messages.py @@ -750,7 +750,7 @@ class MessageCollection(WithMsgFields, IndexedDB, MBoxParser): :return: a dict with the template :rtype: dict """ - if not _type in self.templates.keys(): + if _type not in self.templates.keys(): raise TypeError("Improper type passed to _get_empty_doc") return copy.deepcopy(self.templates[_type]) @@ -864,7 +864,7 @@ class MessageCollection(WithMsgFields, IndexedDB, MBoxParser): else: return False - def add_msg(self, raw, subject=None, flags=None, date=None, uid=None, + def add_msg(self, raw, subject=None, flags=None, date=None, notify_on_disk=False): """ Creates a new message document. @@ -881,9 +881,6 @@ class MessageCollection(WithMsgFields, IndexedDB, MBoxParser): :param date: the received date for the message :type date: str - :param uid: the message uid for this mailbox - :type uid: int - :return: a deferred that will be fired with the message uid when the adding succeed. :rtype: deferred @@ -933,15 +930,16 @@ class MessageCollection(WithMsgFields, IndexedDB, MBoxParser): msg.setFlags((fields.DELETED_FLAG,), -1) return + # XXX get FUCKING UID from autoincremental table uid = self.memstore.increment_last_soledad_uid(self.mbox) # We can say the observer that we're done at this point, but # before that we should make sure it has no serious consequences # if we're issued, for instance, a fetch command right after... - #self.reactor.callFromThread(observer.callback, uid) + # self.reactor.callFromThread(observer.callback, uid) # if we did the notify, we need to invalidate the deferred # so not to try to fire it twice. - #observer = None + # observer = None fd = self._populate_flags(flags, uid, chash, size, multi) hd = self._populate_headr(msg, chash, subject, date) @@ -1337,7 +1335,7 @@ class MessageCollection(WithMsgFields, IndexedDB, MBoxParser): :returns: a list of LeapMessages :rtype: list """ - return [LeapMessage(self._soledad, docid, self.mbox) + return [LeapMessage(self._soledad, docid, self.mbox, collection=self) for docid in self.unseen_iter()] # recent messages @@ -1370,7 +1368,7 @@ class MessageCollection(WithMsgFields, IndexedDB, MBoxParser): :returns: iterator of dicts with content for all messages. :rtype: iterable """ - return (LeapMessage(self._soledad, docuid, self.mbox) + return (LeapMessage(self._soledad, docuid, self.mbox, collection=self) for docuid in self.all_uid_iter()) def __repr__(self): diff --git a/mail/src/leap/mail/imap/tests/test_imap.py b/mail/src/leap/mail/imap/tests/test_imap.py index fd88440..631a2c1 100644 --- a/mail/src/leap/mail/imap/tests/test_imap.py +++ b/mail/src/leap/mail/imap/tests/test_imap.py @@ -25,7 +25,6 @@ XXX add authors from the original twisted tests. @license: GPLv3, see included LICENSE file """ # XXX review license of the original tests!!! -from email import parser try: from cStringIO import StringIO @@ -34,43 +33,25 @@ except ImportError: import os import types -import tempfile -import shutil -import time - -from itertools import chain - - -from mock import Mock -from nose.twistedtools import deferred, stop_reactor -from unittest import skip from twisted.mail import imap4 -from twisted.protocols import loopback from twisted.internet import defer from twisted.trial import unittest -from twisted.python import util, log +from twisted.python import util from twisted.python import failure from twisted import cred -import twisted.cred.error -import twisted.cred.checkers -import twisted.cred.credentials -import twisted.cred.portal # import u1db -from leap.common.testing.basetest import BaseLeapTest -from leap.mail.imap.account import SoledadBackedAccount from leap.mail.imap.mailbox import SoledadMailbox from leap.mail.imap.memorystore import MemoryStore from leap.mail.imap.messages import MessageCollection from leap.mail.imap.server import LeapIMAPServer +from leap.mail.imap.tests.utils import IMAP4HelperMixin -from leap.soledad.client import Soledad -from leap.soledad.client import SoledadCrypto TEST_USER = "testuser@leap.se" TEST_PASSWD = "1234" @@ -91,46 +72,6 @@ def sortNest(l): return l -def initialize_soledad(email, gnupg_home, tempdir): - """ - Initializes soledad by hand - - :param email: ID for the user - :param gnupg_home: path to home used by gnupg - :param tempdir: path to temporal dir - :rtype: Soledad instance - """ - - uuid = "foobar-uuid" - passphrase = u"verysecretpassphrase" - secret_path = os.path.join(tempdir, "secret.gpg") - local_db_path = os.path.join(tempdir, "soledad.u1db") - server_url = "http://provider" - cert_file = "" - - class MockSharedDB(object): - - get_doc = Mock(return_value=None) - put_doc = Mock() - lock = Mock(return_value=('atoken', 300)) - unlock = Mock(return_value=True) - - def __call__(self): - return self - - Soledad._shared_db = MockSharedDB() - - _soledad = Soledad( - uuid, - passphrase, - secret_path, - local_db_path, - server_url, - cert_file) - - return _soledad - - class TestRealm: """ @@ -143,205 +84,6 @@ class TestRealm: # -# Simple IMAP4 Client for testing -# - - -class SimpleClient(imap4.IMAP4Client): - - """ - A Simple IMAP4 Client to test our - Soledad-LEAPServer - """ - - def __init__(self, deferred, contextFactory=None): - imap4.IMAP4Client.__init__(self, contextFactory) - self.deferred = deferred - self.events = [] - - def serverGreeting(self, caps): - self.deferred.callback(None) - - def modeChanged(self, writeable): - self.events.append(['modeChanged', writeable]) - self.transport.loseConnection() - - def flagsChanged(self, newFlags): - self.events.append(['flagsChanged', newFlags]) - self.transport.loseConnection() - - def newMessages(self, exists, recent): - self.events.append(['newMessages', exists, recent]) - self.transport.loseConnection() - - -class IMAP4HelperMixin(BaseLeapTest): - - """ - MixIn containing several utilities to be shared across - different TestCases - """ - - serverCTX = None - clientCTX = None - - @classmethod - def setUpClass(cls): - """ - TestCase initialization setup. - Sets up a new environment. - Initializes a SINGLE Soledad Instance that will be shared - by all tests in this base class. - This breaks orthogonality, avoiding us to use trial, so we should - move away from this test design. But it's a quick way to get - started without knowing / mocking the soledad api. - - We do also some duplication with BaseLeapTest cause trial and nose - seem not to deal well with deriving classmethods. - """ - cls.old_path = os.environ['PATH'] - cls.old_home = os.environ['HOME'] - cls.tempdir = tempfile.mkdtemp(prefix="leap_tests-") - cls.home = cls.tempdir - bin_tdir = os.path.join( - cls.tempdir, - 'bin') - os.environ["PATH"] = bin_tdir - os.environ["HOME"] = cls.tempdir - - # Soledad: config info - cls.gnupg_home = "%s/gnupg" % cls.tempdir - cls.email = 'leap@leap.se' - - # initialize soledad by hand so we can control keys - cls._soledad = initialize_soledad( - cls.email, - cls.gnupg_home, - cls.tempdir) - - # now we're passing the mailbox name, so we - # should get this into a partial or something. - # cls.sm = SoledadMailbox("mailbox", soledad=cls._soledad) - # XXX REFACTOR --- self.server (in setUp) is initializing - # a SoledadBackedAccount - - @classmethod - def tearDownClass(cls): - """ - TestCase teardown method. - - Restores the old path and home environment variables. - Removes the temporal dir created for tests. - """ - cls._soledad.close() - - os.environ["PATH"] = cls.old_path - os.environ["HOME"] = cls.old_home - # safety check - assert cls.tempdir.startswith('/tmp/leap_tests-') - shutil.rmtree(cls.tempdir) - - def setUp(self): - """ - Setup method for each test. - - Initializes and run a LEAP IMAP4 Server, - but passing the same Soledad instance (it's costly to initialize), - so we have to be sure to restore state across tests. - """ - UUID = 'deadbeef', - USERID = TEST_USER - memstore = MemoryStore() - - d = defer.Deferred() - self.server = LeapIMAPServer( - uuid=UUID, userid=USERID, - contextFactory=self.serverCTX, - # XXX do we really need this?? - soledad=self._soledad) - - self.client = SimpleClient(d, contextFactory=self.clientCTX) - self.connected = d - - # XXX REVIEW-ME. - # We're adding theAccount here to server - # but it was also passed to initialization - # as it was passed to realm. - # I THINK we ONLY need to do it at one place now. - - theAccount = SoledadBackedAccount( - USERID, - soledad=self._soledad, - memstore=memstore) - LeapIMAPServer.theAccount = theAccount - - # in case we get something from previous tests... - for mb in self.server.theAccount.mailboxes: - self.server.theAccount.delete(mb) - - # email parser - self.parser = parser.Parser() - - def tearDown(self): - """ - tearDown method called after each test. - - Deletes all documents in the Index, and deletes - instances of server and client. - """ - self.delete_all_docs() - acct = self.server.theAccount - for mb in acct.mailboxes: - acct.delete(mb) - - # FIXME add again - # for subs in acct.subscriptions: - # acct.unsubscribe(subs) - - del self.server - del self.client - del self.connected - - def populateMessages(self): - """ - Populates soledad instance with several simple messages - """ - # XXX we should encapsulate this thru SoledadBackedAccount - # instead. - - # XXX we also should put this in a mailbox! - - self._soledad.messages.add_msg('', uid=1, subject="test1") - self._soledad.messages.add_msg('', uid=2, subject="test2") - self._soledad.messages.add_msg('', uid=3, subject="test3") - # XXX should change Flags too - self._soledad.messages.add_msg('', uid=4, subject="test4") - - def delete_all_docs(self): - """ - Deletes all the docs in the testing instance of the - SoledadBackedAccount. - """ - self.server.theAccount.deleteAllMessages( - iknowhatiamdoing=True) - - def _cbStopClient(self, ignore): - self.client.transport.loseConnection() - - def _ebGeneral(self, failure): - self.client.transport.loseConnection() - self.server.transport.loseConnection() - # can we do something similar? - # I guess this was ok with trial, but not in noseland... - #log.err(failure, "Problem with %r" % (self.function,)) - raise failure.value - #failure.trap(Exception) - - def loopback(self): - return loopback.loopbackAsync(self.server, self.client) - - -# # TestCases # @@ -358,6 +100,7 @@ class MessageCollectionTestCase(IMAP4HelperMixin, unittest.TestCase): We override mixin method since we are only testing MessageCollection interface in this particular TestCase """ + super(MessageCollectionTestCase, self).setUp() memstore = MemoryStore() self.messages = MessageCollection("testmbox%s" % (self.count,), self._soledad, memstore=memstore) @@ -398,17 +141,17 @@ class MessageCollectionTestCase(IMAP4HelperMixin, unittest.TestCase): def add_first(): d = defer.gatherResults([ - mc.add_msg('Stuff 1', uid=1, subject="test1"), - mc.add_msg('Stuff 2', uid=2, subject="test2"), - mc.add_msg('Stuff 3', uid=3, subject="test3"), - mc.add_msg('Stuff 4', uid=4, subject="test4")]) + mc.add_msg('Stuff 1', subject="test1"), + mc.add_msg('Stuff 2', subject="test2"), + mc.add_msg('Stuff 3', subject="test3"), + mc.add_msg('Stuff 4', subject="test4")]) return d def add_second(result): d = defer.gatherResults([ - mc.add_msg('Stuff 5', uid=5, subject="test5"), - mc.add_msg('Stuff 6', uid=6, subject="test6"), - mc.add_msg('Stuff 7', uid=7, subject="test7")]) + mc.add_msg('Stuff 5', subject="test5"), + mc.add_msg('Stuff 6', subject="test6"), + mc.add_msg('Stuff 7', subject="test7")]) return d def check_second(result): @@ -418,7 +161,6 @@ class MessageCollectionTestCase(IMAP4HelperMixin, unittest.TestCase): d1.addCallback(add_second) d1.addCallback(check_second) - @skip("needs update!") def testRecentCount(self): """ Test the recent count @@ -429,20 +171,20 @@ class MessageCollectionTestCase(IMAP4HelperMixin, unittest.TestCase): self.assertEqual(countrecent(), 0) - d = mc.add_msg('Stuff', uid=1, subject="test1") + d = mc.add_msg('Stuff', subject="test1") # For the semantics defined in the RFC, we auto-add the # recent flag by default. def add2(_): - return mc.add_msg('Stuff', subject="test2", uid=2, + return mc.add_msg('Stuff', subject="test2", flags=('\\Deleted',)) def add3(_): - return mc.add_msg('Stuff', subject="test3", uid=3, + return mc.add_msg('Stuff', subject="test3", flags=('\\Recent',)) def add4(_): - return mc.add_msg('Stuff', subject="test4", uid=4, + return mc.add_msg('Stuff', subject="test4", flags=('\\Deleted', '\\Recent')) d.addCallback(lambda r: eq(countrecent(), 1)) @@ -461,9 +203,9 @@ class MessageCollectionTestCase(IMAP4HelperMixin, unittest.TestCase): self.assertEqual(self.messages.count(), 0) def add_1(): - d1 = mc.add_msg('msg 1', uid=1, subject="test1") - d2 = mc.add_msg('msg 2', uid=2, subject="test2") - d3 = mc.add_msg('msg 3', uid=3, subject="test3") + d1 = mc.add_msg('msg 1', subject="test1") + d2 = mc.add_msg('msg 2', subject="test2") + d3 = mc.add_msg('msg 3', subject="test3") d = defer.gatherResults([d1, d2, d3]) return d @@ -500,7 +242,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): # mailboxes operations # - @deferred(timeout=None) def testCreate(self): """ Test whether we can create mailboxes @@ -533,13 +274,11 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def _cbTestCreate(self, ignored, succeed, fail): self.assertEqual(self.result, [1] * len(succeed) + [0] * len(fail)) - mbox = LeapIMAPServer.theAccount.mailboxes - answers = ['foobox', 'testbox', 'test/box', 'test', 'test/box/box'] - mbox.sort() - answers.sort() - self.assertEqual(mbox, [a for a in answers]) + mboxes = list(LeapIMAPServer.theAccount.mailboxes) + answers = ([u'INBOX', u'foobox', 'test', u'test/box', + u'test/box/box', 'testbox']) + self.assertEqual(mboxes, [a for a in answers]) - @deferred(timeout=None) def testDelete(self): """ Test whether we can delete mailboxes @@ -559,7 +298,7 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d = defer.gatherResults([d1, d2]) d.addCallback( lambda _: self.assertEqual( - LeapIMAPServer.theAccount.mailboxes, [])) + LeapIMAPServer.theAccount.mailboxes, ['INBOX'])) return d def testIllegalInboxDelete(self): @@ -588,7 +327,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): failure.Failure))) return d - @deferred(timeout=None) def testNonExistentDelete(self): """ Test what happens if we try to delete a non-existent mailbox. @@ -614,13 +352,10 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): str(self.failure.value).startswith('No such mailbox'))) return d - @deferred(timeout=None) def testIllegalDelete(self): """ Try deleting a mailbox with sub-folders, and \NoSelect flag set. - An exception is expected - - Obs: this test will fail if SoledadMailbox returns hardcoded flags. + An exception is expected. """ LeapIMAPServer.theAccount.addMailbox('delete') to_delete = LeapIMAPServer.theAccount.getMailbox('delete') @@ -646,10 +381,11 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): expected = ("Hierarchically inferior mailboxes exist " "and \\Noselect is set") d.addCallback(lambda _: + self.assertTrue(self.failure is not None)) + d.addCallback(lambda _: self.assertEqual(str(self.failure.value), expected)) return d - @deferred(timeout=None) def testRename(self): """ Test whether we can rename a mailbox @@ -670,10 +406,9 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d.addCallback(lambda _: self.assertEqual( LeapIMAPServer.theAccount.mailboxes, - ['newname'])) + ['INBOX', 'newname'])) return d - @deferred(timeout=None) def testIllegalInboxRename(self): """ Try to rename inbox. We expect it to fail. Then it would be not @@ -701,7 +436,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): self.stashed, failure.Failure))) return d - @deferred(timeout=None) def testHierarchicalRename(self): """ Try to rename hierarchical mailboxes @@ -724,11 +458,9 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def _cbTestHierarchicalRename(self, ignored): mboxes = LeapIMAPServer.theAccount.mailboxes - expected = ['newname', 'newname/m1', 'newname/m2'] - mboxes.sort() + expected = ['INBOX', 'newname', 'newname/m1', 'newname/m2'] self.assertEqual(mboxes, [s for s in expected]) - @deferred(timeout=None) def testSubscribe(self): """ Test whether we can mark a mailbox as subscribed to @@ -750,7 +482,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): ['this/mbox'])) return d - @deferred(timeout=None) def testUnsubscribe(self): """ Test whether we can unsubscribe from a set of mailboxes @@ -775,7 +506,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): ['that/mbox'])) return d - @deferred(timeout=None) def testSelect(self): """ Try to select a mailbox @@ -804,8 +534,15 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def _cbTestSelect(self, ignored): mbox = LeapIMAPServer.theAccount.getMailbox('TESTMAILBOX-SELECT') self.assertEqual(self.server.mbox.messages.mbox, mbox.messages.mbox) + # XXX UIDVALIDITY should be "42" if the creation_ts is passed along + # to the memory store. However, the current state of the account + # implementation is incomplete and we're writing to soledad store + # directly there. We should handle the UIDVALIDITY timestamping + # mechanism in a separate test suite. + self.assertEqual(self.selectedArgs, { - 'EXISTS': 0, 'RECENT': 0, 'UIDVALIDITY': 42, + 'EXISTS': 0, 'RECENT': 0, 'UIDVALIDITY': 0, + # 'EXISTS': 0, 'RECENT': 0, 'UIDVALIDITY': 42, 'FLAGS': ('\\Seen', '\\Answered', '\\Flagged', '\\Deleted', '\\Draft', '\\Recent', 'List'), 'READ-WRITE': True @@ -815,7 +552,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): # capabilities # - @deferred(timeout=None) def testCapability(self): caps = {} @@ -827,11 +563,11 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d1 = self.connected.addCallback( strip(getCaps)).addErrback(self._ebGeneral) d = defer.gatherResults([self.loopback(), d1]) - expected = {'IMAP4rev1': None, 'NAMESPACE': None, 'IDLE': None} + expected = {'IMAP4rev1': None, 'NAMESPACE': None, 'LITERAL+': None, + 'IDLE': None} return d.addCallback(lambda _: self.assertEqual(expected, caps)) - @deferred(timeout=None) def testCapabilityWithAuth(self): caps = {} self.server.challengers[ @@ -848,7 +584,8 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d = defer.gatherResults([self.loopback(), d1]) expCap = {'IMAP4rev1': None, 'NAMESPACE': None, - 'IDLE': None, 'AUTH': ['CRAM-MD5']} + 'IDLE': None, 'LITERAL+': None, + 'AUTH': ['CRAM-MD5']} return d.addCallback(lambda _: self.assertEqual(expCap, caps)) @@ -856,7 +593,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): # authentication # - @deferred(timeout=None) def testLogout(self): """ Test log out @@ -871,7 +607,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d = self.loopback() return d.addCallback(lambda _: self.assertEqual(self.loggedOut, 1)) - @deferred(timeout=None) def testNoop(self): """ Test noop command @@ -887,7 +622,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d = self.loopback() return d.addCallback(lambda _: self.assertEqual(self.responses, [])) - @deferred(timeout=None) def testLogin(self): """ Test login @@ -904,7 +638,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): self.assertEqual(self.server.account, LeapIMAPServer.theAccount) self.assertEqual(self.server.state, 'auth') - @deferred(timeout=None) def testFailedLogin(self): """ Test bad login @@ -923,7 +656,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): self.assertEqual(self.server.state, 'unauth') self.assertEqual(self.server.account, None) - @deferred(timeout=None) def testLoginRequiringQuoting(self): """ Test login requiring quoting @@ -948,7 +680,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): # Inspection # - @deferred(timeout=None) def testNamespace(self): """ Test retrieving namespace @@ -973,7 +704,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): [[['', '/']], [], []])) return d - @deferred(timeout=None) def testExamine(self): """ L{IMAP4Client.examine} issues an I{EXAMINE} command to the server and @@ -989,9 +719,10 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): See U{RFC 3501<http://www.faqs.org/rfcs/rfc3501.html>}, section 6.3.2, for details. """ + # TODO implement the IMAP4ClientExamineTests testcase. + self.server.theAccount.addMailbox('test-mailbox-e', creation_ts=42) - self.examinedArgs = None def login(): @@ -1015,8 +746,15 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def _cbTestExamine(self, ignored): mbox = self.server.theAccount.getMailbox('test-mailbox-e') self.assertEqual(self.server.mbox.messages.mbox, mbox.messages.mbox) + + # XXX UIDVALIDITY should be "42" if the creation_ts is passed along + # to the memory store. However, the current state of the account + # implementation is incomplete and we're writing to soledad store + # directly there. We should handle the UIDVALIDITY timestamping + # mechanism in a separate test suite. self.assertEqual(self.examinedArgs, { - 'EXISTS': 0, 'RECENT': 0, 'UIDVALIDITY': 42, + 'EXISTS': 0, 'RECENT': 0, 'UIDVALIDITY': 0, + # 'EXISTS': 0, 'RECENT': 0, 'UIDVALIDITY': 42, 'FLAGS': ('\\Seen', '\\Answered', '\\Flagged', '\\Deleted', '\\Draft', '\\Recent', 'List'), 'READ-WRITE': False}) @@ -1043,7 +781,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): d2 = self.loopback() return defer.gatherResults([d1, d2]).addCallback(lambda _: self.listed) - @deferred(timeout=None) def testList(self): """ Test List command @@ -1060,7 +797,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): )) return d - @deferred(timeout=None) def testLSub(self): """ Test LSub command @@ -1074,7 +810,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): [(SoledadMailbox.INIT_FLAGS, "/", "root/subthingl2")]) return d - @deferred(timeout=None) def testStatus(self): """ Test Status command @@ -1106,7 +841,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): )) return d - @deferred(timeout=None) def testFailedStatus(self): """ Test failed status command with a non-existent mailbox @@ -1146,7 +880,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): # messages # - @deferred(timeout=None) def testFullAppend(self): """ Test appending a full message to the mailbox @@ -1197,7 +930,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): self.assertItemsEqual( headers, gotheaders) - @deferred(timeout=None) def testPartialAppend(self): """ Test partially appending a message to the mailbox @@ -1240,7 +972,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): body, msg.getBodyFile().read()) - @deferred(timeout=None) def testCheck(self): """ Test check command @@ -1264,7 +995,6 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): # Okay, that was fun - @deferred(timeout=5) def testClose(self): """ Test closing the mailbox. We expect to get deleted all messages flagged @@ -1283,13 +1013,13 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def add_messages(): d1 = m.messages.add_msg( - 'test 1', uid=1, subject="Message 1", + 'test 1', subject="Message 1", flags=('\\Deleted', 'AnotherFlag')) d2 = m.messages.add_msg( - 'test 2', uid=2, subject="Message 2", + 'test 2', subject="Message 2", flags=('AnotherFlag',)) d3 = m.messages.add_msg( - 'test 3', uid=3, subject="Message 3", + 'test 3', subject="Message 3", flags=('\\Deleted',)) d = defer.gatherResults([d1, d2, d3]) return d @@ -1307,15 +1037,14 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def _cbTestClose(self, ignored, m): self.assertEqual(len(m.messages), 1) - msg = m.messages.get_msg_by_uid(2) - self.assertFalse(msg is None) + self.assertTrue(msg is not None) + self.assertEqual( - msg._hdoc.content['subject'], + dict(msg.hdoc.content)['subject'], 'Message 2') self.failUnless(m.closed) - @deferred(timeout=5) def testExpunge(self): """ Test expunge command @@ -1332,13 +1061,13 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def add_messages(): d1 = m.messages.add_msg( - 'test 1', uid=1, subject="Message 1", + 'test 1', subject="Message 1", flags=('\\Deleted', 'AnotherFlag')) d2 = m.messages.add_msg( - 'test 2', uid=2, subject="Message 2", + 'test 2', subject="Message 2", flags=('AnotherFlag',)) d3 = m.messages.add_msg( - 'test 3', uid=3, subject="Message 3", + 'test 3', subject="Message 3", flags=('\\Deleted',)) d = defer.gatherResults([d1, d2, d3]) return d @@ -1364,94 +1093,36 @@ class LeapIMAP4ServerTestCase(IMAP4HelperMixin, unittest.TestCase): def _cbTestExpunge(self, ignored, m): # we only left 1 mssage with no deleted flag self.assertEqual(len(m.messages), 1) - msg = m.messages.get_msg_by_uid(2) + + msg = list(m.messages)[0] + self.assertTrue(msg is not None) + self.assertEqual( - msg._hdoc.content['subject'], + msg.hdoc.content['subject'], 'Message 2') + # the uids of the deleted messages self.assertItemsEqual(self.results, [1, 3]) -class StoreAndFetchTestCase(unittest.TestCase, IMAP4HelperMixin): +class AccountTestCase(IMAP4HelperMixin, unittest.TestCase): """ - Several tests to check that the internal storage representation - is able to render the message structures as we expect them. + Test the Account. """ - # TODO get rid of the fucking sleeps with a proper defer - # management. - - def setUp(self): - IMAP4HelperMixin.setUp(self) - MBOX_NAME = "multipart/SIGNED" - self.received_messages = self.received_uid = None - self.result = None - - self.server.state = 'select' - - infile = util.sibpath(__file__, 'rfc822.multi-signed.message') - raw = open(infile).read() - - self.server.theAccount.addMailbox(MBOX_NAME) - mbox = self.server.theAccount.getMailbox(MBOX_NAME) - time.sleep(1) - self.server.mbox = mbox - self.server.mbox.messages.add_msg(raw, uid=1) - time.sleep(1) - - def addListener(self, x): - pass - - def removeListener(self, x): - pass - - def _fetchWork(self, uids): + def _create_empty_mailbox(self): + LeapIMAPServer.theAccount.addMailbox('') - def result(R): - self.result = R + def _create_one_mailbox(self): + LeapIMAPServer.theAccount.addMailbox('one') - self.connected.addCallback( - lambda _: self.function( - uids, uid=1) # do NOT use seq numbers! - ).addCallback(result).addCallback( - self._cbStopClient).addErrback(self._ebGeneral) - - d = loopback.loopbackTCP(self.server, self.client, noisy=False) - d.addCallback(lambda x: self.assertEqual(self.result, self.expected)) - return d - - @deferred(timeout=None) - def testMultiBody(self): - """ - Test that a multipart signed message is retrieved the same - as we stored it. - """ - time.sleep(1) - self.function = self.client.fetchBody - messages = '1' - - # XXX review. This probably should give everything? - - self.expected = {1: { - 'RFC822.TEXT': 'This is an example of a signed message,\n' - 'with attachments.\n\n\n--=20\n' - 'Nihil sine chao! =E2=88=B4\n', - 'UID': '1'}} - print "test multi: fetch uid", messages - return self._fetchWork(messages) + def test_illegalMailboxCreate(self): + self.assertRaises(AssertionError, self._create_empty_mailbox) class IMAP4ServerSearchTestCase(IMAP4HelperMixin, unittest.TestCase): - """ Tests for the behavior of the search_* functions in L{imap5.IMAP4Server}. """ # XXX coming soon to your screens! pass - - -def tearDownModule(): - """ - Tear down functions for module level - """ - stop_reactor() diff --git a/mail/src/leap/mail/imap/tests/test_imap_store_fetch.py b/mail/src/leap/mail/imap/tests/test_imap_store_fetch.py new file mode 100644 index 0000000..6da8581 --- /dev/null +++ b/mail/src/leap/mail/imap/tests/test_imap_store_fetch.py @@ -0,0 +1,71 @@ +from twisted.protocols import loopback +from twisted.python import util + +from leap.mail.imap.tests.utils import IMAP4HelperMixin + +TEST_USER = "testuser@leap.se" +TEST_PASSWD = "1234" + + +class StoreAndFetchTestCase(IMAP4HelperMixin): + """ + Several tests to check that the internal storage representation + is able to render the message structures as we expect them. + """ + + def setUp(self): + IMAP4HelperMixin.setUp(self) + self.received_messages = self.received_uid = None + self.result = None + + def addListener(self, x): + pass + + def removeListener(self, x): + pass + + def _addSignedMessage(self, _): + self.server.state = 'select' + infile = util.sibpath(__file__, 'rfc822.multi-signed.message') + raw = open(infile).read() + MBOX_NAME = "multipart/SIGNED" + + self.server.theAccount.addMailbox(MBOX_NAME) + mbox = self.server.theAccount.getMailbox(MBOX_NAME) + self.server.mbox = mbox + # return a deferred that will fire with UID + return self.server.mbox.messages.add_msg(raw) + + def _fetchWork(self, uids): + + def result(R): + self.result = R + + self.connected.addCallback( + self._addSignedMessage).addCallback( + lambda uid: self.function( + uids, uid=uid) # do NOT use seq numbers! + ).addCallback(result).addCallback( + self._cbStopClient).addErrback(self._ebGeneral) + + d = loopback.loopbackTCP(self.server, self.client, noisy=False) + d.addCallback(lambda x: self.assertEqual(self.result, self.expected)) + return d + + def testMultiBody(self): + """ + Test that a multipart signed message is retrieved the same + as we stored it. + """ + self.function = self.client.fetchBody + messages = '1' + + # XXX review. This probably should give everything? + + self.expected = {1: { + 'RFC822.TEXT': 'This is an example of a signed message,\n' + 'with attachments.\n\n\n--=20\n' + 'Nihil sine chao! =E2=88=B4\n', + 'UID': '1'}} + # print "test multi: fetch uid", messages + return self._fetchWork(messages) diff --git a/mail/src/leap/mail/imap/tests/utils.py b/mail/src/leap/mail/imap/tests/utils.py new file mode 100644 index 0000000..0932bd4 --- /dev/null +++ b/mail/src/leap/mail/imap/tests/utils.py @@ -0,0 +1,225 @@ +import os +import tempfile +import shutil + +from email import parser + +from mock import Mock +from twisted.mail import imap4 +from twisted.internet import defer +from twisted.protocols import loopback + +from leap.common.testing.basetest import BaseLeapTest +from leap.mail.imap.account import SoledadBackedAccount +from leap.mail.imap.memorystore import MemoryStore +from leap.mail.imap.server import LeapIMAPServer +from leap.soledad.client import Soledad + +TEST_USER = "testuser@leap.se" +TEST_PASSWD = "1234" + +# +# Simple IMAP4 Client for testing +# + + +class SimpleClient(imap4.IMAP4Client): + + """ + A Simple IMAP4 Client to test our + Soledad-LEAPServer + """ + + def __init__(self, deferred, contextFactory=None): + imap4.IMAP4Client.__init__(self, contextFactory) + self.deferred = deferred + self.events = [] + + def serverGreeting(self, caps): + self.deferred.callback(None) + + def modeChanged(self, writeable): + self.events.append(['modeChanged', writeable]) + self.transport.loseConnection() + + def flagsChanged(self, newFlags): + self.events.append(['flagsChanged', newFlags]) + self.transport.loseConnection() + + def newMessages(self, exists, recent): + self.events.append(['newMessages', exists, recent]) + self.transport.loseConnection() + + +def initialize_soledad(email, gnupg_home, tempdir): + """ + Initializes soledad by hand + + :param email: ID for the user + :param gnupg_home: path to home used by gnupg + :param tempdir: path to temporal dir + :rtype: Soledad instance + """ + + uuid = "foobar-uuid" + passphrase = u"verysecretpassphrase" + secret_path = os.path.join(tempdir, "secret.gpg") + local_db_path = os.path.join(tempdir, "soledad.u1db") + server_url = "http://provider" + cert_file = "" + + class MockSharedDB(object): + + get_doc = Mock(return_value=None) + put_doc = Mock() + lock = Mock(return_value=('atoken', 300)) + unlock = Mock(return_value=True) + + def __call__(self): + return self + + Soledad._shared_db = MockSharedDB() + + _soledad = Soledad( + uuid, + passphrase, + secret_path, + local_db_path, + server_url, + cert_file) + + return _soledad + + +# XXX this is not properly a mixin, since helper already inherits from +# uniittest.Testcase +class IMAP4HelperMixin(BaseLeapTest): + """ + MixIn containing several utilities to be shared across + different TestCases + """ + + serverCTX = None + clientCTX = None + + # setUpClass cannot be a classmethod in trial, see: + # https://twistedmatrix.com/trac/ticket/1870 + + def setUp(self): + """ + Setup method for each test. + + Initializes and run a LEAP IMAP4 Server, + but passing the same Soledad instance (it's costly to initialize), + so we have to be sure to restore state across tests. + """ + self.old_path = os.environ['PATH'] + self.old_home = os.environ['HOME'] + self.tempdir = tempfile.mkdtemp(prefix="leap_tests-") + self.home = self.tempdir + bin_tdir = os.path.join( + self.tempdir, + 'bin') + os.environ["PATH"] = bin_tdir + os.environ["HOME"] = self.tempdir + + # Soledad: config info + self.gnupg_home = "%s/gnupg" % self.tempdir + self.email = 'leap@leap.se' + + # initialize soledad by hand so we can control keys + self._soledad = initialize_soledad( + self.email, + self.gnupg_home, + self.tempdir) + UUID = 'deadbeef', + USERID = TEST_USER + memstore = MemoryStore() + + ########### + + d = defer.Deferred() + self.server = LeapIMAPServer( + uuid=UUID, userid=USERID, + contextFactory=self.serverCTX, + # XXX do we really need this?? + soledad=self._soledad) + + self.client = SimpleClient(d, contextFactory=self.clientCTX) + self.connected = d + + # XXX REVIEW-ME. + # We're adding theAccount here to server + # but it was also passed to initialization + # as it was passed to realm. + # I THINK we ONLY need to do it at one place now. + + theAccount = SoledadBackedAccount( + USERID, + soledad=self._soledad, + memstore=memstore) + LeapIMAPServer.theAccount = theAccount + + # in case we get something from previous tests... + for mb in self.server.theAccount.mailboxes: + self.server.theAccount.delete(mb) + + # email parser + self.parser = parser.Parser() + + def tearDown(self): + """ + tearDown method called after each test. + + Deletes all documents in the Index, and deletes + instances of server and client. + """ + try: + self._soledad.close() + os.environ["PATH"] = self.old_path + os.environ["HOME"] = self.old_home + # safety check + assert 'leap_tests-' in self.tempdir + shutil.rmtree(self.tempdir) + except Exception: + print "ERROR WHILE CLOSING SOLEDAD" + + def populateMessages(self): + """ + Populates soledad instance with several simple messages + """ + # XXX we should encapsulate this thru SoledadBackedAccount + # instead. + + # XXX we also should put this in a mailbox! + + self._soledad.messages.add_msg('', subject="test1") + self._soledad.messages.add_msg('', subject="test2") + self._soledad.messages.add_msg('', subject="test3") + # XXX should change Flags too + self._soledad.messages.add_msg('', subject="test4") + + def delete_all_docs(self): + """ + Deletes all the docs in the testing instance of the + SoledadBackedAccount. + """ + self.server.theAccount.deleteAllMessages( + iknowhatiamdoing=True) + + def _cbStopClient(self, ignore): + self.client.transport.loseConnection() + + def _ebGeneral(self, failure): + self.client.transport.loseConnection() + self.server.transport.loseConnection() + # can we do something similar? + # I guess this was ok with trial, but not in noseland... + # log.err(failure, "Problem with %r" % (self.function,)) + raise failure.value + # failure.trap(Exception) + + def loopback(self): + return loopback.loopbackAsync(self.server, self.client) + + diff --git a/mail/src/leap/mail/smtp/gateway.py b/mail/src/leap/mail/smtp/gateway.py index ef398d1..13d3bbf 100644 --- a/mail/src/leap/mail/smtp/gateway.py +++ b/mail/src/leap/mail/smtp/gateway.py @@ -463,13 +463,13 @@ class EncryptedMessage(object): """ Sends the message. - :return: A deferred with callbacks for error and success of this - #message send. + :return: A deferred with callback and errback for + this #message send. :rtype: twisted.internet.defer.Deferred """ d = deferToThread(self._route_msg) d.addCallbacks(self.sendQueued, self.sendError) - return + return d def _route_msg(self): """ diff --git a/mail/src/leap/mail/smtp/tests/__init__.py b/mail/src/leap/mail/smtp/tests/__init__.py index 1459cea..dc24293 100644 --- a/mail/src/leap/mail/smtp/tests/__init__.py +++ b/mail/src/leap/mail/smtp/tests/__init__.py @@ -21,6 +21,7 @@ Base classes and keys for SMTP gateway tests. """ import os +import distutils.spawn import shutil import tempfile from mock import Mock @@ -39,9 +40,14 @@ from leap.keymanager import ( from leap.common.testing.basetest import BaseLeapTest +def _find_gpg(): + gpg_path = distutils.spawn.find_executable('gpg') + return os.path.realpath(gpg_path) if gpg_path is not None else "/usr/bin/gpg" + + class TestCaseWithKeyManager(BaseLeapTest): - GPG_BINARY_PATH = '/usr/bin/gpg' + GPG_BINARY_PATH = _find_gpg() def setUp(self): # mimic BaseLeapTest.setUpClass behaviour, because this is deprecated @@ -148,7 +154,7 @@ class TestCaseWithKeyManager(BaseLeapTest): os.environ["PATH"] = self.old_path os.environ["HOME"] = self.old_home # safety check - assert self.tempdir.startswith('/tmp/leap_tests-') + assert 'leap_tests-' in self.tempdir shutil.rmtree(self.tempdir) diff --git a/mail/src/leap/mail/smtp/tests/test_gateway.py b/mail/src/leap/mail/smtp/tests/test_gateway.py index 88ee5f7..466677f 100644 --- a/mail/src/leap/mail/smtp/tests/test_gateway.py +++ b/mail/src/leap/mail/smtp/tests/test_gateway.py @@ -23,13 +23,9 @@ SMTP gateway tests. import re from datetime import datetime -from gnupg._util import _make_binary_stream from twisted.test import proto_helpers -from twisted.mail.smtp import ( - User, - Address, - SMTPBadRcpt, -) +from twisted.mail.smtp import User, Address + from mock import Mock from leap.mail.smtp.gateway import ( @@ -137,7 +133,7 @@ class TestSmtpGateway(TestCaseWithKeyManager): self._config['port'], self._config['cert'], self._config['key']) for line in self.EMAIL_DATA[4:12]: m.lineReceived(line) - #m.eomReceived() # this includes a defer, so we avoid calling it here + # m.eomReceived() # this includes a defer, so we avoid calling it here m.lines.append('') # add a trailing newline # we need to call the following explicitelly because it was deferred # inside the previous method @@ -181,7 +177,7 @@ class TestSmtpGateway(TestCaseWithKeyManager): for line in self.EMAIL_DATA[4:12]: m.lineReceived(line) # trigger encryption and signing - #m.eomReceived() # this includes a defer, so we avoid calling it here + # m.eomReceived() # this includes a defer, so we avoid calling it here m.lines.append('') # add a trailing newline # we need to call the following explicitelly because it was deferred # inside the previous method @@ -229,7 +225,7 @@ class TestSmtpGateway(TestCaseWithKeyManager): for line in self.EMAIL_DATA[4:12]: m.lineReceived(line) # trigger signing - #m.eomReceived() # this includes a defer, so we avoid calling it here + # m.eomReceived() # this includes a defer, so we avoid calling it here m.lines.append('') # add a trailing newline # we need to call the following explicitelly because it was deferred # inside the previous method |