Merged revisions 77263-77264 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r77263 | gregory.p.smith | 2010-01-02 17:29:44 -0800 (Sat, 02 Jan 2010) | 4 lines

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

  For use by issue3972.
........
  r77264 | gregory.p.smith | 2010-01-02 18:06:07 -0800 (Sat, 02 Jan 2010) | 5 lines

  issue3972: HTTPConnection and HTTPSConnection now support a
  source_address parameter.

  Also cleans up an annotation in the socket documentation.
........

2 files changed, 18 insertions, 3 deletions

diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index 7a6717b..9f906df 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -23,7 +23,7 @@ HTTPS protocols.  It is normally not used directly --- the module
 The module provides the following classes:
 
 
-.. class:: HTTPConnection(host, port=None, strict=None[, timeout])
+.. class:: HTTPConnection(host, port=None, strict=None[, timeout[, source_address]])
 
    An :class:`HTTPConnection` instance represents one transaction with an HTTP
    server.  It should be instantiated passing it a host and optional port
@@ -35,6 +35,8 @@ The module provides the following classes:
    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, the global default timeout setting is used).
+   The optional *source_address* parameter may be a typle of a (host, port)
+   to use as the source address the HTTP connection is made from.
 
    For example, the following calls all create instances that connect to the server
    at the same host and port::
@@ -44,8 +46,11 @@ The module provides the following classes:
       >>> h3 = http.client.HTTPConnection('www.cwi.nl', 80)
       >>> h3 = http.client.HTTPConnection('www.cwi.nl', 80, timeout=10)
 
+   .. versionchanged:: 3.2
+      *source_address* was added.
 
-.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None, strict=None[, timeout])
+
+.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None, strict=None[, timeout[, source_address]])
 
    A subclass of :class:`HTTPConnection` that uses SSL for communication with
    secure servers.  Default port is ``443``. *key_file* is the name of a PEM
@@ -56,6 +61,9 @@ The module provides the following classes:
 
       This does not do any certificate verification.
 
+   .. versionchanged:: 3.2
+      *source_address* was added.
+
 
 .. class:: HTTPResponse(sock, debuglevel=0, strict=0, method=None, url=None)
 
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 79a4964..ec8ff3d 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -194,7 +194,7 @@ The module :mod:`socket` exports the following constants and functions:
    this platform.
 
 
-.. 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
@@ -202,6 +202,13 @@ The module :mod:`socket` exports the following constants and functions:
    *timeout* is supplied, the global default timeout setting returned by
    :func:`getdefaulttimeout` is used.
 
+   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.
+
+   .. versionchanged:: 3.2
+      *source_address* was added.
+
 
 .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])