Merge issue #26355 fix from Python 3.5

1 files changed, 19 insertions, 0 deletions

diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 771ca43783..1632eb7aed 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -103,6 +103,14 @@ There's also a subclass for secure connections:
       :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
       :data:`ssl.HAS_SNI`).
 
+   .. deprecated:: 3.6
+
+       *keyfile* and *certfile* are deprecated in favor of *ssl_context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
+
 The second subclass allows for connections created by a child process:
 
 
@@ -500,6 +508,17 @@ An :class:`IMAP4` instance has the following methods:
          M.store(num, '+FLAGS', '\\Deleted')
       M.expunge()
 
+   .. note::
+
+      Creating flags containing ']' (for example: "[test]") violates
+      :rfc:`3501` (the IMAP protocol).  However, imaplib has historically
+      allowed creation of such tags, and popular IMAP servers, such as Gmail,
+      accept and produce such flags.  There are non-Python programs which also
+      create such tags.  Although it is an RFC violation and IMAP clients and
+      servers are supposed to be strict, imaplib nonetheless continues to allow
+      such tags to be created for backward compatibility reasons, and as of
+      python 3.6, handles them if they are sent from the server, since this
+      improves real-world compatibility.
 
 .. method:: IMAP4.subscribe(mailbox)