source: trunk/essentials/dev-lang/python/Doc/lib/libsimplehttp.tex@ 3368

\section{\module{SimpleHTTPServer} ---
         Simple HTTP request handler}

\declaremodule{standard}{SimpleHTTPServer}
\sectionauthor{Moshe Zadka}{[email protected]}
\modulesynopsis{This module provides a basic request handler for HTTP
                servers.}


The \module{SimpleHTTPServer} module defines a request-handler class,
interface-compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler},
that serves files only from a base directory.

The \module{SimpleHTTPServer} module defines the following class:

\begin{classdesc}{SimpleHTTPRequestHandler}{request, client_address, server}
This class is used to serve files from the current directory and below,
directly mapping the directory structure to HTTP requests.

A lot of the work, such as parsing the request, is done by the base
class \class{BaseHTTPServer.BaseHTTPRequestHandler}.  This class
implements the \function{do_GET()} and \function{do_HEAD()} functions.
\end{classdesc}

The \class{SimpleHTTPRequestHandler} defines the following member
variables:

\begin{memberdesc}{server_version}
This will be \code{"SimpleHTTP/" + __version__}, where \code{__version__}
is defined in the module.
\end{memberdesc}

\begin{memberdesc}{extensions_map}
A dictionary mapping suffixes into MIME types. The default is signified
by an empty string, and is considered to be \code{application/octet-stream}.
The mapping is used case-insensitively, and so should contain only
lower-cased keys.
\end{memberdesc}

The \class{SimpleHTTPRequestHandler} defines the following methods:

\begin{methoddesc}{do_HEAD}{}
This method serves the \code{'HEAD'} request type: it sends the
headers it would send for the equivalent \code{GET} request. See the
\method{do_GET()} method for a more complete explanation of the possible
headers.
\end{methoddesc}

\begin{methoddesc}{do_GET}{}
The request is mapped to a local file by interpreting the request as
a path relative to the current working directory.

If the request was mapped to a directory, the directory is checked for
a file named \code{index.html} or \code{index.htm} (in that order).
If found, the file's contents are returned; otherwise a directory
listing is generated by calling the \method{list_directory()} method.
This method uses \function{os.listdir()} to scan the directory, and
returns a \code{404} error response if the \function{listdir()} fails.

If the request was mapped to a file, it is opened and the contents are
returned.  Any \exception{IOError} exception in opening the requested
file is mapped to a \code{404}, \code{'File not found'}
error. Otherwise, the content type is guessed by calling the
\method{guess_type()} method, which in turn uses the
\var{extensions_map} variable.

A \code{'Content-type:'} header with the guessed content type is
output, followed by a \code{'Content-Length:'} header with the file's
size and a \code{'Last-Modified:'} header with the file's modification
time.

Then follows a blank line signifying the end of the headers,
and then the contents of the file are output. If the file's MIME type
starts with \code{text/} the file is opened in text mode; otherwise
binary mode is used.

For example usage, see the implementation of the \function{test()}
function.
\versionadded[The \code{'Last-Modified'} header]{2.5}
\end{methoddesc}


\begin{seealso}
  \seemodule{BaseHTTPServer}{Base class implementation for Web server
                             and request handler.}
\end{seealso}