Permalink
Browse files

Merge pull request #329 from mjs/doc-tweaks

Documentation improvements
  • Loading branch information...
mjs committed Jan 11, 2018
2 parents 6068368 + 2314606 commit f2f27e5cd6fe83ec68ba8087fb74930727ac4159
View
@@ -1,9 +1,11 @@
IMAPClient was created by Menno Finlay-Smits <inbox@menno.io>. The
project is now Nicolas Le Manchet and Menno Finlay-Smits.
project is now maintained by Nicolas Le Manchet and Menno
Finlay-Smits.
Many thanks go to the following people for their help with this
project:
- Maxime Lorant
- Mathieu Agopian
- Chris Arndt
- Jp Calderone
@@ -14,7 +16,6 @@ project:
- Mark Hammond
- Johannes Heckel
- Thomas Jost
- Maxime Lorant
- Lukasz Mierzwa
- Naveen Nathan
- Brian Neal
View
@@ -7,9 +7,9 @@ library.
Current version 1.1.0
Supported Python versions 2.7, 3.4, 3.5 and 3.6
License New BSD
Project home http://imapclient.freshfoo.com/
Project home https://github.com/mjs/imapclient/
PyPI https://pypi.python.org/pypi/IMAPClient
Documentation http://imapclient.readthedocs.io/
Documentation https://imapclient.readthedocs.io/
Mailing list https://groups.io/g/imapclient
========================= ========================================
@@ -44,6 +44,33 @@ Features
- Convenience methods are provided for commonly used functionality.
- Exceptions are raised when errors occur.
Example
-------
.. code-block:: python
from imapclient import IMAPClient
# context manager ensures the session is cleaned up
with IMAPClient(host="imap.host.org") as client:
client.login('someone', 'secret')
client.select_folder('INBOX')
# search criteria are passed in a straightforward way
# (nesting is supported)
messages = client.search(['NOT', 'DELETED'])
# fetch selectors are passed as a simple list of strings.
response = client.fetch(messages, ['FLAGS', 'RFC822.SIZE'])
# `response` is keyed by message id and contains parsed,
# converted response items.
for message_id, data in response.items():
print('{id}: {size} bytes, flags={flags}'.format(
id=message_id,
size=data[b'RFC822.SIZE'],
flags=data[b'FLAGS']))
Why IMAPClient?
---------------
You may ask: "why create another IMAP client library for Python?
@@ -53,7 +80,7 @@ The problem with imaplib is that it's very low-level. It expects
string values where lists or tuples would be more appropriate and
returns server responses almost unparsed. As IMAP server responses can
be quite complex this means everyone using imaplib ends up writing
their own flimsy parsing routines which break easily.
their own fragile parsing routines.
Also, imaplib doesn't make good use of exceptions. This means you need
to check the return value of each call to imaplib to see if what you
@@ -76,39 +103,25 @@ 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::
python setup.py build_sphinx
See the imapclient/examples directory for examples of how to use
IMAPClient. If the IMAPClient was installed from PyPI, the examples
subdirectory can be found under the imapclient package in the
installation directory.
See the `examples` directory in the root of project source for
examples of how to use IMAPClient.
Current Status
--------------
IMAPClient is currently under development but it is unlikely that
the existing API will change in backwards-incompatible ways. Changes
planned for the near future will only add extra functionality to the
API.
You should feel confident using IMAPClient for production
purposes. Any problems found will be fixed quickly once reported.
The project's home page is http://imapclient.freshfoo.com/ (this
In order to clearly communicate version compatibility, IMAPClient
will strictly adhere to the `Semantic Versioning <http://semver.org>`_
scheme from version 1.0 onwards.
The project's home page is https://github.com/mjs/imapclient/ (this
currently redirects to the IMAPClient Github site). Details about
upcoming versions and planned features/fixes can be found in the issue
tracker on Github. The maintainer also blogs about IMAPClient
tracker on Github. The maintainers also blog about IMAPClient
news. Those articles can be found `here
<http://menno.io/tags/imapclient>`_.
Versions
--------
In order to clearly communicate version compatibility, IMAPClient
will strictly adhere to the `Semantic Versioning <http://semver.org>`_
scheme from version 1.0 onwards.
Mailing List
------------
The IMAPClient mailing list can be used to ask IMAPClient related
@@ -133,9 +146,8 @@ inbox@menno.io.
Working on IMAPClient
---------------------
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.
<http://imapclient.rtfd.io/en/master/contributing.html>`_ contains
information for those interested in improving IMAPClient.
IMAP Servers
------------
@@ -162,16 +174,14 @@ interact module like this::
"Live" Tests
------------
IMAPClient includes a series of functional tests which exercise
it against a live IMAP account. It is useful for ensuring
IMAPClient includes a series of live, functional tests which exercise
it against a live IMAP account. These are useful for ensuring
compatibility with a given IMAP server implementation.
The livetest functionality can also be accessed like this::
python -m imapclient.livetest <livetest.ini> [ optional unittest arguments ]
The livetest functionality are run from the root of the project source
like this::
Alternatively you can run the ``livetest.py`` script included with the
source distribution. Use ``livetest.py --help`` to see usage.
python livetest.py <livetest.ini> [ optional unittest arguments ]
The configuration file format is
`described in the main documentation <http://imapclient.rtfd.io/#configuration-file-format>`_.
View
@@ -22,15 +22,15 @@ However if an error is raised when selecting the folder, the connection may be
left open.
IMAPClient may be used as a context manager that automatically closes
connections when they are not needed anymore::
connections when they are not needed any more::
import imapclient
with imapclient.IMAPClient(host="imap.foo.org") as c:
c.login("bar@foo.org", "passwd")
c.select_folder("INBOX")
Watching a mailbox using idle
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
@@ -39,7 +39,7 @@ 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`.
by issuing a ``DONE`` command. This is explained in :rfc:`2177`.
.. literalinclude:: ../../examples/idle_example.py
@@ -48,10 +48,6 @@ 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
~~~~~~~~~~~~~~~~~~~~~~~~
TODO
Interactive Sessions
~~~~~~~~~~~~~~~~~~~~
When developing program using IMAPClient is it sometimes useful to
@@ -150,8 +146,3 @@ 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
@@ -61,3 +61,8 @@ TLS Support
.. automodule:: imapclient.tls
:members:
Thread Safety
~~~~~~~~~~~~~
Instances of IMAPClient are NOT thread safe. They should not be shared and
accessed concurrently from multiple threads.
View
@@ -1,4 +1,4 @@
IMAPClient concepts
IMAPClient Concepts
-------------------
Message Identifiers
@@ -77,13 +77,14 @@ connections and also allows for a high level of control of TLS
parameters if required. It uses the built-in `ssl` package,
provided since Python 2.7.9 and 3.4.
TLS parameters are controlled by passing a ``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.
TLS parameters are controlled by passing a ``ssl.SSLContext`` when
creating an IMAPClient instance (or to the `starttls` method when the
STARTTLS is used). 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.
When constructing a custom context it is usually best to start with
the default context, created by the ``ssl`` module, and modify it to
@@ -109,7 +110,7 @@ certificate used by the IMAP server.
If your operating system comes with an outdated list of CA certificates you can
use the `certifi <https://pypi.python.org/pypi/certifi>`_ package that provides
a list of common and respectable CAs::
an up-to-date set of trusted CAs::
import certifi
@@ -119,34 +120,13 @@ 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.
Using gevent with IMAPClient
++++++++++++++++++++++++++++
Some extra monkey patching is required so that the gevent_ package can
work with pyOpenSSL (used by IMAPClient for TLS support). The
`gevent_openssl`_ package performs this patching. Please use
gevent_openssl 1.2 or later.
Here's an example of how gevent_openssl can be used with IMAPClient::
from gevent import monkey; monkey.patch_all()
import gevent_openssl; gevent_openssl.monkey_patch()
import imapclient
client = imapclient.IMAPClient(...)
...
.. _gevent: http://www.gevent.org/
.. _`gevent_openssl`: https://pypi.python.org/pypi/gevent_openssl/
Logging
~~~~~~~
IMAPClient logs debug lines using the standard Python `logging module
<https://docs.python.org/3/library/logging.html>`_. Its logger is
``imapclient.*``.
IMAPClient logs debug lines using the standard Python :py:mod:`logging`
module. Its logger prefix is ``imapclient.``.
A simple way to display log messages is to setup logging::
One way to see debug messages from IMAPClient is to set up logging
like this::
import logging
@@ -155,4 +135,5 @@ A simple way to display log messages is to setup logging::
level=logging.DEBUG
)
For advanced usage please refer to the Python documentation.
For advanced usage, please refer to the documentation ``logging``
module.
View
@@ -5,7 +5,6 @@
import sys
from os import path
from mock import MagicMock
sys.path.insert(0, path.abspath(path.join(path.dirname(__file__), '..', '..')))
Oops, something went wrong.

0 comments on commit f2f27e5

Please sign in to comment.