[Python-checkins] r77263 - in python/trunk: Doc/library/socket.rst Lib/socket.py Lib/test/test_socket.py Misc/NEWS

[gregory.p.smith]

Author: gregory.p.smith
Date: Sun Jan  3 02:29:44 2010
New Revision: 77263

Log:
Adds an optional source_address parameter to socket.create_connection().

For use by issue3972.


Modified:
   python/trunk/Doc/library/socket.rst
   python/trunk/Lib/socket.py
   python/trunk/Lib/test/test_socket.py
   python/trunk/Misc/NEWS

Modified: python/trunk/Doc/library/socket.rst
==============================================================================
--- python/trunk/Doc/library/socket.rst	(original)
+++ python/trunk/Doc/library/socket.rst	Sun Jan  3 02:29:44 2010
@@ -205,7 +205,7 @@
    .. versionadded:: 2.3
 
 
-.. function:: create_connection(address[, timeout])
+.. function:: create_connection(address[, timeout[, source_address]])
 
    Convenience function.  Connect to *address* (a 2-tuple ``(host, port)``),
    and return the socket object.  Passing the optional *timeout* parameter will
@@ -215,6 +215,12 @@
 
    .. versionadded:: 2.6
 
+   If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the
+   socket to bind to as its source address before connecting.  If host or port
+   are '' or 0 respectively the OS default behavior will be used.
+
+   .. versionadded:: 2.7
+
 
 .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
 

Modified: python/trunk/Lib/socket.py
==============================================================================
--- python/trunk/Lib/socket.py	(original)
+++ python/trunk/Lib/socket.py	Sun Jan  3 02:29:44 2010
@@ -24,7 +24,8 @@
 ssl() -- secure socket layer support (only available if configured)
 socket.getdefaulttimeout() -- get the default timeout value
 socket.setdefaulttimeout() -- set the default timeout value
-create_connection() -- connects to an address, with an optional timeout
+create_connection() -- connects to an address, with an optional timeout and
+                       optional source address.
 
  [*] not available on all platforms!
 
@@ -531,7 +532,8 @@
 
 _GLOBAL_DEFAULT_TIMEOUT = object()
 
-def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT):
+def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT,
+                      source_address=None):
     """Connect to *address* and return the socket object.
 
     Convenience function.  Connect to *address* (a 2-tuple ``(host,
@@ -539,7 +541,9 @@
     *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.
+    is used.  If *source_address* is set it must be a tuple of (host, port)
+    for the socket to bind as a source address before making the connection.
+    An host of '' or port 0 tells the OS to use the default.
     """
 
     msg = "getaddrinfo returns an empty list"
@@ -551,6 +555,8 @@
             sock = socket(af, socktype, proto)
             if timeout is not _GLOBAL_DEFAULT_TIMEOUT:
                 sock.settimeout(timeout)
+            if source_address:
+                sock.bind(source_address)
             sock.connect(sa)
             return sock
 

Modified: python/trunk/Lib/test/test_socket.py
==============================================================================
--- python/trunk/Lib/test/test_socket.py	(original)
+++ python/trunk/Lib/test/test_socket.py	Sun Jan  3 02:29:44 2010
@@ -995,7 +995,7 @@
         ThreadableTest.__init__(self)
 
     def clientSetUp(self):
-        pass
+        self.source_port = test_support.find_unused_port()
 
     def clientTearDown(self):
         self.cli.close()
@@ -1010,6 +1010,19 @@
         self.cli = socket.create_connection((HOST, self.port), timeout=30)
         self.assertEqual(self.cli.family, 2)
 
+    testSourcePort = _justAccept
+    def _testSourcePort(self):
+        self.cli = socket.create_connection((HOST, self.port), timeout=30,
+                source_address=('', self.source_port))
+        self.assertEqual(self.cli.getsockname()[1], self.source_port)
+
+    testSourceAddress = _justAccept
+    def _testSourceAddress(self):
+        self.cli = socket.create_connection(
+                (HOST, self.port), 30, ('127.0.0.1', self.source_port))
+        self.assertEqual(self.cli.getsockname(),
+                         ('127.0.0.1', self.source_port))
+
     testTimeoutDefault = _justAccept
     def _testTimeoutDefault(self):
         # passing no explicit timeout uses socket's global default

Modified: python/trunk/Misc/NEWS
==============================================================================
--- python/trunk/Misc/NEWS	(original)
+++ python/trunk/Misc/NEWS	Sun Jan  3 02:29:44 2010
@@ -62,6 +62,8 @@
 Library
 -------
 
+- socket.create_connection now accepts an optional source_address parameter.
+
 - Issue #5511: now zipfile.ZipFile can be used as a context manager.
   Initial patch by Brian Curtin.