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

1 files changed, 10 insertions, 7 deletions

diff --git a/Lib/socket.py b/Lib/socket.py
index 2a5254730c..6dcd1a693a 100644
--- a/Lib/socket.py
+++ b/Lib/socket.py
@@ -480,14 +480,17 @@ class _fileobject(object):
             raise StopIteration
         return line
 
+_GLOBAL_DEFAULT_TIMEOUT = object()
 
-def create_connection(address, timeout=None):
-    """Connect to address (host, port) with an optional timeout.
+def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT):
+    """Connect to *address* and return the socket object.
 
-    Provides access to socketobject timeout for higher-level
-    protocols.  Passing a timeout will set the timeout on the
-    socket instance (if not present, or passed as None, the
-    default global timeout setting will be 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.
     """
 
     msg = "getaddrinfo returns an empty list"
@@ -497,7 +500,7 @@ def create_connection(address, timeout=None):
         sock = None
         try:
             sock = socket(af, socktype, proto)
-            if timeout is not None:
+            if timeout is not _GLOBAL_DEFAULT_TIMEOUT:
                 sock.settimeout(timeout)
             sock.connect(sa)
             return sock