Module Expr Str Assign NameStore Str Import alias Import alias Import alias Assign NameStore ListLoad Str Str Str Str Str Str Str Str Str Str Str If Call NameLoad NameLoad Str body Expr Call AttributeLoad NameLoad attr ListLoad Str Str Str Str ClassDef bases body Expr Str FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Str Pass decorator_list FunctionDef arguments args NameParam defaults body Expr Str While Num body Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str TryExcept body Assign TupleStore NameStore NameStore Call AttributeLoad NameLoad attr handlers ExceptHandler type AttributeLoad NameLoad attr body Return If Call AttributeLoad NameLoad attr NameLoad NameLoad body TryExcept body Expr Call AttributeLoad NameLoad attr NameLoad NameLoad handlers ExceptHandler body Expr Call AttributeLoad NameLoad attr NameLoad NameLoad Expr Call AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Return NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Expr Call AttributeLoad NameLoad attr NameLoad NameLoad Expr Call AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Str Pass decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Expr Call AttributeLoad NameLoad attr NameLoad NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Pass decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Print BinOpMult Str Num Print Str Print NameLoad Import alias Expr Call AttributeLoad NameLoad attr Print BinOpMult Str Num decorator_list decorator_list ClassDef bases NameLoad body Expr Str Assign NameStore AttributeLoad NameLoad attr Assign NameStore AttributeLoad NameLoad attr Assign NameStore Num Assign NameStore NameLoad FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Expr Call AttributeLoad NameLoad attr NameLoad NameLoad NameLoad Assign AttributeStore NameLoad attr Call AttributeLoad NameLoad attr AttributeLoad NameLoad attr AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str If AttributeLoad NameLoad attr body Expr Call AttributeLoad AttributeLoad NameLoad attr attr AttributeLoad NameLoad attr AttributeLoad NameLoad attr Num Expr Call AttributeLoad AttributeLoad NameLoad attr attr AttributeLoad NameLoad attr Assign AttributeStore NameLoad attr Call AttributeLoad AttributeLoad NameLoad attr attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Expr Call AttributeLoad AttributeLoad NameLoad attr attr AttributeLoad NameLoad attr Assign AttributeStore NameLoad attr Call AttributeLoad AttributeLoad NameLoad attr attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Expr Call AttributeLoad AttributeLoad NameLoad attr attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call AttributeLoad AttributeLoad NameLoad attr attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call AttributeLoad AttributeLoad NameLoad attr attr decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Expr Call AttributeLoad NameLoad attr decorator_list decorator_list ClassDef bases NameLoad body Expr Str Assign NameStore NameLoad Assign NameStore AttributeLoad NameLoad attr Assign NameStore Num FunctionDef arguments args NameParam defaults body Assign TupleStore NameStore NameStore Call AttributeLoad AttributeLoad NameLoad attr attr AttributeLoad NameLoad attr Return TupleLoad TupleLoad NameLoad AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body Pass decorator_list FunctionDef arguments args NameParam NameParam defaults body Pass decorator_list decorator_list ClassDef bases body Expr Str Assign NameStore NameLoad Assign NameStore Num FunctionDef arguments args NameParam defaults body Expr Str While AttributeLoad NameLoad attr body If CompareLt Call NameLoad AttributeLoad NameLoad attr AttributeLoad NameLoad attr body Assign NameStore AttributeLoad NameLoad attr orelse Assign NameStore Num TryExcept body Assign TupleStore NameStore NameStore Call AttributeLoad NameLoad attr Num NameLoad handlers ExceptHandler type AttributeLoad NameLoad attr body Assign NameStore NameLoad If UnaryOpNot NameLoad body Break Expr Call AttributeLoad AttributeLoad NameLoad attr attr NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Expr Call AttributeLoad NameLoad attr Assign NameStore Call AttributeLoad NameLoad attr If NameLoad body If CompareIs AttributeLoad NameLoad attr NameLoad body Assign AttributeStore NameLoad attr ListLoad Expr Call AttributeLoad AttributeLoad NameLoad attr attr NameLoad Expr Call AttributeLoad NameLoad attr NameLoad Return orelse TryExcept body Expr Call AttributeLoad NameLoad attr NameLoad NameLoad Expr Call AttributeLoad NameLoad attr Num handlers ExceptHandler body TryFinally body Expr Call AttributeLoad NameLoad attr NameLoad NameLoad finalbody Expr Call AttributeLoad NameLoad attr Num decorator_list decorator_list ClassDef bases body Expr Str Assign NameStore NameLoad FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str TryExcept body Expr Call AttributeLoad NameLoad attr NameLoad NameLoad Expr Call AttributeLoad NameLoad attr NameLoad handlers ExceptHandler body Expr Call AttributeLoad NameLoad attr NameLoad NameLoad Expr Call AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body Expr Str Import alias Assign NameStore Call AttributeLoad NameLoad attr keyword AttributeLoad NameLoad attr keyword TupleLoad NameLoad NameLoad If AttributeLoad NameLoad attr body Expr Call AttributeLoad NameLoad attr Num Expr Call AttributeLoad NameLoad attr decorator_list decorator_list ClassDef bases NameLoad NameLoad body Pass decorator_list ClassDef bases NameLoad NameLoad body Pass decorator_list ClassDef bases NameLoad NameLoad body Pass decorator_list ClassDef bases NameLoad NameLoad body Pass decorator_list If Call NameLoad NameLoad Str body ClassDef bases NameLoad body Assign NameStore AttributeLoad NameLoad attr decorator_list ClassDef bases NameLoad body Assign NameStore AttributeLoad NameLoad attr decorator_list ClassDef bases NameLoad NameLoad body Pass decorator_list ClassDef bases NameLoad NameLoad body Pass decorator_list ClassDef bases body Expr Str FunctionDef arguments args NameParam NameParam NameParam NameParam defaults body Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr NameLoad Expr Call AttributeLoad NameLoad attr TryFinally body Expr Call AttributeLoad NameLoad attr finalbody Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Pass decorator_list FunctionDef arguments args NameParam defaults body Pass decorator_list FunctionDef arguments args NameParam defaults body Pass decorator_list decorator_list ClassDef bases NameLoad body Expr Str Assign NameStore Num Assign NameStore Num FunctionDef arguments args NameParam defaults body Assign AttributeStore NameLoad attr AttributeLoad NameLoad attr Assign AttributeStore NameLoad attr Call AttributeLoad AttributeLoad NameLoad attr attr Str AttributeLoad NameLoad attr Assign AttributeStore NameLoad attr Call AttributeLoad AttributeLoad NameLoad attr attr Str AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body If UnaryOpNot AttributeLoad AttributeLoad NameLoad attr attr body Expr Call AttributeLoad AttributeLoad NameLoad attr attr Expr Call AttributeLoad AttributeLoad NameLoad attr attr Expr Call AttributeLoad AttributeLoad NameLoad attr attr decorator_list decorator_list ClassDef bases NameLoad body Expr Str FunctionDef arguments args NameParam defaults body TryExcept body ImportFrom alias handlers ExceptHandler type NameLoad body ImportFrom alias Assign TupleStore AttributeStore NameLoad attr AttributeStore NameLoad attr AttributeLoad NameLoad attr Assign AttributeStore NameLoad attr Call NameLoad AttributeLoad NameLoad attr Assign AttributeStore NameLoad attr Call NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Call AttributeLoad AttributeLoad NameLoad attr attr Call AttributeLoad AttributeLoad NameLoad attr attr AttributeLoad NameLoad attr decorator_list decorator_list
N/A N/A Generic socket server classes.

This module tries to capture the various aspects of defining a server:

For socket-based servers:

- address family:
        - AF_INET{,6}: IP (Internet Protocol) sockets (default)
        - AF_UNIX: Unix domain sockets
        - others, e.g. AF_DECNET are conceivable (see <socket.h>
- socket type:
        - SOCK_STREAM (reliable stream, e.g. TCP)
        - SOCK_DGRAM (datagrams, e.g. UDP)

For request-based servers (including socket-based):

- client address verification before further looking at the request
        (This is actually a hook for any processing that needs to look
         at the request before anything else, e.g. logging)
- how to handle multiple requests:
        - synchronous (one request is handled at a time)
        - forking (each request is handled by a new process)
        - threading (each request is handled by a new thread)

The classes in this module favor the server type that is simplest to
write: a synchronous TCP/IP server.  This is bad class design, but
save some typing.  (There's also the issue that a deep class hierarchy
slows down method lookups.)

There are five classes in an inheritance diagram, four of which represent
synchronous servers of four types:

        +------------+
        | BaseServer |
        +------------+
              |
              v
        +-----------+        +------------------+
        | TCPServer |------->| UnixStreamServer |
        +-----------+        +------------------+
              |
              v
        +-----------+        +--------------------+
        | UDPServer |------->| UnixDatagramServer |
        +-----------+        +--------------------+

Note that UnixDatagramServer derives from UDPServer, not from
UnixStreamServer -- the only difference between an IP and a Unix
stream server is the address family, which is simply repeated in both
unix server classes.

Forking and threading versions of each type of server can be created
using the ForkingMixIn and ThreadingMixIn mix-in classes.  For
instance, a threading UDP server class is created as follows:

        class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass

The Mix-in class must come first, since it overrides a method defined
in UDPServer! Setting the various member variables also changes
the behavior of the underlying server mechanism.

To implement a service, you must derive a class from
BaseRequestHandler and redefine its handle() method.  You can then run
various versions of the service by combining one of the server classes
with your request handler class.

The request handler class must be different for datagram or stream
services.  This can be hidden by using the request handler
subclasses StreamRequestHandler or DatagramRequestHandler.

Of course, you still have to use your head!

For instance, it makes no sense to use a forking server if the service
contains state in memory that can be modified by requests (since the
modifications in the child process would never reach the initial state
kept in the parent process and passed to each child).  In this case,
you can use a threading server, but you will probably have to use
locks to avoid two requests that come in nearly simultaneous to apply
conflicting changes to the server state.

On the other hand, if you are building e.g. an HTTP server, where all
data is stored externally (e.g. in the file system), a synchronous
class will essentially render the service "deaf" while one request is
being handled -- which may be for a very long time if a client is slow
to reqd all the data it has requested.  Here a threading or forking
server is appropriate.

In some cases, it may be appropriate to process part of a request
synchronously, but to finish processing in a forked child depending on
the request data.  This can be implemented by using a synchronous
server and doing an explicit fork in the request handler class
handle() method.

Another approach to handling multiple simultaneous requests in an
environment that supports neither threads nor fork (or where these are
too expensive or inappropriate for the service) is to maintain an
explicit table of partially finished requests and to use select() to
decide which request to work on next (or whether to handle a new
incoming request).  This is particularly important for stream services
where each client can potentially be connected for a long time (if
threads or subprocesses cannot be used).

Future work:
- Standard classes for Sun RPC (which uses either UDP or TCP)
- Standard mix-in classes to implement various authentication
  and encryption schemes
- Standard framework for select-based multiplexing

XXX Open problems:
- What to do with out-of-band data?

BaseServer:
- split generic "request" functionality out into BaseServer class.
  Copyright (C) 2000  Luke Kenneth Casson Leighton <lkcl@samba.org>

  example: read entries from a SQL database (requires overriding
  get_request() to return a table entry from the database).
  entry is processed by a RequestHandlerClass.

 N/A __version__ 0.4 N/A socket N/A sys N/A os N/A __all__ N/A TCPServer UDPServer ForkingUDPServer ForkingTCPServer ThreadingUDPServer ThreadingTCPServer BaseRequestHandler StreamRequestHandler DatagramRequestHandler ThreadingMixIn ForkingMixIn N/A N/A hasattr socket AF_UNIX N/A N/A N/A N/A __all__ extend N/A UnixStreamServer UnixDatagramServer ThreadingUnixStreamServer ThreadingUnixDatagramServer BaseServer N/A N/A N/A Base class for server classes.

    Methods for the caller:

    - __init__(server_address, RequestHandlerClass)
    - serve_forever()
    - handle_request()  # if you do not use serve_forever()
    - fileno() -> int   # for select()

    Methods that may be overridden:

    - server_bind()
    - server_activate()
    - get_request() -> request, client_address
    - verify_request(request, client_address)
    - server_close()
    - process_request(request, client_address)
    - close_request(request)
    - handle_error()

    Methods for derived classes:

    - finish_request(request, client_address)

    Class variables that may be overridden by derived classes or
    instances:

    - address_family
    - socket_type
    - allow_reuse_address

    Instance variables:

    - RequestHandlerClass
    - socket

     __init__ N/A N/A self server_address RequestHandlerClass N/A N/A N/A Constructor.  May be extended, do not override. N/A N/A self server_address server_address N/A N/A self RequestHandlerClass RequestHandlerClass N/A server_activate N/A N/A self N/A N/A N/A Called by constructor to activate the server.

        May be overridden.

         N/A N/A serve_forever N/A N/A self N/A N/A N/A Handle one request at a time until doomsday. N/A 1 N/A N/A N/A N/A self handle_request N/A handle_request N/A N/A self N/A N/A N/A Handle one request, possibly blocking. N/A N/A N/A N/A request client_address N/A N/A self get_request N/A N/A N/A N/A socket error N/A N/A N/A N/A N/A self verify_request request client_address N/A N/A N/A N/A N/A N/A self process_request request client_address N/A N/A N/A N/A N/A N/A self handle_error request client_address N/A N/A N/A self close_request request N/A verify_request N/A N/A self request client_address N/A N/A N/A Verify the request.  May be overridden.

        Return True if we should proceed with this request.

         N/A True N/A process_request N/A N/A self request client_address N/A N/A N/A Call finish_request.

        Overridden by ForkingMixIn and ThreadingMixIn.

         N/A N/A N/A self finish_request request client_address N/A N/A N/A self close_request request N/A server_close N/A N/A self N/A N/A N/A Called to clean-up the server.

        May be overridden.

         N/A N/A finish_request N/A N/A self request client_address N/A N/A N/A Finish one request by instantiating RequestHandlerClass. N/A N/A N/A self RequestHandlerClass request client_address self N/A close_request N/A N/A self request N/A N/A N/A Called to clean up an individual request. N/A N/A handle_error N/A N/A self request client_address N/A N/A N/A Handle an error gracefully.  May be overridden.

        The default is to print a traceback and continue.

         N/A N/A - 40 N/A Exception happened during processing of request from N/A client_address N/A traceback N/A N/A N/A traceback print_exc N/A N/A - 40 N/A N/A TCPServer N/A BaseServer N/A N/A Base class for various socket-based server classes.

    Defaults to synchronous IP stream (i.e., TCP).

    Methods for the caller:

    - __init__(server_address, RequestHandlerClass)
    - serve_forever()
    - handle_request()  # if you don't use serve_forever()
    - fileno() -> int   # for select()

    Methods that may be overridden:

    - server_bind()
    - server_activate()
    - get_request() -> request, client_address
    - verify_request(request, client_address)
    - process_request(request, client_address)
    - close_request(request)
    - handle_error()

    Methods for derived classes:

    - finish_request(request, client_address)

    Class variables that may be overridden by derived classes or
    instances:

    - address_family
    - socket_type
    - request_queue_size (only for stream sockets)
    - allow_reuse_address

    Instance variables:

    - server_address
    - RequestHandlerClass
    - socket

     N/A address_family N/A socket AF_INET N/A socket_type N/A socket SOCK_STREAM N/A request_queue_size 5 N/A allow_reuse_address False __init__ N/A N/A self server_address RequestHandlerClass N/A N/A N/A Constructor.  May be extended, do not override. N/A N/A N/A BaseServer __init__ self server_address RequestHandlerClass N/A N/A self socket N/A N/A socket socket N/A self address_family N/A self socket_type N/A N/A N/A self server_bind N/A N/A N/A self server_activate N/A server_bind N/A N/A self N/A N/A N/A Called by constructor to bind the socket.

        May be overridden.

         N/A N/A self allow_reuse_address N/A N/A N/A N/A N/A self socket setsockopt N/A socket SOL_SOCKET N/A socket SO_REUSEADDR 1 N/A N/A N/A N/A self socket bind N/A self server_address N/A N/A self server_address N/A N/A N/A self socket getsockname N/A server_activate N/A N/A self N/A N/A N/A Called by constructor to activate the server.

        May be overridden.

         N/A N/A N/A N/A self socket listen N/A self request_queue_size N/A N/A self server_address N/A N/A N/A self socket getsockname N/A server_close N/A N/A self N/A N/A N/A Called to clean-up the server.

        May be overridden.

         N/A N/A N/A N/A self socket close N/A fileno N/A N/A self N/A N/A N/A Return socket file number.

        Interface required by select().

         N/A N/A N/A N/A self socket fileno N/A get_request N/A N/A self N/A N/A N/A Get the request and client address from the socket.

        May be overridden.

         N/A N/A N/A N/A self socket accept N/A close_request N/A N/A self request N/A N/A N/A Called to clean up an individual request. N/A N/A N/A request close N/A N/A UDPServer N/A TCPServer N/A N/A UDP server class. N/A allow_reuse_address False N/A socket_type N/A socket SOCK_DGRAM N/A max_packet_size 8192 get_request N/A N/A self N/A N/A N/A N/A data client_addr N/A N/A N/A self socket recvfrom N/A self max_packet_size N/A N/A N/A data N/A self socket client_addr N/A server_activate N/A N/A self N/A N/A N/A N/A close_request N/A N/A self request N/A N/A N/A N/A N/A ForkingMixIn N/A N/A N/A Mix-in class to handle each request in a new process. N/A active_children None N/A max_children 40 collect_children N/A N/A self N/A N/A N/A Internal routine to wait for died children. N/A N/A self active_children N/A N/A N/A N/A len N/A self active_children N/A self max_children N/A N/A options N/A os WNOHANG N/A N/A options 0 N/A N/A N/A N/A pid status N/A N/A os waitpid 0 options N/A N/A N/A N/A os error N/A N/A pid None N/A N/A pid N/A N/A N/A N/A N/A N/A self active_children remove pid N/A process_request N/A N/A self request client_address N/A N/A N/A Fork a new subprocess to process the request. N/A N/A N/A self collect_children N/A pid N/A N/A os fork N/A pid N/A N/A N/A N/A self active_children None N/A N/A N/A self active_children N/A N/A N/A N/A N/A self active_children append pid N/A N/A N/A self close_request request N/A N/A N/A N/A N/A N/A N/A self finish_request request client_address N/A N/A N/A os _exit 0 N/A N/A N/A N/A N/A N/A N/A N/A self handle_error request client_address N/A N/A N/A N/A os _exit 1 N/A N/A ThreadingMixIn N/A N/A N/A Mix-in class to handle each request in a new thread. N/A daemon_threads False process_request_thread N/A N/A self request client_address N/A N/A N/A Same as in BaseServer but as a thread.

        In addition, exception handling is done here.

         N/A N/A N/A N/A N/A self finish_request request client_address N/A N/A N/A self close_request request N/A N/A N/A N/A N/A N/A self handle_error request client_address N/A N/A N/A self close_request request N/A process_request N/A N/A self request client_address N/A N/A N/A Start a new thread to process the request. N/A threading N/A t N/A N/A threading Thread target N/A self process_request_thread args N/A request client_address N/A N/A self daemon_threads N/A N/A N/A N/A t setDaemon 1 N/A N/A N/A t start N/A N/A ForkingUDPServer N/A ForkingMixIn UDPServer N/A N/A N/A ForkingTCPServer N/A ForkingMixIn TCPServer N/A N/A N/A ThreadingUDPServer N/A ThreadingMixIn UDPServer N/A N/A N/A ThreadingTCPServer N/A ThreadingMixIn TCPServer N/A N/A N/A N/A N/A hasattr socket AF_UNIX N/A UnixStreamServer N/A TCPServer N/A N/A address_family N/A socket AF_UNIX N/A UnixDatagramServer N/A UDPServer N/A N/A address_family N/A socket AF_UNIX N/A ThreadingUnixStreamServer N/A ThreadingMixIn UnixStreamServer N/A N/A N/A ThreadingUnixDatagramServer N/A ThreadingMixIn UnixDatagramServer N/A N/A N/A BaseRequestHandler N/A N/A N/A Base class for request handler classes.

    This class is instantiated for each request to be handled.  The
    constructor sets the instance variables request, client_address
    and server, and then calls the handle() method.  To implement a
    specific service, all you need to do is to derive a class which
    defines a handle() method.

    The handle() method can find the request as self.request, the
    client address as self.client_address, and the server (in case it
    needs access to per-server information) as self.server.  Since a
    separate instance is created for each request, the handle() method
    can define arbitrary other instance variariables.

     __init__ N/A N/A self request client_address server N/A N/A N/A N/A self request request N/A N/A self client_address client_address N/A N/A self server server N/A N/A N/A self setup N/A N/A N/A N/A N/A self handle N/A N/A N/A N/A self finish N/A setup N/A N/A self N/A N/A N/A N/A handle N/A N/A self N/A N/A N/A N/A finish N/A N/A self N/A N/A N/A N/A N/A StreamRequestHandler N/A BaseRequestHandler N/A N/A Define self.rfile and self.wfile for stream sockets. N/A rbufsize -1 N/A wbufsize 0 setup N/A N/A self N/A N/A N/A N/A self connection N/A self request N/A N/A self rfile N/A N/A N/A self connection makefile rb N/A self rbufsize N/A N/A self wfile N/A N/A N/A self connection makefile wb N/A self wbufsize N/A finish N/A N/A self N/A N/A N/A N/A N/A N/A self wfile closed N/A N/A N/A N/A N/A self wfile flush N/A N/A N/A N/A self wfile close N/A N/A N/A N/A self rfile close N/A N/A DatagramRequestHandler N/A BaseRequestHandler N/A N/A Define self.rfile and self.wfile for datagram sockets. setup N/A N/A self N/A N/A N/A N/A cStringIO StringIO N/A N/A N/A ImportError N/A StringIO StringIO N/A N/A N/A self packet N/A self socket N/A self request N/A N/A self rfile N/A StringIO N/A self packet N/A N/A self wfile N/A StringIO N/A finish N/A N/A self N/A N/A N/A N/A N/A N/A self socket sendto N/A N/A N/A self wfile getvalue N/A self client_address N/A N/A