[Python-checkins] cpython (3.2): Issue #13724: improve documentation for socket.create_connection.

[antoine.pitrou]

http://hg.python.org/cpython/rev/5594cd88bfed
changeset:   74343:5594cd88bfed
branch:      3.2
parent:      74340:068e5c4d4bae
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Thu Jan 12 08:06:19 2012 +0100
summary:
  Issue #13724: improve documentation for socket.create_connection.

files:
  Doc/library/socket.rst |  15 +++++++++++----
  1 files changed, 11 insertions(+), 4 deletions(-)


diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -236,10 +236,17 @@
 
 .. 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
-   set the timeout on the socket instance before attempting to connect.  If no
-   *timeout* is supplied, the global default timeout setting returned by
+   Connect to a TCP service listening on the Internet *address* (a 2-tuple
+   ``(host, port)``), and return the socket object.  This is a higher-level
+   function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
+   it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`,
+   and then try to connect to all possible addresses in turn until a
+   connection succeeds.  This makes it easy to write clients that are
+   compatible to both IPv4 and IPv6.
+
+   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.
 
    If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the

-- 
Repository URL: http://hg.python.org/cpython