[Python-Dev] server modules class diagram

[aurora]

Hi I don't know if I'm sending this to the right mailing list. Anyway
I have gone through the Python server module code so many times. I
actually come up with a class diagram to help me navigate it. I wonder
if this would be useful in offical documentation. Please let me know
if this is not the right mailing list for documentations. (The class
diagram show be viewed with monospace fonts.)

Wai Yip Tung


---------------------------------------------------------------------------------------
Standard Python Modules for implementing network servers

...Some description on the collection of classes...

There are two important line of classes. The BaseServer and its
subclasses handle network connections. The BaseRequestHandler and its
subclasses handle the message.

...ForkingMixIn v.s. synchronized...

...mention asyncore, mention cgi...



                       ***************************
                       * The SocketServer module *
                       ***************************

-------------------------------
BaseServer
-------------------------------
An abstract class that defines
the main method handle_request()
with pseudo code like below:
                                     -------------------------------
def handle_request():                ForkingMixIn
  req = get_request()                -------------------------------
  if verify_request(req):            Overrides process_request() to
  try:                               fork process to handle each
    process_request(req)             request. Handles error in the
  except:                            child process.
    handle_error(req)                -------------------------------
    close_request(req)

def process_request(req):            -------------------------------
  finish_request(req)                ThreadingMixIn
  close_request(req)                 -------------------------------
                                     Overrides process_request() to
def finish_request(req):             spawn new thread to handle each
  instantiates                       request. Handles error in the
    RequestHandlerClass(req)         child thread.
                                     -------------------------------
Other than handle_request(),
all methods may be overridden.
-------------------------------
            ^
            |
-------------------------------
TCPServer
-------------------------------          -------------------------------
Creates a STREAM socket, then            BaseRequestHandler
bind() and listen() to it.               -------------------------------
                                         Abstract base class that calls
Implements get_request() to use          setup(), handle() and finish()
socket.accept()                          methods.
-------------------------------          -------------------------------
  ^         ^                                        ^
  |         |                                        |
  |   ----------------------------       -------------------------------
  |   UDPServer                          StreamRequestHandler
  |   ----------------------------       -------------------------------
  |   Creates DGRAM socket.              Implements setup() and finish()
  |                                      to create the rfile/wfile
  |   Overrides get_request() to         object from the socket
  |   use socket.recvfrom().             connection.
  |   ----------------------------       -------------------------------
  |                                                  ^
  |                                                  |
  |                                                  |
  |                                                  |
  |                *****************************     |
  |                * The BaseHTTPServer module *     |
  |                *****************************     |
  |                                                  |
  |                                                  |
-------------------------------          -------------------------------
HTTPServer                               BaseHTTPRequestHandler
-------------------------------          -------------------------------
Overrides server_bind to store           Implements handle(). Calls
the server name.                         handle_one_request() to parse
-------------------------------          HTTP request and invoke the
                                         corresponding do_XXX methods.

                                         handle_one_request() are called
                                         once for each HTTP request in a
                                         persistent connection.
                                         -------------------------------
                                                     ^
                                                     |
                                                     |
                    ************************         |
                    * The SimpleHTTPServer *         |
                    ************************         |
                                                     |
                                                     |
                                         -------------------------------
                                         SimpleHTTPRequestHandler
                                         -------------------------------
                                         Implements do_GET() to serve
                                         files mapped to URL path.
                                         -------------------------------
                                                     ^
                                                     |
                                                     |
                   ****************************      |
                   * The CGIHTTPServer module *      |
                   ****************************      |
                                                     |
                                                     |
                                         -------------------------------
                                         CGIHTTPRequestHandler
                                         -------------------------------
                                         Implements do_POST() to find,
                                         prepare and invoke CGI programs.
                                         -------------------------------


Some observations

1. One exception to the Server / RequestHandler division is the
   BaseHTTPRequestHandler.handle() method. The request handler is
   responsible to break down multiple HTTP messages from a persistent
   TCP connection (See RFC 2616 section 8.1).

2. Strictly speaking UDPServer should not be a specialization of
   TCPServer.

3. The BaseServer.finish_request() is a bit of a misnomer. From there it
   instantiates a RequestHandler where most application logic actually
   begins.

4. Note that BaseRequestHandler put most application logic in the
   __init__ method. (Unfortunately this does not give the caller much
   fine control. Also when an exception is thrown in __init__, the
   object reference is not available at all). Also notice that finish()
   is not in a finally clause and may not be called when an exception is
   thrown.