PEP 748: create_connection and create_server instead of connect

The `connect()` function is poorly named server-side as it actually
`bind()` the socket. Server-side the function lacks a `family` parameter
to support IPv6 without a DNS lookup.

Actually all three `connect()`, `bind()` and `listen()` socket function
are pretty low-level. The high-level `create_connection` (for `connect`)
and `create_server` (for `bind()` + `listen()`) are more pythonic. Wrap
the latter and not the former, also to remove the need of a `listen()`
method on the created socket (which is useless client-side).

Author: Julien00859

peps/pep-0748.rst

@@ -351,7 +351,15 @@ The ``ClientContext`` protocol class has the following class definition:
             ...
 
         @abstractmethod
-        def connect(self, address: tuple[str | None, int]) -> TLSSocket:
+        def create_connection(
+            self,
+            address: tuple[str | None, bytes | str | int | None],
+            timeout: float | None = ...,
+            source_address: _Address | None = None,
+            *,
+            all_errors: bool = False,
+            sever_hostname: str | None = None,
+        ) -> TLSSocket:
             """Creates a TLSSocket that behaves like a socket.socket, and
             contains information about the TLS exchange
             (cipher, negotiated_protocol, negotiated_tls_version, etc.).
@@ -382,9 +390,18 @@ The ``ServerContext`` protocol class has the following class definition:
             ...
 
         @abstractmethod
-        def connect(self, address: tuple[str | None, int]) -> TLSSocket:
-            """Creates a TLSSocket that behaves like a socket.socket, and
-            contains information about the TLS exchange
+        def create_server(
+            self,
+            address: _Address,
+            *,
+            family: int = socket.AF_INET,
+            backlog: int | None = None,
+            reuse_port: bool = False,
+            dualstack_ipv6: bool = False,
+        ) -> TLSSocket:
+            """Creates a listening socket with an accept() function that returns
+            a TLSSocket that behaves like a socket.socket, and contains
+            information about the TLS exchange
             (cipher, negotiated_protocol, negotiated_tls_version, etc.).
             """
             ...
@@ -404,7 +421,7 @@ specification of the ``TLSSocket`` protocol class. Specifically, implementations
 need to implement the following:
 
 * ``recv`` and ``send``
-* ``listen`` and ``accept``
+* ``accept`` (server-side)
 * ``close``
 * ``getsockname``
 * ``getpeername``
@@ -458,13 +475,6 @@ The following code describes these functions in more detail:
             close_notify alert currently fails."""
             ...
 
-        @abstractmethod
-        def listen(self, backlog: int) -> None:
-            """Enable a server to accept connections. If backlog is specified, it
-            specifies the number of unaccepted connections that the system will allow
-            before refusing new connections."""
-            ...
-
         @abstractmethod
         def accept(self) -> tuple[TLSSocket, tuple[str | None, int]]:
             """Accept a connection. The socket must be bound to an address and listening