Permalink
Browse files

Many small documentation tweaks

Removed the quickstart section as it's not necessary. The README as an
introductory example now, and the current documentation structure is
better now.
  • Loading branch information...
mjs committed Jan 4, 2018
1 parent 5bb8fdb commit 332d7bcc7230afa03300991b30ce5b1eb961b06c
Showing with 28 additions and 37 deletions.
  1. +3 −2 AUTHORS.rst
  2. +3 −12 doc/src/advanced.rst
  3. +5 −0 doc/src/api.rst
  4. +16 −14 doc/src/concepts.rst
  5. +1 −2 doc/src/index.rst
  6. +0 −7 doc/src/quickstart.rst
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
@@ -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
@@ -121,11 +122,11 @@ the Python 3 :py:mod:`ssl` package documentation for further options.
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
@@ -134,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
@@ -69,7 +69,7 @@ messages in the INBOX folder.
>>> print('ID #%d: "%s" received %s' % (msgid, envelope.subject.decode(), envelope.date))
ID #62: "Our holidays photos" received 2017-07-20 21:47:42
ID #55: "Re: did you book the hotel?" received 2017-06-26 10:38:09
ID #53: "Re: did you book the holel?" received 2017-06-25 22:02:58
ID #53: "Re: did you book the hotel?" received 2017-06-25 22:02:58
ID #44: "See that fun article about lobsters in Pacific ocean!" received 2017-06-09 09:49:47
ID #46: "Planning for our next vacations" received 2017-05-12 10:29:30
@@ -85,7 +85,6 @@ help you start.
:maxdepth: 2
installation
quickstart
concepts
advanced
View

This file was deleted.

Oops, something went wrong.

0 comments on commit 332d7bc

Please sign in to comment.