bpo-38615: Add timeout parameter for IMAP4 and IMAP4_SSL constructor (GH-17203)
imaplib.IMAP4 and imaplib.IMAP4_SSL now have an
optional *timeout* parameter for their constructors.
Also, the imaplib.IMAP4.open() method now has an optional *timeout* parameter
with this change. The overridden methods of imaplib.IMAP4_SSL and
imaplib.IMAP4_stream were applied to this change.
diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index df63d82..5b8ca7c 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -30,12 +30,14 @@
base class:
-.. class:: IMAP4(host='', port=IMAP4_PORT)
+.. class:: IMAP4(host='', port=IMAP4_PORT, timeout=None)
This class implements the actual IMAP4 protocol. The connection is created and
protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
initialized. If *host* is not specified, ``''`` (the local host) is used. If
- *port* is omitted, the standard IMAP4 port (143) is used.
+ *port* is omitted, the standard IMAP4 port (143) is used. The optional *timeout*
+ parameter specifies a timeout in seconds for the connection attempt.
+ If timeout is not given or is None, the global default socket timeout is used.
The :class:`IMAP4` class supports the :keyword:`with` statement. When used
like this, the IMAP4 ``LOGOUT`` command is issued automatically when the
@@ -50,6 +52,9 @@
.. versionchanged:: 3.5
Support for the :keyword:`with` statement was added.
+ .. versionchanged:: 3.9
+ The optional *timeout* parameter was added.
+
Three exceptions are defined as attributes of the :class:`IMAP4` class:
@@ -78,7 +83,7 @@
.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, \
- certfile=None, ssl_context=None)
+ certfile=None, ssl_context=None, timeout=None)
This is a subclass derived from :class:`IMAP4` that connects over an SSL
encrypted socket (to use this class you need a socket module that was compiled
@@ -95,8 +100,12 @@
mutually exclusive with *ssl_context*, a :class:`ValueError` is raised
if *keyfile*/*certfile* is provided along with *ssl_context*.
+ The optional *timeout* parameter specifies a timeout in seconds for the
+ connection attempt. If timeout is not given or is None, the global default
+ socket timeout is used.
+
.. versionchanged:: 3.3
- *ssl_context* parameter added.
+ *ssl_context* parameter was added.
.. versionchanged:: 3.4
The class now supports hostname check with
@@ -110,6 +119,8 @@
:func:`ssl.create_default_context` select the system's trusted CA
certificates for you.
+ .. versionchanged:: 3.9
+ The optional *timeout* parameter was added.
The second subclass allows for connections created by a child process:
@@ -353,16 +364,22 @@
Send ``NOOP`` to server.
-.. method:: IMAP4.open(host, port)
+.. method:: IMAP4.open(host, port, timeout=None)
- Opens socket to *port* at *host*. This method is implicitly called by
- the :class:`IMAP4` constructor. The connection objects established by this
- method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`,
- :meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override
- this method.
+ Opens socket to *port* at *host*. The optional *timeout* parameter
+ specifies a timeout in seconds for the connection attempt.
+ If timeout is not given or is None, the global default socket timeout
+ is used. Also note that if the *timeout* parameter is set to be zero,
+ it will raise a :class:`ValueError` to reject creating a non-blocking socket.
+ This method is implicitly called by the :class:`IMAP4` constructor.
+ The connection objects established by this method will be used in
+ the :meth:`IMAP4.read`, :meth:`IMAP4.readline`, :meth:`IMAP4.send`,
+ and :meth:`IMAP4.shutdown` methods. You may override this method.
.. audit-event:: imaplib.open self,host,port imaplib.IMAP4.open
+ .. versionchanged:: 3.9
+ The *timeout* parameter was added.
.. method:: IMAP4.partial(message_num, message_part, start, length)
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index 46774c2..ea6d8f5 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -167,6 +167,16 @@
been executed), do not block the collection of all objects that are still
unreachable. (Contributed by Pablo Galindo and Tim Peters in :issue:`38379`.)
+imaplib
+-------
+
+:class:`~imaplib.IMAP4` and :class:`~imaplib.IMAP4_SSL` now have
+an optional *timeout* parameter for their constructors.
+Also, the :meth:`~imaplib.IMAP4.open` method now has an optional *timeout* parameter
+with this change. The overridden methods of :class:`~imaplib.IMAP4_SSL` and
+:class:`~imaplib.IMAP4_stream` were applied to this change.
+(Contributed by Dong-hee Na in :issue:`38615`.)
+
os
--