===============
Enhanced TLS support [API]
--------------------------
The way that IMAPClient establishes TLS/SSL connections has been
completely reworked. By default IMAPClient will attempt certificate
verification, certificate hostname checking, and will not use
known-insecure TLS settings and protocols. In addition, TLS parameters
are now highly configurable.
By leveraging pyOpenSSL and backports.ssl, all Python versions
supported by IMAPClient enjoy the same TLS functionality and
API.
These packages mean that IMAPClient now has a number of new
dependencies. These should be installed automatically as required but
there will no doubt be complications.
Compatibility breaks:
1. Due to lack of support in some of the dependent libraries,
IMAPClient no longer supports Python 3.2.
2. The passthrough keyword arguments that the IMAPClient constructor
took in past versions are no longer accepted. These were in place
to provide access to imaplib's SSL arguments which are no longer
relevant. Please pass a SSL context object instead.
3. When using the default SSL context that IMAPClient creates
(recommended), certificate verification is enabled. This means that
IMAPClient connections to servers that used to work before,
may fail now (especially if a self-signed certificate is used by
the server). Refer to the documentation for details of how to
supply alternate CA certificates or disable verification.
4. There are some new exceptions that might be raised in response to
network issues or TLS protocol failures. Refer to the
Exceptions_ section of the manual for more details.
Please refer to the "TLS/SSL" section of the manual for more details
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.io/en/latest/#exceptions
STARTTLS support [NEW]
----------------------
When the server supports it, IMAPClient can now establish an encrypted
connection after initially starting with an unencrypted connection
using the STARTTLS command. The starttls method takes an SSL context
object for controlling the parameters of the TLS negotiation.
Many thanks to Chris Arndt for his extensive initial work on this.
More robust criteria handling for search, sort and thread [API]
---------------------------------------------------------------
IMAPClient's methods that accept search criteria (search, sort,
thread, gmail_search) have been changed to provide take criteria in
a more straightforward and robust way. In addition, the way the
*charset* argument interacts with search criteria has been
improved. These changes make it easier to pass search criteria and
have them handled correctly but unfortunately also mean that small
changes may be required to existing code that uses IMAPClient.
Search criteria
~~~~~~~~~~~~~~~
The preferred way to specify criteria now is as a list of strings,
ints and dates (where relevant). The list should be flat with all the
criteria parts run together. Where a criteria takes an argument, just
provide it as the next element in the list.
Some valid examples::
c.search(['DELETED'])
c.search(['NOT', 'DELETED'])
c.search(['FLAGGED', 'SUBJECT', 'foo', 'BODY', 'hello world'])
c.search(['NOT', 'DELETED', 'SMALLER', 1000])
c.search(['SINCE', date(2006, 5, 3)])
IMAPClient will perform all required conversion, quoting and
encoding. Callers do not need to and should not attempt to do this
themselves. IMAPClient will automatically send criteria parts as IMAP
literals when required (i.e. when the encoded part is 8-bit).
Some previously accepted ways of passing search criteria will not work
as they did in previous versions of IMAPClient. Small changes will be
required in these cases. Here are some examples of how to update code
written against older versions of IMAPClient::
c.search(['NOT DELETED']) Before
c.search(['NOT', 'DELETED']) After
c.search(['TEXT "foo"']) Before
c.search(['TEXT', 'foo']) After (IMAPClient will add the quotes)
c.search(['DELETED', 'TEXT "foo"']) Before
c.search(['DELETED', 'TEXT', 'foo']) After
c.search(['SMALLER 1000']) Before
c.search(['SMALLER', 1000]) After
It is also possible to pass a single string as the search
criteria. IMAPClient will not attempt quoting in this case, allowing
the caller to specify search criteria at a lower level. Specifying
criteria using a sequence of strings is preferable however. The
following examples (equivalent to those further above) are valid::
c.search('DELETED')
c.search('NOT DELETED')
c.search('FLAGGED SUBJECT "foo" BODY "hello world"')
c.search('NOT DELETED SMALLER 1000')
c.search('SINCE 03-May-2006')
Search charset
~~~~~~~~~~~~~~
The way that the search *charset* argument is handled has also
changed.
Any unicode criteria arguments will now be encoded by IMAPClient using
the supplied charset. The charset must refer to an encoding that is
capable of handling the criteria's characters or an error will
occur. The charset must obviously also be one that the server
supports! (UTF-8 is common)
Any criteria given as bytes will not be changed by IMAPClient, but the
provided charset will still be passed to the IMAP server. This allows
already encoding criteria to be passed through as-is. The encoding
referred to by *charset* should match the actual encoding used for the
criteria.
The following are valid examples::
c.search(['TEXT', u'\u263a'], 'utf-8') IMAPClient will apply UTF-8 encoding
c.search([b'TEXT', b'\xe2\x98\xba'], 'utf-8') Caller has already applied UTF-8 encoding
The documentation and tests for search, gmail_search, sort and thread
has updated to account for these changes and have also been generally
improved.
Socket timeout support [NEW]
----------------------------
IMAPClient now accepts a timeout at creation time. The timeout applies
while establishing the connection and for all operations on the socket
connected to the IMAP server.
Semantic versioning
-------------------
In order to better indicate version compatibility to users, IMAPClient
will now strictly adhere to the `Semantic Versioning
<http://semver.org>`_ scheme.
Performance optimisation for parsing message id lists
-----------------------------------------------------
A short circuit is now used when parsing a list of message ids which
greatly speeds up parsing time.
Other
-----
- Perform quoting of Gmail labels. Thanks to Pawel Sz for the fix.
- The type of the various flag constants was fixed. Thanks to Thomi
Richards for pointing this out.
- Now using mock 1.3.0. Thanks to Thomi Richards for the patch.
- Fixed handling of very long numeric only folder names. Thanks to
Paweł Gorzelany for the patch.
- The default charset for gmail_search is now UTF-8. This makes it
easier to use any unicode string as a search string and is safe
because Gmail supports UTF-8 search criteria.
- PEP8 compliance fixed (except for some occasional long lines)
- Added a "shutdown" method.
- The embedded six package has been removed in favour of using an
externally installed instance.
- Fixed handling of literals in STATUS responses.
- Only use the untagged post-login CAPABILITY response once (if sent
by server).
- Release history made part of the main documentation.
- Clarified how message ids work in the docs.
- Livetest infrastructure now works with Yahoo's OAUTH2
- Fixed bytes handling in Address.__str__
==============