Permalink
Browse files

Improve documentation

* Document how to use IDLE
* Write a note about thread safety
* Split installation into its own page
* Simplify a bit the README
* Mention that `backports.ssl` is just a compatibility layer
  • Loading branch information...
NicolasLM committed Sep 5, 2017
1 parent 84e2332 commit 528ae666abe401a3545fc910036e98f8633efa1a
Showing with 102 additions and 61 deletions.
  1. +8 −7 README.rst
  2. +22 −3 doc/src/advanced.rst
  3. +23 −20 doc/src/concepts.rst
  4. +9 −7 doc/src/contributing.rst
  5. +10 −2 doc/src/index.rst
  6. +30 −0 doc/src/installation.rst
  7. +0 −22 doc/src/quickstart.rst
View
@@ -64,18 +64,17 @@ point in the future.
Installing IMAPClient
---------------------
IMAPClient is listed on the PyPI (Python Package Index). To install
via PyPI use the pip or easy_install tools::
IMAPClient is listed on PyPI and can be installed with pip::
pip install imapclient
easy_install IMAPClient
More installation methods are described in the documentation.
Documentation
-------------
IMAPClient's manual is available at http://imapclient.readthedocs.io/. Release notes can be found at http://imapclient.readthedocs.io/#release-history.
IMAPClient's manual is available at http://imapclient.readthedocs.io/.
Release notes can be found at
http://imapclient.readthedocs.io/#release-history.
The Sphinx source for the documentation can be found under doc/src. If
Sphinx is installed, the documentation can be rebuilt using::
@@ -133,8 +132,10 @@ inbox@menno.io.
Working on IMAPClient
---------------------
The HACKING.rst document contains information for those interested in
improving IMAPClient and contributing back to the project.
The `contributing documentation
<http://imapclient.readthedocs.io/en/master/contributing.html>`_. contains
information for those interested in improving IMAPClient and contributing back
to the project.
IMAP Servers
------------
View
@@ -30,9 +30,23 @@ connections when they are not needed anymore::
c.login("bar@foo.org", "passwd")
c.select_folder("INBOX")
Watching a mailbox asynchronously using idle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TODO
Watching a mailbox using idle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The IDLE extension allows an IMAP server to notify a client when something
changes in a mailbox. It can be used as an alternative to polling to receive
new messages.
The concept is simple: the client connects to the server, selects a mailbox and
enters the IDLE mode. At this point the server sends notifications whenever
something happens in the selected mailbox until the client ends the IDLE mode
by issuing a `DONE` command. This is explained in :rfc:`2177`.
.. literalinclude:: ../../examples/idle_example.py
Note that IMAPClient does not handle low-level socket errors that can happen
when maintaining long-lived TCP connections. Users are advised to renew the
IDLE command every 10 minutes to avoid the connection from being abruptly
closed.
Handling large mailboxes
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -136,3 +150,8 @@ 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.
Thread Safety
~~~~~~~~~~~~~
Instances of IMAPClient are NOT thread safe. They should not be shared and
accessed concurrently from multiple threads.
View
@@ -72,26 +72,29 @@ folder names are returned as str (Python 2) or bytes (Python 3).
TLS/SSL
~~~~~~~
IMAPClient uses sensible TLS parameter defaults for encrypted
connections and also allows for a high level of control of TLS
parameters if required. To provide a consistent API and capabilities
across Python versions the `backports.ssl <https://github.com/alekstorm/backports.ssl>`_
library is used instead of the standard library ssl
package. backports.ssl provides an API that aims to mimic the Python
3.4 ssl package so it should be familiar to developers that have used
the ssl package in recent versions of Python.
TLS parameters are controlled by passing a ``backports.ssl.SSLContext``
when creating an IMAPClient instance. When ``ssl=True`` is used
without passing a SSLContext, a default context is used. The default
context avoids the use of known insecure ciphers and SSL protocol
versions, with certificate verification and hostname verification
turned on. The default context will use system installed certificate
authority trust chains, if available.
:py:func:`IMAPClient.tls.create_default_context` returns IMAPClient's
default context. When constructing a custom context it is usually best
to start with the default context and modify it to suit your needs.
IMAPClient established secure connections by default. It uses sensible TLS
parameters for encrypted connections and also allows for a high level of
control of TLS parameters if required, with the ``ssl`` module.
.. note::
For older versions of Python which do not provide a recent enough ``ssl``
module, IMAPClient installs `backports.ssl
<https://github.com/alekstorm/backports.ssl>`_ as a compatibility layer.
You are highly encouraged to use a recent version of Python if security is
of prime importance for you.
TLS parameters are controlled by passing an ``ssl.SSLContext`` (or
``backports.ssl.SSLContext`` when appropriate) when creating an IMAPClient
instance. When ``ssl=True`` is used without passing a SSLContext, a default
context is used. The default context avoids the use of known insecure ciphers
and SSL protocol versions, with certificate verification and hostname
verification turned on. The default context will use system installed
certificate authority trust chains, if available.
:py:func:`ssl.create_default_context()` returns a safe default context. When
constructing a custom context it is usually best to start with the default
context and modify it to suit your needs.
The following example shows how to to disable certification
verification and certificate host name checks if required.
View
@@ -18,7 +18,7 @@ Please read on if you plan on submitting changes to IMAPClient.
Source Code
~~~~~~~~~~~
The official source code repository for IMAPClient can be found on
Github at: https://github.com/mjs/imapclient/
Github at: https://github.com/mjs/imapclient
Any major feature work will also be found as branches of this
repository.
@@ -67,12 +67,14 @@ script (for Unix-like systems) or the unit2.py script::
unit2 discover
unit2.py discover
Running the Unit Tests Against Multiple Python Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to run the unit tests against all supported Python
versions at once using `tox`_. Once installed, the ``tox`` command
will use the tox.ini file in the root of the source directory and run
the unit tests against the Python versions officially supported by
Testing Against Multiple Python Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When submitting a Pull Request to IMAPClient, tests are automatically ran
against all the supported Python versions.
It is possible to locally run these tests using `tox`_. Once installed, the
``tox`` command will use the tox.ini file in the root of the source directory
and run the unit tests against the Python versions officially supported by
IMAPClient (provided these versions of Python are installed!).
.. _`tox`: http://testrun.org/tox/
View
@@ -32,8 +32,15 @@ where relevant.
Python versions 2.7, 3.4, 3.5 and 3.6 are officially supported.
A Simple Example
----------------
Getting Started
---------------
Install IMAPClient::
$ pip install imapclient
See :ref:`Installation <installation>` for more details.
The core of the IMAPClient API is the IMAPClient class. Instantiating
this class, creates a connection to an IMAP account. Calling methods
on the IMAPClient instance interacts with the server.
@@ -77,6 +84,7 @@ help you start.
.. toctree::
:maxdepth: 2
installation
quickstart
concepts
advanced
View
@@ -0,0 +1,30 @@
.. _installation:
Installation
------------
Pip
~~~
IMAPClient can easily be installed with pip::
$ pip install imapclient
From Source
~~~~~~~~~~~
IMAPClient is developed on GitHub, you can find the code at `mjs/imapclient
<https://github.com/mjs/imapclient>`_.
You can clone the public repository::
$ git clone https://github.com/mjs/imapclient.git
Once you have the sources, simply install IMAPClient with::
$ cd imapclient
$ pip install -e .
Other versions
~~~~~~~~~~~~~~
The source distributions of all IMAPClient versions are available at
http://menno.io/projects/IMAPClient/. Alternatively you can also use
the PyPI page at https://pypi.python.org/pypi/IMAPClient/.
View
@@ -1,28 +1,6 @@
Quickstart
----------
Installing IMAPClient
~~~~~~~~~~~~~~~~~~~~~
`imapclient` is listed on the PyPi. The easiest way to install it is to
use `pip` or `easy_install`::
$ pip install imapclient
# or
$ easy_install IMAPClient
The source distributions of all IMAPClient versions are available at
http://menno.io/projects/IMAPClient/. Alternatively you can also use
the PyPI page at https://pypi.python.org/pypi/IMAPClient/.
To install from source run::
python setup.py install
The project is packaged using Distribute (mostly compatible with
setuptools) and all the usual setup.py installation options are
available. See http://packages.python.org/distribute/ for more info.
Connect to a server and send our first commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0 comments on commit 528ae66

Please sign in to comment.