diff options
Diffstat (limited to 'Doc/library/socketserver.rst')
| -rw-r--r-- | Doc/library/socketserver.rst | 61 |
1 files changed, 35 insertions, 26 deletions
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index f82f538816..9e0e9260c3 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -122,15 +122,21 @@ another way to manage this. Server Objects -------------- +.. class:: BaseServer -.. function:: fileno() + This is the superclass of all Server objects in the module. It defines the + interface, given below, but does not implement most of the methods, which is + done in subclasses. + + +.. method:: BaseServer.fileno() Return an integer file descriptor for the socket on which the server is listening. This function is most commonly passed to :func:`select.select`, to allow monitoring multiple servers in the same process. -.. function:: handle_request() +.. method:: BaseServer.handle_request() Process a single request. This function calls the following methods in order: :meth:`get_request`, :meth:`verify_request`, and @@ -141,30 +147,30 @@ Server Objects will return. -.. function:: serve_forever(poll_interval=0.5) +.. method:: BaseServer.serve_forever(poll_interval=0.5) Handle requests until an explicit :meth:`shutdown` request. Polls for shutdown every *poll_interval* seconds. -.. function:: shutdown() +.. method:: BaseServer.shutdown() Tells the :meth:`serve_forever` loop to stop and waits until it does. -.. data:: address_family +.. attribute:: BaseServer.address_family The family of protocols to which the server's socket belongs. Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`. -.. data:: RequestHandlerClass +.. attribute:: BaseServer.RequestHandlerClass The user-provided request handler class; an instance of this class is created for each request. -.. data:: server_address +.. attribute:: BaseServer.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 @@ -172,22 +178,22 @@ Server Objects the address, and an integer port number: ``('127.0.0.1', 80)``, for example. -.. data:: socket +.. attribute:: BaseServer.socket The socket object on which the server will listen for incoming requests. + The server classes support the following class variables: .. XXX should class variables be covered before instance variables, or vice versa? - -.. data:: allow_reuse_address +.. attribute:: BaseServer.allow_reuse_address Whether the server will allow the reuse of an address. This defaults to :const:`False`, and can be set in subclasses to change the policy. -.. data:: request_queue_size +.. attribute:: BaseServer.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 @@ -196,17 +202,19 @@ The server classes support the following class variables: value is usually 5, but this can be overridden by subclasses. -.. data:: socket_type +.. attribute:: BaseServer.socket_type The type of socket used by the server; :const:`socket.SOCK_STREAM` and :const:`socket.SOCK_DGRAM` are two common values. -.. data:: timeout + +.. attribute:: BaseServer.timeout Timeout duration, measured in seconds, or :const:`None` if no timeout is desired. If :meth:`handle_request` receives no incoming requests within the timeout period, the :meth:`handle_timeout` method is called. + There are various server methods that can be overridden by subclasses of base server classes like :class:`TCPServer`; these methods aren't useful to external users of the server object. @@ -214,27 +222,27 @@ users of the server object. .. XXX should the default implementations of these be documented, or should it be assumed that the user will look at socketserver.py? - -.. function:: finish_request() +.. method:: BaseServer.finish_request() Actually processes the request by instantiating :attr:`RequestHandlerClass` and calling its :meth:`handle` method. -.. function:: get_request() +.. method:: BaseServer.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. -.. function:: handle_error(request, client_address) +.. method:: BaseServer.handle_error(request, client_address) This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle` method raises an exception. The default action is to print the traceback to standard output and continue handling further requests. -.. function:: handle_timeout() + +.. method:: BaseServer.handle_timeout() This function is called when the :attr:`timeout` attribute has been set to a value other than :const:`None` and the timeout period has passed with no @@ -242,31 +250,32 @@ users of the server object. to collect the status of any child processes that have exited, while in threading servers this method does nothing. -.. function:: process_request(request, client_address) + +.. method:: BaseServer.process_request(request, client_address) Calls :meth:`finish_request` to create an instance of the :attr:`RequestHandlerClass`. If desired, this function can create a new process or thread to handle the request; the :class:`ForkingMixIn` and :class:`ThreadingMixIn` classes do this. + .. Is there any point in documenting the following two functions? What would the purpose of overriding them be: initializing server instance variables, adding new network families? - -.. function:: server_activate() +.. method:: BaseServer.server_activate() Called by the server's constructor to activate the server. The default behavior just :meth:`listen`\ s to the server's socket. May be overridden. -.. function:: server_bind() +.. method:: BaseServer.server_bind() Called by the server's constructor to bind the socket to the desired address. May be overridden. -.. function:: verify_request(request, client_address) +.. method:: BaseServer.verify_request(request, client_address) Must return a Boolean value; if the value is :const:`True`, the request will be processed, and if it's :const:`False`, the request will be denied. This function @@ -282,14 +291,14 @@ override any of the following methods. A new instance is created for each request. -.. function:: finish() +.. method:: RequestHandler.finish() Called after the :meth:`handle` method to perform any clean-up actions required. The default implementation does nothing. If :meth:`setup` or :meth:`handle` raise an exception, this function will not be called. -.. function:: handle() +.. method:: RequestHandler.handle() This function must do all the work required to service a request. The default implementation does nothing. Several instance attributes are @@ -308,7 +317,7 @@ request. data or return data to the client. -.. function:: setup() +.. method:: RequestHandler.setup() Called before the :meth:`handle` method to perform any initialization actions required. The default implementation does nothing. |