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, :)

7 files changed, 28 insertions, 27 deletions

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 module defines the following items:
    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 @@ 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 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 @@ The module provides the following classes:
    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 @@ A single class is provided by the :mod:`poplib` module:
    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 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    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 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    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 @@ The module :mod:`socket` exports the following constants and functions:
 
 .. 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 @@ 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
+   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 @@ 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 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 @@ The :mod:`urllib2` module defines the following functions:
    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 @@ OpenerDirector Objects
    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.