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

1 files changed, 44 insertions, 1 deletions

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index d466884..b4a07bd 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -595,6 +595,50 @@ 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=0, reuse_port=False, dualstack_ipv6=False)
+
+   Convenience function which creates a TCP 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`; when ``0``
+   a default reasonable value is chosen.
+   *reuse_port* dictates whether to set the :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, else it will raise
+   :exc:`ValueError`. Most POSIX platforms and Windows are supposed to support
+   this functionality.
+   When this functionality is enabled the address returned by
+   :meth:`socket.getpeername` when an IPv4 connection occurs will be an IPv6
+   address represented as an IPv4-mapped IPv6 address.
+   If *dualstack_ipv6* is false it will explicitly disable this functionality
+   on platforms that enable it by default (e.g. Linux).
+   This parameter can be used in conjunction with :func:`has_dualstack_ipv6`:
+
+   ::
+
+     import socket
+
+     addr = ("", 8080)  # all interfaces, port 8080
+     if socket.has_dualstack_ipv6():
+         s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
+     else:
+         s = socket.create_server(addr)
+
+   .. note::
+    On POSIX platforms the :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 TCP socket which can
+   handle both IPv4 and IPv6 connections.
+
+   .. versionadded:: 3.8
 
 .. function:: fromfd(fd, family, type, proto=0)
 
@@ -1778,7 +1822,6 @@ sends traffic to the first one connected successfully. ::
        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::