Fixed the semantic of timeout for socket.create_connection and
all the upper level libraries that use it, including urllib2.
Added and fixed some tests, and changed docs correspondingly.
Thanks to John J Lee for the patch and the pusing, :)
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 1785a26..728eeab 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -44,8 +44,8 @@
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).
+ connection attempt (if is not specified, the global default timeout setting
+ will be used).
.. versionchanged:: 2.6
*timeout* was added.
@@ -126,10 +126,8 @@
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 no *timeout* is passed, 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 ce6222b..4c87d17 100644
--- a/Doc/library/httplib.rst
+++ b/Doc/library/httplib.rst
@@ -44,7 +44,7 @@
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).
+ (if it is not given, 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/poplib.rst b/Doc/library/poplib.rst
index 2cf3402..e5f693d 100644
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -29,8 +29,8 @@
This class implements the actual POP3 protocol. The connection is created when
the instance is initialized. If *port* is omitted, the standard POP3 port (110)
is used. 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).
+ connection attempt (if not specified, the global default timeout setting will
+ be used).
.. versionchanged:: 2.6
*timeout* was added.
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index dfa5e8f..ff580da 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -25,8 +25,8 @@
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).
+ like the connection attempt (if not specified, 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.
@@ -45,8 +45,8 @@
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).
+ connection attempt (if not specified, the global default timeout setting
+ will be used).
.. versionchanged:: 2.6
*timeout* was added.
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index e5a8167..16feee5 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -207,12 +207,11 @@
.. function:: create_connection(address[, timeout])
- Connects to the *address* received (as usual, a ``(host, port)`` pair), with an
- optional timeout for the connection. Especially useful for higher-level
- protocols, it is not normally used directly from application-level code.
- Passing the optional *timeout* parameter will set the timeout on the socket
- instance (if it is not given or ``None``, the global default timeout setting is
- used).
+ Convenience function. Connect to *address* (a 2-tuple ``(host, port)``),
+ and return the socket object. Passing the optional *timeout* parameter will
+ set the timeout on the socket instance before attempting to connect. If no
+ *timeout* is supplied, the global default timeout setting returned by
+ :func:`getdefaulttimeout` is used.
.. versionadded:: 2.6
diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
index b0c1683..b326da9 100644
--- a/Doc/library/telnetlib.rst
+++ b/Doc/library/telnetlib.rst
@@ -28,6 +28,11 @@
: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
+ and timeout can be passed to the constructor, 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, the global default timeout setting will be used).
+
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
@@ -128,8 +133,7 @@
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 blocking operations like the connection
- attempt (if not specified, or passed as None, the global default timeout
- setting will be used).
+ attempt (if not specified, 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 0bdc8be..ff664f5 100644
--- a/Doc/library/urllib2.rst
+++ b/Doc/library/urllib2.rst
@@ -27,9 +27,9 @@
returns a string in this format.
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.
+ operations like the connection attempt (if not specified, 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:
@@ -411,9 +411,9 @@
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).
+ operations like the connection attempt (if not specified, the global default
+ timeout setting will be usedi). The timeout feature actually works only for
+ HTTP, HTTPS, FTP and FTPS connections).
.. versionchanged:: 2.6
*timeout* was added.
