#1742837: expand HTTP server docs, and fix SocketServer ones to document methods as methods, not functions.
This commit is contained in:
Georg Brandl
parent
5d64c330dd
commit
9af0c56057
|
|
@ -15,8 +15,6 @@
|
|||
pair: HTTP; protocol
|
||||
single: URL
|
||||
single: httpd
|
||||
|
||||
.. index::
|
||||
module: SimpleHTTPServer
|
||||
module: CGIHTTPServer
|
||||
|
||||
|
|
@ -26,7 +24,8 @@ functioning Web servers. See the :mod:`SimpleHTTPServer` and
|
|||
:mod:`CGIHTTPServer` modules.
|
||||
|
||||
The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
|
||||
subclass. It creates and listens at the HTTP socket, dispatching the requests
|
||||
subclass, and therefore implements the :class:`SocketServer.BaseServer`
|
||||
interface. It creates and listens at the HTTP socket, dispatching the requests
|
||||
to a handler. Code to create and run the server looks like this::
|
||||
|
||||
def run(server_class=BaseHTTPServer.HTTPServer,
|
||||
|
|
@ -269,12 +268,31 @@ to a handler. Code to create and run the server looks like this::
|
|||
performed on the client's IP address.
|
||||
|
||||
|
||||
More examples
|
||||
-------------
|
||||
|
||||
To create a server that doesn't run forever, but until some condition is
|
||||
fulfilled::
|
||||
|
||||
def run_while_true(server_class=BaseHTTPServer.HTTPServer,
|
||||
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
|
||||
"""
|
||||
This assumes that keep_running() is a function of no arguments which
|
||||
is tested initially and after each request. If its return value
|
||||
is true, the server continues.
|
||||
"""
|
||||
server_address = ('', 8000)
|
||||
httpd = server_class(server_address, handler_class)
|
||||
while keep_running():
|
||||
httpd.handle_request()
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
Module :mod:`CGIHTTPServer`
|
||||
Extended request handler that supports CGI scripts.
|
||||
|
||||
Module :mod:`SimpleHTTPServer`
|
||||
Basic request handler that limits response to files actually under the document
|
||||
root.
|
||||
Basic request handler that limits response to files actually under the
|
||||
document root.
|
||||
|
||||
|
|
|
|||
|
|
@ -129,15 +129,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
|
||||
|
|
@ -148,32 +154,32 @@ 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.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
|
||||
.. 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
|
||||
|
|
@ -181,22 +187,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
|
||||
|
|
@ -205,17 +211,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.
|
||||
|
|
@ -223,27 +231,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
|
||||
|
|
@ -251,31 +259,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
|
||||
|
|
@ -291,14 +300,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
|
||||
|
|
@ -317,7 +326,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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue