source: trunk/essentials/dev-lang/python/Doc/lib/libbasehttp.tex@ 3398

\section{\module{BaseHTTPServer} ---
         Basic HTTP server}

\declaremodule{standard}{BaseHTTPServer}
\modulesynopsis{Basic HTTP server (base class for
                \class{SimpleHTTPServer} and \class{CGIHTTPServer}).}


\indexii{WWW}{server}
\indexii{HTTP}{protocol}
\index{URL}
\index{httpd}

This module defines two classes for implementing HTTP servers
(Web servers). Usually, this module isn't used directly, but is used
as a basis for building functioning Web servers. See the
\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
\refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules.

The first class, \class{HTTPServer}, is a
\class{SocketServer.TCPServer} subclass.  It creates and listens at the
HTTP socket, dispatching the requests to a handler.  Code to create and
run the server looks like this:

\begin{verbatim}
def run(server_class=BaseHTTPServer.HTTPServer,
        handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()
\end{verbatim}

\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
This class builds on the \class{TCPServer} class by
storing the server address as instance
variables named \member{server_name} and \member{server_port}. The
server is accessible by the handler, typically through the handler's
\member{server} instance variable.
\end{classdesc}

\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
This class is used
to handle the HTTP requests that arrive at the server. By itself,
it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (e.g. GET or POST).
\class{BaseHTTPRequestHandler} provides a number of class and instance
variables, and methods for use by subclasses.

The handler will parse the request and the headers, then call a
method specific to the request type. The method name is constructed
from the request. For example, for the request method \samp{SPAM}, the
\method{do_SPAM()} method will be called with no arguments. All of
the relevant information is stored in instance variables of the
handler.  Subclasses should not need to override or extend the
\method{__init__()} method.
\end{classdesc}


\class{BaseHTTPRequestHandler} has the following instance variables:

\begin{memberdesc}{client_address}
Contains a tuple of the form \code{(\var{host}, \var{port})} referring
to the client's address.
\end{memberdesc}

\begin{memberdesc}{command}
Contains the command (request type). For example, \code{'GET'}.
\end{memberdesc}

\begin{memberdesc}{path}
Contains the request path.
\end{memberdesc}

\begin{memberdesc}{request_version}
Contains the version string from the request. For example,
\code{'HTTP/1.0'}.
\end{memberdesc}

\begin{memberdesc}{headers}
Holds an instance of the class specified by the \member{MessageClass}
class variable. This instance parses and manages the headers in
the HTTP request.
\end{memberdesc}

\begin{memberdesc}{rfile}
Contains an input stream, positioned at the start of the optional
input data.
\end{memberdesc}

\begin{memberdesc}{wfile}
Contains the output stream for writing a response back to the client.
Proper adherence to the HTTP protocol must be used when writing
to this stream.
\end{memberdesc}


\class{BaseHTTPRequestHandler} has the following class variables:

\begin{memberdesc}{server_version}
Specifies the server software version.  You may want to override
this.
The format is multiple whitespace-separated strings,
where each string is of the form name[/version].
For example, \code{'BaseHTTP/0.2'}.
\end{memberdesc}

\begin{memberdesc}{sys_version}
Contains the Python system version, in a form usable by the
\member{version_string} method and the \member{server_version} class
variable. For example, \code{'Python/1.4'}.
\end{memberdesc}

\begin{memberdesc}{error_message_format}
Specifies a format string for building an error response to the
client. It uses parenthesized, keyed format specifiers, so the
format operand must be a dictionary. The \var{code} key should
be an integer, specifying the numeric HTTP error code value.
\var{message} should be a string containing a (detailed) error
message of what occurred, and \var{explain} should be an
explanation of the error code number. Default \var{message}
and \var{explain} values can found in the \var{responses}
class variable.
\end{memberdesc}

\begin{memberdesc}{protocol_version}
This specifies the HTTP protocol version used in responses.  If set
to \code{'HTTP/1.1'}, the server will permit HTTP persistent
connections; however, your server \emph{must} then include an
accurate \code{Content-Length} header (using \method{send_header()})
in all of its responses to clients.  For backwards compatibility,
the setting defaults to \code{'HTTP/1.0'}.
\end{memberdesc}

\begin{memberdesc}{MessageClass}
Specifies a \class{rfc822.Message}-like class to parse HTTP
headers. Typically, this is not overridden, and it defaults to
\class{mimetools.Message}.
\withsubitem{(in module mimetools)}{\ttindex{Message}}
\end{memberdesc}

\begin{memberdesc}{responses}
This variable contains a mapping of error code integers to two-element
tuples containing a short and long message. For example,
\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
\var{shortmessage} is usually used as the \var{message} key in an
error response, and \var{longmessage} as the \var{explain} key
(see the \member{error_message_format} class variable).
\end{memberdesc}


A \class{BaseHTTPRequestHandler} instance has the following methods:

\begin{methoddesc}{handle}{}
Calls \method{handle_one_request()} once (or, if persistent connections
are enabled, multiple times) to handle incoming HTTP requests.
You should never need to override it; instead, implement appropriate
\method{do_*()} methods.
\end{methoddesc}

\begin{methoddesc}{handle_one_request}{}
This method will parse and dispatch
the request to the appropriate \method{do_*()} method.  You should
never need to override it.
\end{methoddesc}

\begin{methoddesc}{send_error}{code\optional{, message}}
Sends and logs a complete error reply to the client. The numeric
\var{code} specifies the HTTP error code, with \var{message} as
optional, more specific text. A complete set of headers is sent,
followed by text composed using the \member{error_message_format}
class variable.
\end{methoddesc}

\begin{methoddesc}{send_response}{code\optional{, message}}
Sends a response header and logs the accepted request. The HTTP
response line is sent, followed by \emph{Server} and \emph{Date}
headers. The values for these two headers are picked up from the
\method{version_string()} and \method{date_time_string()} methods,
respectively.
\end{methoddesc}

\begin{methoddesc}{send_header}{keyword, value}
Writes a specific HTTP header to the output stream. \var{keyword}
should specify the header keyword, with \var{value} specifying
its value.
\end{methoddesc}

\begin{methoddesc}{end_headers}{}
Sends a blank line, indicating the end of the HTTP headers in
the response.
\end{methoddesc}

\begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
Logs an accepted (successful) request. \var{code} should specify
the numeric HTTP code associated with the response. If a size of
the response is available, then it should be passed as the
\var{size} parameter.
\end{methoddesc}

\begin{methoddesc}{log_error}{...}
Logs an error when a request cannot be fulfilled. By default,
it passes the message to \method{log_message()}, so it takes the
same arguments (\var{format} and additional values).
\end{methoddesc}

\begin{methoddesc}{log_message}{format, ...}
Logs an arbitrary message to \code{sys.stderr}. This is typically
overridden to create custom error logging mechanisms. The
\var{format} argument is a standard printf-style format string,
where the additional arguments to \method{log_message()} are applied
as inputs to the formatting. The client address and current date
and time are prefixed to every message logged.
\end{methoddesc}

\begin{methoddesc}{version_string}{}
Returns the server software's version string. This is a combination
of the \member{server_version} and \member{sys_version} class variables.
\end{methoddesc}

\begin{methoddesc}{date_time_string}{\optional{timestamp}}
Returns the date and time given by \var{timestamp} (which must be in the
format returned by \function{time.time()}), formatted for a message header.
If \var{timestamp} is omitted, it uses the current date and time.

The result looks like \code{'Sun, 06 Nov 1994 08:49:37 GMT'}.
\versionadded[The \var{timestamp} parameter]{2.5}
\end{methoddesc}

\begin{methoddesc}{log_date_time_string}{}
Returns the current date and time, formatted for logging.
\end{methoddesc}

\begin{methoddesc}{address_string}{}
Returns the client address, formatted for logging. A name lookup
is performed on the client's IP address.
\end{methoddesc}


\begin{seealso}
  \seemodule{CGIHTTPServer}{Extended request handler that supports CGI
                            scripts.}

  \seemodule{SimpleHTTPServer}{Basic request handler that limits response
                               to files actually under the document root.}
\end{seealso}