Merged stable into default

Author: Menno Smits

NEWS.rst

@@ -2,6 +2,6 @@ IMAPClient's release history is now part of the main
 documentation_. See the `release documentation`_ on `Read the Docs`_ for
 the most up-to-date details of IMAPClient's releases.
 
-.. _documentation: http://imapclient.readthedocs.org/en/latest/
-.. _release documentation: http://imapclient.readthedocs.org/en/latest/releases.html
+.. _documentation: http://imapclient.readthedocs.io/en/latest/
+.. _release documentation: http://imapclient.readthedocs.io/en/latest/releases.html
 .. _Read the Docs: http://readthedocs.org

README.rst

@@ -17,7 +17,7 @@ Features:
 - Convenience methods are provided for commonly used functionality.
 - Exceptions are raised when errors occur.
 
-Python versions 2.6, 2.7, 3.3 and 3.4 are officially supported.
+Python versions 2.6, 2.7, 3.3, 3.4 and 3.5 are officially supported.
 
 The current stable version of IMAPClient is 1.0.1. It is licensed
 under the New BSD License.
@@ -63,7 +63,7 @@ available. See http://packages.python.org/distribute/ for more info.
 
 Documentation
 -------------
-IMAPClient's manual is available at http://imapclient.readthedocs.org/
+IMAPClient's manual is available at http://imapclient.readthedocs.io/
 
 The `NEWS <https://bitbucket.org/mjs0/imapclient/src/tip/NEWS.rst>`_
 file also has useful information.
@@ -159,12 +159,13 @@ compatibility with a given IMAP server implementation.
 
 The livetest functionality can also be accessed like this::
 
-    python -m imapclient.livetest ...
+    python -m imapclient.livetest <livetest.ini> [ optional unittest arguments ]
 
 Alternatively you can run the ``livetest.py`` script included with the
-source distribution.
+source distribution. Use ``livetest.py --help`` to see usage.
 
-Use the --help option to see usage.
+The configuration file format is
+`described in the main documentation <http://imapclient.rtfd.io/#configuration-file-format>`_.
 
 **WARNING**: The operations used by livetest are destructive and could
 cause unintended loss of data. That said, as of version 0.9, livetest

doc/src/index.rst

@@ -7,7 +7,7 @@
 :Date: |today|
 :Homepage: http://imapclient.freshfoo.com
 :Download: http://pypi.python.org/pypi/IMAPClient/
-:Documentation: http://imapclient.readthedocs.org/
+:Documentation: http://imapclient.readthedocs.io/
 :License: `New BSD License <http://en.wikipedia.org/wiki/BSD_licenses>`_
 :Support: `Mailing List <https://groups.io/g/imapclient>`_
 
@@ -175,6 +175,18 @@ The above examples show some of the most common TLS parameter
 customisations but there are many other tweaks are possible. Consult
 the Python 3 :py:mod:`ssl` package documentation for further options.
 
+Old pyOpenSSL Versions
++++++++++++++++++++++++
+
+IMAPClient's TLS functionality will not behaviour correctly if an
+out-of-date version of pyOpenSSL is used. On some systems
+(particularly OS X) the system installed version of pyOpenSSL will
+take precedence over any user installed version. Use of virtualenvs is
+strongly encouraged to work around this.
+
+IMAPClient checks the installed pyOpenSSL version at import time and
+will fail early if an old pyOpenSSL version is found.
+
 Using gevent with IMAPClient
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Some extra monkey patching is required so that the gevent_ package can
@@ -261,12 +273,18 @@ Various options are available to specify the IMAP server details. See
 the help (--help) for more details. You'll be prompted for a username
 and password if one isn't provided on the command line.
 
-The connected IMAPClient instance is available as the variable "c".
+It is also possible to pass connection details as a configuration file
+like this::
+
+   python -m imapclient.interact -f <config file>
+
+See below for details of the :ref:`configuration file format<conf-files>`.
 
 If installed, IPython will be used as the embedded shell. Otherwise
 the basic built-in Python shell will be used.
 
-Here's an example session::
+The connected IMAPClient instance is available as the variable
+"c". Here's an example session::
 
     $ python -m imapclient.interact -H <host> -u <user> ...
     Connecting...
@@ -297,6 +315,48 @@ Here's an example session::
     In [3]: c.logout()
     Out[3]: b'Logging out'
 
+.. _conf-files:
+
+Configuration File Format
+-------------------------
+Both the IMAPClient interactive shell and the live tests take
+configuration files which specify how to to connect to an IMAP
+server. The configuration file format is the same for both.
+
+Configuration files use the INI format and must always have a section
+called ``DEFAULT``. Here's a simple example::
+
+    [DEFAULT]
+    host = imap.mailserver.com
+    username = bob
+    password = sekret
+    ssl = True
+
+The supported options are:
+
+==================== ======= =========================================================================================
+Name                 Type    Description
+==================== ======= =========================================================================================
+host                 string  IMAP hostname to connect to.
+username             string  The username to authenticate as.
+password             string  The password to use with ``username``.
+port                 int     Server port to connect to. Defaults to 143 unless ``ssl`` is True.
+ssl                  bool    Use SSL/TLS to connect.
+starttls             bool    Use STARTTLS to connect.
+ssl_check_hostname   bool    If true and SSL is in use, check that certificate matches the hostname (defaults to true)
+ssl_verify_cert      bool    If true and SSL is in use, check that the certifcate is valid (defaults to true).
+ssl_ca_file          string  If SSL is true, use this to specify certificate authority certs to validate with.
+timeout              int     Time out I/O operations after this many seconds.
+oauth2               bool    If true, use OAUTH2 to authenticate (``username`` and ``password`` are ignored).
+oauth2_client_id     string  OAUTH2 client id.
+oauth2_client_secret string  OAUTH2 client secret.
+oauth2_refresh_token string  OAUTH2 token for refreshing the secret.
+==================== ======= =========================================================================================
+
+Acceptable boolean values are "1", "yes", "true", and "on", for true;
+and "0", "no", "false", and "off", for false.
+
+
 External Documentation
 ----------------------
 The `Unofficial IMAP Protocol Wiki <http://www.imapwiki.org/>`_ is

doc/src/releases.rst

@@ -8,6 +8,24 @@ Added
 -----
 - PLAIN authentication support (via `plain_login` method)
 
+===============
+ Version 1.0.2
+===============
+
+New
+---
+- Documented the livetest/interact INI file format.
+
+Changed
+-------
+- Explicitly check that the required pyOpenSSL version is installed
+- Start testing against Python 3.5
+- Update doc links from readthedocs.org to readthedocs.io
+
+Fixed
+-----
+- Allow installation from alternate directories
+
 ===============
  Version 1.0.1
 ===============
@@ -69,7 +87,7 @@ on all of the above.
 Many thanks to Chris Arndt and Marc-Antoine Parent for their input
 into these TLS improvements.
 
-.. _Exceptions: http://imapclient.readthedocs.org/en/latest/#exceptions
+.. _Exceptions: http://imapclient.readthedocs.io/en/latest/#exceptions
 
 STARTTLS support [NEW]
 ----------------------
@@ -533,7 +551,7 @@ responses in the same format as idle_check() and idle_done().
 Sphinx Based Docs (#5) [NEW]
 ----------------------------
 Full documentation is now available under doc/html in the source
-distribution and at http://imapclient.readthedocs.org/ online.
+distribution and at http://imapclient.readthedocs.io/ online.
 
 Added rename_folder (#77) [NEW] 
 --------------------------------

imapclient/tls.py

@@ -11,19 +11,37 @@
 """
 
 import imaplib
+import os
 import socket
 import sys
 
+__all__ = ('create_default_context',)
+
+# Explicitly check that the required pyOpenSSL is installed. On some
+# systems (particularly OS X) the system installed version will be
+# seen before any user installed version. Using a virtualenv is
+# recommended to work around this.
+def check_pyopenssl_version():
+    from distutils.version import LooseVersion as V
+    from OpenSSL import __version__ as installed_pyopenssl_version
+    from .version import min_pyopenssl_version
+
+    if V(installed_pyopenssl_version) < V(min_pyopenssl_version):
+       raise ImportError(
+           "pyOpenSSL version (%s) is too old. Need at least %s.\n"
+           "See http://imapclient.rtfd.io/#old-pyopenssl-versions"
+           % (installed_pyopenssl_version, min_pyopenssl_version))
+
+if os.environ.get("READTHEDOCS") != "True":
+    check_pyopenssl_version()
+
 try:
     from backports import ssl
 except ImportError:
     raise ImportError("backports.ssl is not installed")
 
-__all__ = ('create_default_context',)
-
 _ossl = ssl.ossl
 
-
 if sys.platform == "win32":
     try:
         from ssl import enum_certificates, Purpose

imapclient/version.py

@@ -4,7 +4,7 @@
 
 from __future__ import unicode_literals
 
-version_info = (1, 0, 1, 'final')
+version_info = (1, 0, 2, 'alpha')
 
 
 def _imapclient_version_string(vinfo):
@@ -17,3 +17,5 @@ def _imapclient_version_string(vinfo):
 version = _imapclient_version_string(version_info)
 author = 'Menno Smits'
 author_email = '[email protected]'
+
+min_pyopenssl_version = '0.15.1'

setup.py

@@ -20,7 +20,8 @@
 IS_PY_34_OR_NEWER = MAJ_MIN >= (3, 4)
 
 # Read version info
-version_file = path.join('imapclient', 'version.py')
+here = path.dirname(__file__)
+version_file = path.join(here, 'imapclient', 'version.py')
 info = {}
 if IS_PY3:
     exec(open(version_file).read(), {}, info)
@@ -65,7 +66,7 @@ def run_tests(self):
 
 main_deps = [
     'backports.ssl>=0.0.9',
-    'pyopenssl>=0.15.1',
+    'pyopenssl>=' + info["min_pyopenssl_version"],
     'six',
     'mock==1.3.0'
 ]

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist=py26,py27,py33,py34
+envlist=py26,py27,py33,py34,py35
 
 # The tests are currently run directly out of the source tree.
 # See the notes in build-sdist for more details.