summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorAntoine Pitrou <solipsis@pitrou.net>2012-01-12 07:06:19 (GMT)
committerAntoine Pitrou <solipsis@pitrou.net>2012-01-12 07:06:19 (GMT)
commit889a5101c2e752b7e4d3d04f1e7e2ebd46837e37 (patch)
tree191ea59f66cacda582a80861854e4c14436be0a7 /Doc/library
parent0010256de4cb40fe8597fd1395de1d9dee56ed55 (diff)
downloadcpython-889a5101c2e752b7e4d3d04f1e7e2ebd46837e37.zip
cpython-889a5101c2e752b7e4d3d04f1e7e2ebd46837e37.tar.gz
cpython-889a5101c2e752b7e4d3d04f1e7e2ebd46837e37.tar.bz2
Issue #13724: improve documentation for socket.create_connection.
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/socket.rst15
1 files changed, 11 insertions, 4 deletions
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index ef81c4d..b31eb92 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -236,10 +236,17 @@ The module :mod:`socket` exports the following constants and functions:
.. 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