mirrors
/
cpython
mirror of https://github.com/python/cpython.git
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

#1742837: expand HTTP server docs, and fix SocketServer ones to document methods as methods, not functions.

This commit is contained in:
Georg Brandl 2009-04-05 10:24:20 +00:00
parent 5d64c330dd
commit 9af0c56057
2 changed files with 58 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Doc/library/basehttpserver.rst
View File

@ -15,8 +15,6 @@
pair: HTTP; protocol pair: HTTP; protocol
single: URL single: URL
single: httpd single: httpd
.. index::
module: SimpleHTTPServer module: SimpleHTTPServer
module: CGIHTTPServer module: CGIHTTPServer
@ -26,7 +24,8 @@ functioning Web servers. See the :mod:`SimpleHTTPServer` and
:mod:`CGIHTTPServer` modules. :mod:`CGIHTTPServer` modules.
The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer` 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:: to a handler. Code to create and run the server looks like this::
def run(server_class=BaseHTTPServer.HTTPServer, 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. 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:: .. seealso::
Module :mod:`CGIHTTPServer` Module :mod:`CGIHTTPServer`
Extended request handler that supports CGI scripts. Extended request handler that supports CGI scripts.
Module :mod:`SimpleHTTPServer` Module :mod:`SimpleHTTPServer`
Basic request handler that limits response to files actually under the document Basic request handler that limits response to files actually under the
root. document root.

61
Doc/library/socketserver.rst
View File

@ -129,15 +129,21 @@ another way to manage this.
Server Objects 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 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 listening. This function is most commonly passed to :func:`select.select`, to
allow monitoring multiple servers in the same process. 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 Process a single request. This function calls the following methods in
order: :meth:`get_request`, :meth:`verify_request`, and order: :meth:`get_request`, :meth:`verify_request`, and
@ -148,32 +154,32 @@ Server Objects
will return. 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 Handle requests until an explicit :meth:`shutdown` request. Polls for
shutdown every *poll_interval* seconds. shutdown every *poll_interval* seconds.
.. function:: shutdown() .. method:: BaseServer.shutdown()
Tells the :meth:`serve_forever` loop to stop and waits until it does. Tells the :meth:`serve_forever` loop to stop and waits until it does.
.. versionadded:: 2.6 .. versionadded:: 2.6
.. data:: address_family .. attribute:: BaseServer.address_family
The family of protocols to which the server's socket belongs. The family of protocols to which the server's socket belongs.
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`. 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 The user-provided request handler class; an instance of this class is created
for each request. for each request.
.. data:: server_address .. attribute:: BaseServer.server_address
The address on which the server is listening. The format of addresses varies 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 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. 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 socket object on which the server will listen for incoming requests.
The server classes support the following class variables: The server classes support the following class variables:
.. XXX should class variables be covered before instance variables, or vice versa? .. XXX should class variables be covered before instance variables, or vice versa?
.. attribute:: BaseServer.allow_reuse_address
.. data:: allow_reuse_address
Whether the server will allow the reuse of an address. This defaults to 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. :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 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 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. 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 The type of socket used by the server; :const:`socket.SOCK_STREAM` and
:const:`socket.SOCK_DGRAM` are two common values. :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 Timeout duration, measured in seconds, or :const:`None` if no timeout is
desired. If :meth:`handle_request` receives no incoming requests within the desired. If :meth:`handle_request` receives no incoming requests within the
timeout period, the :meth:`handle_timeout` method is called. timeout period, the :meth:`handle_timeout` method is called.
There are various server methods that can be overridden by subclasses of base 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 server classes like :class:`TCPServer`; these methods aren't useful to external
users of the server object. 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 .. XXX should the default implementations of these be documented, or should
it be assumed that the user will look at SocketServer.py? it be assumed that the user will look at SocketServer.py?
.. method:: BaseServer.finish_request()
.. function:: finish_request()
Actually processes the request by instantiating :attr:`RequestHandlerClass` and Actually processes the request by instantiating :attr:`RequestHandlerClass` and
calling its :meth:`handle` method. 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* 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 socket object to be used to communicate with the client, and the client's
address. 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` This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle`
method raises an exception. The default action is to print the traceback to method raises an exception. The default action is to print the traceback to
standard output and continue handling further requests. 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 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 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 to collect the status of any child processes that have exited, while
in threading servers this method does nothing. 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 Calls :meth:`finish_request` to create an instance of the
:attr:`RequestHandlerClass`. If desired, this function can create a new process :attr:`RequestHandlerClass`. If desired, this function can create a new process
or thread to handle the request; the :class:`ForkingMixIn` and or thread to handle the request; the :class:`ForkingMixIn` and
:class:`ThreadingMixIn` classes do this. :class:`ThreadingMixIn` classes do this.
.. Is there any point in documenting the following two functions? .. Is there any point in documenting the following two functions?
What would the purpose of overriding them be: initializing server What would the purpose of overriding them be: initializing server
instance variables, adding new network families? instance variables, adding new network families?
.. method:: BaseServer.server_activate()
.. function:: server_activate()
Called by the server's constructor to activate the server. The default behavior 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. 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. Called by the server's constructor to bind the socket to the desired address.
May be overridden. 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 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 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. request.
.. function:: finish() .. method:: RequestHandler.finish()
Called after the :meth:`handle` method to perform any clean-up actions Called after the :meth:`handle` method to perform any clean-up actions
required. The default implementation does nothing. If :meth:`setup` or required. The default implementation does nothing. If :meth:`setup` or
:meth:`handle` raise an exception, this function will not be called. :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 This function must do all the work required to service a request. The
default implementation does nothing. Several instance attributes are default implementation does nothing. Several instance attributes are
@ -317,7 +326,7 @@ request.
data or return data to the client. data or return data to the client.
.. function:: setup() .. method:: RequestHandler.setup()
Called before the :meth:`handle` method to perform any initialization actions Called before the :meth:`handle` method to perform any initialization actions
required. The default implementation does nothing. required. The default implementation does nothing.