Fix issue 6706: adds new handle_accepted() method to asyncore.dispatcher

Doc/library/asyncore.rst

@@ -86,7 +86,7 @@ any that have been added to the map during asynchronous service) is closed.
    | ``handle_close()``   | Implied by a read event with no data   |
    |                      | available                              |
    +----------------------+----------------------------------------+
-   | ``handle_accept()``  | Implied by a read event on a listening |
+   | ``handle_accepted()``| Implied by a read event on a listening |
    |                      | socket                                 |
    +----------------------+----------------------------------------+
 
@@ -144,8 +144,20 @@ any that have been added to the map during asynchronous service) is closed.
 
       Called on listening channels (passive openers) when a connection can be
       established with a new remote endpoint that has issued a :meth:`connect`
-      call for the local endpoint.
+      call for the local endpoint. Deprecated in version 3.2; use
+      :meth:`handle_accepted` instead.
 
+   .. deprecated:: 3.2
+
+   .. method:: handle_accepted(sock, addr)
+
+      Called on listening channels (passive openers) when a connection has been
+      established with a new remote endpoint that has issued a :meth:`connect`
+      call for the local endpoint.  *conn* is a *new* socket object usable to
+      send and receive data on the connection, and *address* is the address
+      bound to the socket on the other end of the connection.
+
+   .. versionadded:: 3.2
 
    .. method:: readable()
 
@@ -210,10 +222,13 @@ any that have been added to the map during asynchronous service) is closed.
    .. method:: accept()
 
       Accept a connection.  The socket must be bound to an address and listening
-      for connections.  The return value is a pair ``(conn, address)`` where
-      *conn* is a *new* socket object usable to send and receive data on the
-      connection, and *address* is the address bound to the socket on the other
-      end of the connection.
+      for connections.  The return value can be either ``None`` or a pair
+      ``(conn, address)`` where *conn* is a *new* socket object usable to send
+      and receive data on the connection, and *address* is the address bound to
+      the socket on the other end of the connection.
+      When ``None`` is returned it means the connection didn't take place, in
+      which case the server should just ignore this event and keep listening
+      for further incoming connections.
 
 
    .. method:: close()
@@ -223,6 +238,13 @@ any that have been added to the map during asynchronous service) is closed.
       flushed).  Sockets are automatically closed when they are
       garbage-collected.
 
+
+.. class:: dispatcher_with_send()
+
+   A :class:`dispatcher` subclass which adds simple buffered output capability,
+   useful for simple clients. For more sophisticated usage use
+   :class:`asynchat.async_chat`.
+
 .. class:: file_dispatcher()
 
    A file_dispatcher takes a file descriptor or :term:`file object` along
@@ -239,7 +261,7 @@ any that have been added to the map during asynchronous service) is closed.
    socket for use by the :class:`file_dispatcher` class.  Availability: UNIX.
 
 
-.. _asyncore-example:
+.. _asyncore-example-1:
 
 asyncore Example basic HTTP client
 ----------------------------------
@@ -249,7 +271,7 @@ implement its socket handling::
 
    import asyncore, socket
 
-   class http_client(asyncore.dispatcher):
+   class HTTPClient(asyncore.dispatcher):
 
        def __init__(self, host, path):
            asyncore.dispatcher.__init__(self)
@@ -273,6 +295,40 @@ implement its socket handling::
            sent = self.send(self.buffer)
            self.buffer = self.buffer[sent:]
 
-   c = http_client('www.python.org', '/')
 
-   asyncore.loop()
+    client = HTTPClient('www.python.org', '/')
+    asyncore.loop()
+
+.. _asyncore-example-2:
+
+asyncore Example basic echo server
+----------------------------------
+
+Here is abasic echo server that uses the :class:`dispatcher` class to accept
+connections and dispatches the incoming connections to a handler::
+
+    import asyncore
+    import socket
+
+    class EchoHandler(asyncore.dispatcher_with_send):
+
+        def handle_read(self):
+            data = self.recv(8192)
+            self.send(data)
+
+    class EchoServer(asyncore.dispatcher):
+
+        def __init__(self, host, port):
+            asyncore.dispatcher.__init__(self)
+            self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.set_reuse_addr()
+            self.bind((host, port))
+            self.listen(5)
+
+        def handle_accepted(self, sock, addr):
+            print('Incoming connection from %s' % repr(addr))
+            handler = EchoHandler(sock)
+
+    server = EchoServer('localhost', 8080)
+    asyncore.loop()
+