SocketServer
The SocketServer
module simplifies the task of writing network
servers.
There are four basic server classes: TCPServer
uses the
Internet TCP protocol, which provides for continuous streams of data
between the client and server. UDPServer
uses datagrams, which
are discrete packets of information that may arrive out of order or be
lost while in transit. The more infrequently used
UnixStreamServer
and UnixDatagramServer
classes are
similar, but use Unix domain sockets; they're not available on
non-Unix platforms. For more details on network programming, consult
a book such as W. Richard Steven's UNIX Network Programming
or Ralph Davis's Win32 Network Programming.
These four classes process requests synchronously; each request
must be completed before the next request can be started. This isn't
suitable if each request takes a long time to complete, because it
requires a lot of computation, or because it returns a lot of data
which the client is slow to process. The solution is to create a
separate process or thread to handle each request; the
ForkingMixIn
and ThreadingMixIn
mix-in classes can be
used to support asynchronous behaviour.
Creating a server requires several steps. First, you must create a
request handler class by subclassing the BaseRequestHandler
class and overriding its handle()
method; this method will
process incoming requests. Second, you must instantiate one of the
server classes, passing it the server's address and the request
handler class. Finally, call the handle_request()
or
serve_forever()
method of the server object to process one or
many requests.
Server classes have the same external methods and attributes, no matter what network protocol they use:
select.select()
, to allow monitoring multiple servers in the
same process.
get_request()
, verify_request()
, and
process_request()
. If the user-provided handle()
method
of the handler class raises an exception, the server's
handle_error()
method will be called.
handle_request()
inside an infinite loop.
socket.AF_INET
and socket.AF_UNIX
are two possible values.
('127.0.0.1', 80)
, for example.
The server classes support the following class variables:
request_queue_size
requests. Once
the queue is full, further requests from clients will get a
``Connection denied'' error. The default value is usually 5, but this
can be overridden by subclasses.
socket.SOCK_STREAM
and
socket.SOCK_DGRAM
are two possible values.
There are various server methods that can be overridden by subclasses
of base server classes like TCPServer
; these methods aren't
useful to external users of the server object.
RequestHandlerClass
and calling its handle()
method.
RequestHandlerClass
's
handle
method raises an exception. The default action is to print
the traceback to standard output and continue handling further requests.
finish_request()
to create an instance of the
RequestHandlerClass
. If desired, this function can create a new
process or thread to handle the request; the ForkingMixIn
and
ThreadingMixIn
classes do this.
The request handler class must define a new handle
method, and
can override any of the following methods. A new instance is created
for each request.
handle
method to perform any clean-up actions
required. The default implementation does nothing. If setup()
or handle()
raise an exception, this function will not be called.
self.request
; the client address as
self.client_request
; and the server instance as self.server
, in
case it needs access to per-server information.
The type of self.request
is different for datagram or stream
services. For stream services, self.request
is a socket
object; for datagram services, self.request
is a string.
However, this can be hidden by using the mix-in request handler
classes
StreamRequestHandler
or DatagramRequestHandler
, which
override the setup
and finish
methods, and provides
self.rfile
and self.wfile
attributes. self.rfile
and self.wfile
can be read or written, respectively, to get the
request data or return data to the client.
handle
method to perform any initialization
actions required. The default implementation does nothing.