GNU Info
(python2.1-lib.info)SocketServer
A framework for network servers
===============================
A framework for network servers.
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 or
Ralph Davis's .
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:
`fileno()'
Return an integer file descriptor for the socket on which the
server is listening. This function is most commonly passed to
`select.select()', to allow monitoring multiple servers in the
same process.
`handle_request()'
Process a single request. This function calls the following
methods in order: `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.
`serve_forever()'
Handle an infinite number of requests. This simply calls
`handle_request()' inside an infinite loop.
`address_family'
The family of protocols to which the server's socket belongs.
`socket.AF_INET' and `socket.AF_UNIX' are two possible values.
`RequestHandlerClass'
The user-provided request handler class; an instance of this class
is created for each request.
`server_address'
The address on which the server is listening. The format of
addresses varies depending on the protocol family; see the
documentation for the socket module for details. For Internet
protocols, this is a tuple containing a string giving the address,
and an integer port number: `('127.0.0.1', 80)', for example.
`socket'
The socket object on which the server will listen for incoming
requests.
The server classes support the following class variables:
`allow_reuse_address'
Whether the server will allow the reuse of an address. This
defaults to true, and can be set in subclasses to change the
policy.
`request_queue_size'
The size of the request queue. If it takes a long time to process
a single request, any requests that arrive while the server is
busy are placed into a queue, up to `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_type'
The type of socket used by the server; `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.
`finish_request()'
Actually processes the request by instantiating
`RequestHandlerClass' and calling its `handle()' method.
`get_request()'
Must accept a request from the socket, and return a 2-tuple
containing the _new_ socket object to be used to communicate with
the client, and the client's address.
`handle_error(request, client_address)'
This function is called if the `RequestHandlerClass''s `handle()'
method raises an exception. The default action is to print the
traceback to standard output and continue handling further
requests.
`process_request(request, client_address)'
Calls `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.
`server_activate()'
Called by the server's constructor to activate the server. May be
overridden.
`server_bind()'
Called by the server's constructor to bind the socket to the
desired address. May be overridden.
`verify_request(request, client_address)'
Must return a Boolean value; if the value is true, the request
will be processed, and if it's false, the request will be denied.
This function can be overridden to implement access controls for a
server. The default implementation always return true.
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.
`finish()'
Called after the `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.
`handle()'
This function must do all the work required to service a request.
Several instance attributes are available to it; the request is
available as `self.request'; the client address as
`self.client_address'; 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.
`setup()'
Called before the `handle()' method to perform any initialization
actions required. The default implementation does nothing.
automatically generated by info2www version 1.2.2.9