path: root/Doc/libbasehttp.tex

\section{Standard Module \sectcode{BaseHTTPServer}}
\label{module-BaseHTTPServer}
\stmodindex{BaseHTTPServer}

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

\renewcommand{\indexsubitem}{(in module BaseHTTPServer)}

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
\code{SimpleHTTPServer} and \code{CGIHTTPServer} modules.
\stmodindex{SimpleHTTPServer}
\stmodindex{CGIHTTPServer}

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

\bcode\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}\ecode
%
The \code{HTTPServer} class builds on the \code{TCPServer} class by
storing the server address as instance
variables named \code{server_name} and \code{server_port}. The
server is accessible by the handler, typically through the handler's
\code{server} instance variable.

The module's second class, \code{BaseHTTPRequestHandler}, 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).
\code{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 \code{SPAM}, the
\code{do_SPAM} method will be called with no arguments. All of
the relevant information is stored into instance variables of the
handler.

\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler instance variables)}

\code{BaseHTTPRequestHandler} has the following instance variables:

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

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

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

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

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

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

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

\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler class variables)}

\code{BaseHTTPRequestHandler} has the following class variables:

\begin{datadesc}{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{datadesc}

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

\begin{datadesc}{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, specifing 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{datadesc}

\begin{datadesc}{protocol_version}
This specifies the HTTP protocol version used in responses.
Typically, this should not be overridden. Defaults to
\code{"HTTP/1.0"}.
\end{datadesc}

\begin{datadesc}{MessageClass}
Specifies a Message-like class to parse HTTP headers. Typically,
this is not overridden, and it defaults to \code{mimetools.Message}.
\end{datadesc}

\begin{datadesc}{responses}
This variable contains a mapping of error code integers to two-element
tuples containing a short and long message. For example,
\code{\{code : (shortmessage, 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 \code{error_message_format} class variable).
\end{datadesc}

\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler method)}

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

\begin{funcdesc}{handle}{}
Overrides the superclass' \code{handle} method to provide the
specific handler behavior. This method will parse and dispatch
the request to the appropriate \code{do_}* method.
\end{funcdesc}

\begin{funcdesc}{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 \code{error_message_format}
class variable.
\end{funcdesc}

\begin{funcdesc}{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
\code{version_string()} and \code{date_time_string()} methods,
respectively.
\end{funcdesc}

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

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

\begin{funcdesc}{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{funcdesc}

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

\begin{funcdesc}{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 \code{log_message} are applied
as inputs to the formatting. The client address and current date
and time are prefixed to every message logged.
\end{funcdesc}

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

\begin{funcdesc}{date_time_string}{}
Returns the current date and time, formatted for a message header.
\end{funcdesc}

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

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