diff --git a/Lib/socketserver.py b/Lib/socketserver.py index 6e1ae9f..e14cf36 100644 --- a/Lib/socketserver.py +++ b/Lib/socketserver.py @@ -59,14 +59,25 @@ 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. +To implement a service, create a factory function that instantiates +and starts a new request handler and assign this function to the +RequestHandlerClass parameter of the server constructor. You can then +run various versions of the service by combining one of the server +classes with your factory function. + +The name 'RequestHandlerClass' is an historical misnomer. The factory +function does not have to be a class, though a class can do the job if +the constructor handles and finishes the request. A BaseRequestHandler +class is provided in case this approach suits your need. The methods +setup, handle and finish of this base class are used internally +by the constructor. They will be ignored by the server. + +Any handler can be used, but it must be different for datagram or +stream services. In particular, the datagram request includes the data +and has no connection to receive subsequent data in the same request. +You can also look at the subclasses StreamRequestHandler and +DatagramRequestHandler of BaseRequestHandler or directly use them as +these provide ways to hide some differences. Of course, you still have to use your head! @@ -193,7 +204,7 @@ class BaseServer: Instance variables: - - RequestHandlerClass + - RequestHandlerClass # historical misnomer; you can assign a factory function. - socket """ @@ -267,8 +278,8 @@ class BaseServer: # - get_request() is different for stream or datagram sockets # - process_request() is the place that may fork a new process or create a # new thread to finish the request - # - finish_request() instantiates the request handler class; this - # constructor will handle the request all by itself + # - finish_request() calls the factory function, which instantiates and + # starts the handler; this handler will handle the request all by itself. def handle_request(self): """Handle one request, possibly blocking. @@ -672,7 +683,8 @@ class BaseRequestHandler: """Base class for request handler classes. - This class is instantiated for each request to be handled. The + If assigned to the RequestHandlerClass parameter of the server, + 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 @@ -684,6 +696,9 @@ class BaseRequestHandler: separate instance is created for each request, the handle() method can define other arbitrary instance variables. + Recall: The name 'RequestHandlerClass' is an historical misnomer. + Any factory function that instantiates and starts a request + handler can be assigned to this parameter. """ def __init__(self, request, client_address, server):