Copyright (C) 2000-2012 |
GNU Info (python2.1-lib.info)SocketServerA 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 |