From ab756f60bdef88f15cc94c77e0752c6c7c8d708f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 11 May 2008 11:09:35 +0000 Subject: [PATCH] #2452: timeout is used for all blocking operations. --- Doc/library/ftplib.rst | 18 ++++++++++-------- Doc/library/httplib.rst | 16 ++++++++-------- Doc/library/smtplib.rst | 30 ++++++++++++++++-------------- Doc/library/telnetlib.rst | 16 +++++++++------- Doc/library/urllib2.rst | 21 +++++++++++---------- 5 files changed, 54 insertions(+), 47 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 0b82f6822fc..1785a26d8ca 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -40,11 +40,12 @@ The module defines the following items: .. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]]) Return a new instance of the :class:`FTP` class. When *host* is given, the - method call ``connect(host)`` is made. When *user* is given, additionally the - method call ``login(user, passwd, acct)`` is made (where *passwd* and *acct* - default to the empty string when not given). The optional *timeout* parameter - specifies a timeout in seconds for the connection attempt (if is not specified, - or passed as None, the global default timeout setting will be used). + method call ``connect(host)`` is made. When *user* is given, additionally + the method call ``login(user, passwd, acct)`` is made (where *passwd* and + *acct* default to the empty string when not given). The optional *timeout* + parameter specifies a timeout in seconds for blocking operations like the + connection attempt (if is not specified, or passed as None, the global + default timeout setting will be used). .. versionchanged:: 2.6 *timeout* was added. @@ -125,9 +126,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. made. The optional *timeout* parameter specifies a timeout in seconds for the - connection attempt. If is not specified, or passed as None, the object timeout - is used (the timeout that you passed when instantiating the class); if the - object timeout is also None, the global default timeout setting will be used. + connection attempt. If is not specified, or passed as None, the object + timeout is used (the timeout that you passed when instantiating the class); + if the object timeout is also None, the global default timeout setting will + be used. .. versionchanged:: 2.6 *timeout* was added. diff --git a/Doc/library/httplib.rst b/Doc/library/httplib.rst index aae2219cfba..9d6baba2220 100644 --- a/Doc/library/httplib.rst +++ b/Doc/library/httplib.rst @@ -33,14 +33,14 @@ The module provides the following classes: .. class:: HTTPConnection(host[, port[, strict[, timeout]]]) An :class:`HTTPConnection` instance represents one transaction with an HTTP - server. It should be instantiated passing it a host and optional port number. - If no port number is passed, the port is extracted from the host string if it - has the form ``host:port``, else the default HTTP port (80) is used. When True, - the optional parameter *strict* causes ``BadStatusLine`` to be raised if the - status line can't be parsed as a valid HTTP/1.0 or 1.1 status line. If the - optional *timeout* parameter is given, connection attempts will timeout after - that many seconds (if it is not given or ``None``, the global default timeout - setting is used). + server. It should be instantiated passing it a host and optional port + number. If no port number is passed, the port is extracted from the host + string if it has the form ``host:port``, else the default HTTP port (80) is + used. When True, the optional parameter *strict* causes ``BadStatusLine`` to + be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 + status line. If the optional *timeout* parameter is given, blocking + operations (like connection attempts) will timeout after that many seconds + (if it is not given or ``None``, the global default timeout setting is used). For example, the following calls all create instances that connect to the server at the same host and port:: diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 3c22f642349..dfa5e8f8e2d 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -19,13 +19,14 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). .. class:: SMTP([host[, port[, local_hostname[, timeout]]]]) - A :class:`SMTP` instance encapsulates an SMTP connection. It has methods that - support a full repertoire of SMTP and ESMTP operations. If the optional host and - port parameters are given, the SMTP :meth:`connect` method is called with those - parameters during initialization. An :exc:`SMTPConnectError` is raised if the - specified host doesn't respond correctly. The optional *timeout* parameter - specifies a timeout in seconds for the connection attempt (if not specified, or - passed as None, the global default timeout setting will be used). + A :class:`SMTP` instance encapsulates an SMTP connection. It has methods + that support a full repertoire of SMTP and ESMTP operations. If the optional + host and port parameters are given, the SMTP :meth:`connect` method is called + with those parameters during initialization. An :exc:`SMTPConnectError` is + raised if the specified host doesn't respond correctly. The optional + *timeout* parameter specifies a timeout in seconds for blocking operations + like the connection attempt (if not specified, or passed as None, the global + default timeout setting will be used). For normal use, you should only require the initialization/connect, :meth:`sendmail`, and :meth:`quit` methods. An example is included below. @@ -38,13 +39,14 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). A :class:`SMTP_SSL` instance behaves exactly the same as instances of :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is - required from the beginning of the connection and using :meth:`starttls` is not - appropriate. If *host* is not specified, the local host is used. If *port* is - omitted, the standard SMTP-over-SSL port (465) is used. *keyfile* and *certfile* - are also optional, and can contain a PEM formatted private key and certificate - chain file for the SSL connection. The optional *timeout* parameter specifies a - timeout in seconds for the connection attempt (if not specified, or passed as - None, the global default timeout setting will be used). + required from the beginning of the connection and using :meth:`starttls` is + not appropriate. If *host* is not specified, the local host is used. If + *port* is omitted, the standard SMTP-over-SSL port (465) is used. *keyfile* + and *certfile* are also optional, and can contain a PEM formatted private key + and certificate chain file for the SSL connection. The optional *timeout* + parameter specifies a timeout in seconds for blocking operations like the + connection attempt (if not specified, or passed as None, the global default + timeout setting will be used). .. versionchanged:: 2.6 *timeout* was added. diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst index 396560b4d57..b0c16833da1 100644 --- a/Doc/library/telnetlib.rst +++ b/Doc/library/telnetlib.rst @@ -27,11 +27,12 @@ Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin). :class:`Telnet` represents a connection to a Telnet server. The instance is initially not connected by default; the :meth:`open` method must be used to - establish a connection. Alternatively, the host name and optional port number - can be passed to the constructor, to, in which case the connection to the server - will be established before the constructor returns. The optional *timeout* - parameter specifies a timeout in seconds for the connection attempt (if not - specified, or passed as None, the global default timeout setting will be used). + establish a connection. Alternatively, the host name and optional port + number can be passed to the constructor, to, in which case the connection to + the server will be established before the constructor returns. The optional + *timeout* parameter specifies a timeout in seconds for blocking operations + like the connection attempt (if not specified, or passed as None, the global + default timeout setting will be used). Do not reopen an already connected instance. @@ -126,8 +127,9 @@ Telnet Objects Connect to a host. The optional second argument is the port number, which defaults to the standard Telnet port (23). The optional *timeout* parameter - specifies a timeout in seconds for the connection attempt (if not specified, or - passed as None, the global default timeout setting will be used). + specifies a timeout in seconds for blocking operations like the connection + attempt (if not specified, or passed as None, the global default timeout + setting will be used). Do not try to reopen an already connected instance. diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index dad03401bfe..0bdc8be7368 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -26,10 +26,10 @@ The :mod:`urllib2` module defines the following functions: :func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and returns a string in this format. - The optional *timeout* parameter specifies a timeout in seconds for the - connection attempt (if not specified, or passed as None, the global default - timeout setting will be used). This actually only work for HTTP, HTTPS, FTP and - FTPS connections. + The optional *timeout* parameter specifies a timeout in seconds for blocking + operations like the connection attempt (if not specified, or passed as + ``None``, the global default timeout setting will be used). This actually + only works for HTTP, HTTPS, FTP and FTPS connections. This function returns a file-like object with two additional methods: @@ -407,12 +407,13 @@ OpenerDirector Objects .. method:: OpenerDirector.open(url[, data][, timeout]) Open the given *url* (which can be a request object or a string), optionally - passing the given *data*. Arguments, return values and exceptions raised are the - same as those of :func:`urlopen` (which simply calls the :meth:`open` method on - the currently installed global :class:`OpenerDirector`). The optional *timeout* - parameter specifies a timeout in seconds for the connection attempt (if not - specified, or passed as None, the global default timeout setting will be used; - this actually only work for HTTP, HTTPS, FTP and FTPS connections). + passing the given *data*. Arguments, return values and exceptions raised are + the same as those of :func:`urlopen` (which simply calls the :meth:`open` + method on the currently installed global :class:`OpenerDirector`). The + optional *timeout* parameter specifies a timeout in seconds for blocking + operations like the connection attempt (if not specified, or passed as + ``None``, the global default timeout setting will be used; this actually only + works for HTTP, HTTPS, FTP and FTPS connections). .. versionchanged:: 2.6 *timeout* was added.