bpo-35934: Add socket.create_server() utility function

Doc/library/socket.rst

@@ -595,6 +595,58 @@ The following functions all create :ref:`socket objects <socket-objects>`.
    .. versionchanged:: 3.2
       *source_address* was added.
 
+.. function:: create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)
+
+   Convenience function which creates a :data:`SOCK_STREAM` type socket
+   bound to *address* (a 2-tuple ``(host, port)``) and return the socket
+   object.
+
+   *family* should be either :data:`AF_INET` or :data:`AF_INET6`.
+   *backlog* is the queue size passed to :meth:`socket.listen`.
+   *reuse_port* dictates whether to set :data:`SO_REUSEPORT` socket option.
+
+   If *dualstack_ipv6* is true and the platform supports it the socket will
+   be able to accept both IPv4 and IPv6 connections.
+   In this case the address returned by :meth:`socket.getpeername` when an IPv4
+   connection occurs will be an IPv6 address represented as an IPv4-mapped IPv6
+   address like ``":ffff:127.0.0.1"``.
+   If *dualstack_ipv6* is false it will explicitly disable this functionality
+   on platforms that enable it by default (e.g. Linux).
+   For platforms not supporting this functionality natively you could use this
+   `MultipleSocketsListener recipe <http://code.activestate.com/recipes/578504/>`__.
+   This parameter can be used in conjunction with :func:`has_dualstack_ipv6`.
+
+   Here's an echo server example listening on all interfaces, port 8888,
+   accepting both IPv4 and IPv6 connections (if supported):
+
+   ::
+
+     import socket
+
+     with socket.create_server(("", 8888),
+                               dualstack_ipv6=socket.has_dualstack_ipv6()) as server:
+         conn, addr = server.accept()
+         with conn:
+             while True:
+                 data = conn.recv(1024)
+                 if not data:
+                     break
+                 conn.send(data)
+
+   .. note::
+    On POSIX :data:`SO_REUSEADDR` socket option is set in order to immediately
+    reuse previous sockets which were bound on the same *address* and remained
+    in TIME_WAIT state.
+
+   .. versionadded:: 3.8
+
+.. function:: has_dualstack_ipv6()
+
+   Return ``True`` if the platform supports creating a :data:`SOCK_STREAM`
+   socket which can handle both :data:`AF_INET` or :data:`AF_INET6`
+   (IPv4 / IPv6) connections.
+
+   .. versionadded:: 3.8
 
 .. function:: fromfd(fd, family, type, proto=0)
 
@@ -1779,6 +1831,40 @@ sends traffic to the first one connected successfully. ::
    print('Received', repr(data))
 
 
+The two examples above can be rewritten by using :meth:`socket.create_server`
+and :meth:`socket.create_connection` convenience functions.
+If the platform supports it, :meth:`socket.create_server` has the extra
+advantage of creating an agnostic IPv4/IPv6 server:
+
+::
+
+   # Echo server program
+   import socket
+
+   HOST = None
+   PORT = 50007
+   s = socket.create_server((HOST, PORT), dualstack_ipv6=socket.has_dualstack_ipv6())
+   conn, addr = s.accept()
+   with conn:
+       print('Connected by', addr)
+       while True:
+           data = conn.recv(1024)
+           if not data: break
+           conn.send(data)
+
+::
+
+   # Echo client program
+   import socket
+
+   HOST = 'daring.cwi.nl'
+   PORT = 50007
+   with socket.create_connection((HOST, PORT)) as s:
+       s.sendall(b'Hello, world')
+       data = s.recv(1024)
+   print('Received', repr(data))
+
+
 The next example shows how to write a very simple network sniffer with raw
 sockets on Windows. The example requires administrator privileges to modify
 the interface::

Doc/whatsnew/3.8.rst

@@ -214,6 +214,15 @@ contain characters unrepresentable at the OS level.
 (Contributed by Serhiy Storchaka in :issue:`33721`.)
 
 
+socket
+------
+
+Added :meth:`~socket.create_server()` and :meth:`~socket.has_dualstack_ipv6()`
+convenience functions to automatize the necessary tasks usually involved when
+creating a server socket, including accepting both IPv4 and IPv6 connections
+on the same socket.  (Contributed by Giampaolo Rodola in :issue:`17561`.)
+
+
 shutil
 ------
 

Lib/ftplib.py

@@ -302,26 +302,7 @@ def sendeprt(self, host, port):
 
     def makeport(self):
         '''Create a new socket and send a PORT command for it.'''
-        err = None
-        sock = None
-        for res in socket.getaddrinfo(None, 0, self.af, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
-            af, socktype, proto, canonname, sa = res
-            try:
-                sock = socket.socket(af, socktype, proto)
-                sock.bind(sa)
-            except OSError as _:
-                err = _
-                if sock:
-                    sock.close()
-                sock = None
-                continue
-            break
-        if sock is None:
-            if err is not None:
-                raise err
-            else:
-                raise OSError("getaddrinfo returns an empty list")
-        sock.listen(1)
+        sock = socket.create_server(("", 0), family=self.af, backlog=1)
         port = sock.getsockname()[1] # Get proper port
         host = self.sock.getsockname()[0] # Get proper host
         if self.af == socket.AF_INET:

Lib/idlelib/rpc.py

@@ -530,9 +530,8 @@ class RPCClient(SocketIO):
     nextseq = 1 # Requests coming from the client are odd numbered
 
     def __init__(self, address, family=socket.AF_INET, type=socket.SOCK_STREAM):
-        self.listening_sock = socket.socket(family, type)
-        self.listening_sock.bind(address)
-        self.listening_sock.listen(1)
+        self.listening_sock = socket.create_server(
+            address, family=family, type=type, backlog=1)
 
     def accept(self):
         working_sock, address = self.listening_sock.accept()

Lib/socket.py

@@ -60,8 +60,8 @@
 EAGAIN = getattr(errno, 'EAGAIN', 11)
 EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11)
 
-__all__ = ["fromfd", "getfqdn", "create_connection",
-        "AddressFamily", "SocketKind"]
+__all__ = ["fromfd", "getfqdn", "create_connection", "create_server",
+           "has_dualstack_ipv6", "AddressFamily", "SocketKind"]
 __all__.extend(os._get_exports_list(_socket))
 
 # Set up the socket.AF_* socket.SOCK_* constants as members of IntEnums for
@@ -728,6 +728,93 @@ def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT,
     else:
         raise error("getaddrinfo returns an empty list")
 
+
+def has_dualstack_ipv6():
+    """Return True if the platform supports creating a SOCK_STREAM socket
+    which can handle both AF_INET and AF_INET6 (IPv4 / IPv6) connections.
+    """
+    if not has_ipv6 \
+            or not hasattr(_socket, 'IPPROTO_IPV6') \
+            or not hasattr(_socket, 'IPV6_V6ONLY'):
+        return False
+    try:
+        with socket(AF_INET6, SOCK_STREAM) as sock:
+            sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 0)
+            return True
+    except error:
+        return False
+
+
+def create_server(address, *, family=AF_INET, backlog=None, reuse_port=False,
+                  dualstack_ipv6=False):
+    """Convenience function which creates a SOCK_STREAM type socket
+    bound to *address* (a 2-tuple (host, port)) and return the socket
+    object.
+
+    *family* should be either AF_INET or AF_INET6.
+    *backlog* is the queue size passed to socket.listen().
+    *reuse_port* dictate whether to use the SO_REUSEPORT socket option.
+    *dualstack_ipv6*: if true and the platform supports it, it will
+    create a socket able to accept both IPv4 and IPv6 connections.
+    When false it will explicitly disable this option on platforms
+    that enable it by default (e.g. Linux).
+
+    >>> with create_server((None, 8000)) as server:
+    ...     while True:
+    ...         conn, addr = server.accept()
+    ...         # handle new connection
+    """
+    if reuse_port and not hasattr(_socket, "SO_REUSEPORT"):
+        raise ValueError("SO_REUSEPORT not supported on this platform")
+    if dualstack_ipv6:
+        if not has_dualstack_ipv6():
+            raise ValueError("dualstack_ipv6 not supported on this platform")
+        if family != AF_INET6:
+            raise ValueError("dualstack_ipv6 requires AF_INET6 family")
+    sock = socket(family, SOCK_STREAM)
+    try:
+        # Note about Windows. We don't set SO_REUSEADDR because:
+        # 1) It's unnecessary: bind() will succeed even in case of a
+        # previous closed socket on the same address and still in
+        # TIME_WAIT state.
+        # 2) If set, another socket will be free to bind() on the same
+        # address, effectively preventing this one from accepting
+        # connections. Also, it may set the process in a state where
+        # it'll no longer respond to any signals or graceful kills.
+        # See: msdn2.microsoft.com/en-us/library/ms740621(VS.85).aspx
+        if os.name not in ('nt', 'cygwin') and \
+                hasattr(_socket, 'SO_REUSEADDR'):
+            try:
+                sock.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1)
+            except error:
+                # Fail later on bind(), for platforms which may not
+                # support this option.
+                pass
+        if reuse_port:
+            sock.setsockopt(SOL_SOCKET, SO_REUSEPORT, 1)
+        if has_ipv6 and family == AF_INET6:
+            if dualstack_ipv6:
+                sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 0)
+            elif hasattr(_socket, "IPV6_V6ONLY") and \
+                    hasattr(_socket, "IPPROTO_IPV6"):
+                # Disable IPv4/IPv6 dual stack support (enabled by
+                # default on Linux) which makes a single socket
+                # listen on both address families in order to
+                # eliminate cross-platform differences.
+                sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 1)
+        try:
+            sock.bind(address)
+        except error as err:
+            err_msg = '%s (while attempting to bind on address %r)' % \
+                (err.strerror, address)
+            raise error(err.errno, err_msg) from None
+        sock.listen(backlog or 0)
+        return sock
+    except Exception:
+        sock.close()
+        raise
+
+
 def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):
     """Resolve host and port into list of address info entries.
 

Lib/test/_test_multiprocessing.py

@@ -3323,9 +3323,7 @@ def _listener(cls, conn, families):
             new_conn.close()
             l.close()
 
-        l = socket.socket()
-        l.bind((test.support.HOST, 0))
-        l.listen()
+        l = socket.create_server((test.support.HOST, 0))
         conn.send(l.getsockname())
         new_conn, addr = l.accept()
         conn.send(new_conn)
@@ -4077,9 +4075,7 @@ def _child_test_wait_socket(cls, address, slow):
 
     def test_wait_socket(self, slow=False):
         from multiprocessing.connection import wait
-        l = socket.socket()
-        l.bind((test.support.HOST, 0))
-        l.listen()
+        l = socket.create_server((test.support.HOST, 0))
         addr = l.getsockname()
         readers = []
         procs = []

Lib/test/eintrdata/eintr_tester.py

@@ -284,12 +284,9 @@ def test_sendmsg(self):
         self._test_send(lambda sock, data: sock.sendmsg([data]))
 
     def test_accept(self):
-        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock = socket.create_server((support.HOST, 0))
         self.addCleanup(sock.close)
-
-        sock.bind((support.HOST, 0))
         port = sock.getsockname()[1]
-        sock.listen()
 
         code = '\n'.join((
             'import socket, time',

Lib/test/test_asyncio/functional.py

@@ -60,21 +60,13 @@ def tcp_server(self, server_prog, *,
             else:
                 addr = ('127.0.0.1', 0)
 
-        sock = socket.socket(family, socket.SOCK_STREAM)
-
+        sock = socket.create_server(addr, family=family, backlog=backlog)
         if timeout is None:
             raise RuntimeError('timeout is required')
         if timeout <= 0:
             raise RuntimeError('only blocking sockets are supported')
         sock.settimeout(timeout)
 
-        try:
-            sock.bind(addr)
-            sock.listen(backlog)
-        except OSError as ex:
-            sock.close()
-            raise ex
-
         return TestThreadedServer(
             self, sock, server_prog, timeout, max_clients)
 

Lib/test/test_asyncio/test_events.py

@@ -667,9 +667,7 @@ def data_received(self, data):
                 super().data_received(data)
                 self.transport.write(expected_response)
 
-        lsock = socket.socket()
-        lsock.bind(('127.0.0.1', 0))
-        lsock.listen(1)
+        lsock = socket.create_server(('127.0.0.1', 0), backlog=1)
         addr = lsock.getsockname()
 
         message = b'test data'
@@ -1118,9 +1116,7 @@ def connection_made(self, transport):
                 super().connection_made(transport)
                 proto.set_result(self)
 
-        sock_ob = socket.socket(type=socket.SOCK_STREAM)
-        sock_ob.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        sock_ob.bind(('0.0.0.0', 0))
+        sock_ob = socket.create_server(('0.0.0.0', 0))
 
         f = self.loop.create_server(TestMyProto, sock=sock_ob)
         server = self.loop.run_until_complete(f)
@@ -1136,9 +1132,7 @@ def connection_made(self, transport):
         server.close()
 
     def test_create_server_addr_in_use(self):
-        sock_ob = socket.socket(type=socket.SOCK_STREAM)
-        sock_ob.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        sock_ob.bind(('0.0.0.0', 0))
+        sock_ob = socket.create_server(('0.0.0.0', 0))
 
         f = self.loop.create_server(MyProto, sock=sock_ob)
         server = self.loop.run_until_complete(f)

Lib/test/test_asyncio/test_streams.py

@@ -592,8 +592,7 @@ async def handle_client(self, client_reader, client_writer):
                 await client_writer.wait_closed()
 
             def start(self):
-                sock = socket.socket()
-                sock.bind(('127.0.0.1', 0))
+                sock = socket.create_server(('127.0.0.1', 0))
                 self.server = self.loop.run_until_complete(
                     asyncio.start_server(self.handle_client,
                                          sock=sock,
@@ -605,8 +604,7 @@ def handle_client_callback(self, client_reader, client_writer):
                                                          client_writer))
 
             def start_callback(self):
-                sock = socket.socket()
-                sock.bind(('127.0.0.1', 0))
+                sock = socket.create_server(('127.0.0.1', 0))
                 addr = sock.getsockname()
                 sock.close()
                 self.server = self.loop.run_until_complete(
@@ -796,10 +794,7 @@ def test_drain_raises(self):
 
         def server():
             # Runs in a separate thread.
-            sock = socket.socket()
-            with sock:
-                sock.bind(('localhost', 0))
-                sock.listen(1)
+            with socket.create_server(('localhost', 0)) as sock:
                 addr = sock.getsockname()
                 q.put(addr)
                 clt, _ = sock.accept()

Lib/test/test_epoll.py

@@ -41,9 +41,7 @@
 class TestEPoll(unittest.TestCase):
 
     def setUp(self):
-        self.serverSocket = socket.socket()
-        self.serverSocket.bind(('127.0.0.1', 0))
-        self.serverSocket.listen()
+        self.serverSocket = socket.create_server(('127.0.0.1', 0))
         self.connections = [self.serverSocket]
 
     def tearDown(self):