Doc/lib/libsimplehttp.tex

   1 \section{\module{SimpleHTTPServer} ---
   2          Simple HTTP request handler}
   3
   4 \declaremodule{standard}{SimpleHTTPServer}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{This module provides a basic request handler for HTTP
   7                 servers.}
   8
   9
  10 The \module{SimpleHTTPServer} module defines a request-handler class,
  11 interface-compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler},
  12 that serves files only from a base directory.
  13
  14 The \module{SimpleHTTPServer} module defines the following class:
  15
  16 \begin{classdesc}{SimpleHTTPRequestHandler}{request, client_address, server}
  17 This class is used to serve files from the current directory and below,
  18 directly mapping the directory structure to HTTP requests.
  19
  20 A lot of the work, such as parsing the request, is done by the base
  21 class \class{BaseHTTPServer.BaseHTTPRequestHandler}.  This class
  22 implements the \function{do_GET()} and \function{do_HEAD()} functions.
  23 \end{classdesc}
  24
  25 The \class{SimpleHTTPRequestHandler} defines the following member
  26 variables:
  27
  28 \begin{memberdesc}{server_version}
  29 This will be \code{"SimpleHTTP/" + __version__}, where \code{__version__}
  30 is defined in the module.
  31 \end{memberdesc}
  32
  33 \begin{memberdesc}{extensions_map}
  34 A dictionary mapping suffixes into MIME types. The default is signified
  35 by an empty string, and is considered to be \code{application/octet-stream}.
  36 The mapping is used case-insensitively, and so should contain only
  37 lower-cased keys.
  38 \end{memberdesc}
  39
  40 The \class{SimpleHTTPRequestHandler} defines the following methods:
  41
  42 \begin{methoddesc}{do_HEAD}{}
  43 This method serves the \code{'HEAD'} request type: it sends the
  44 headers it would send for the equivalent \code{GET} request. See the
  45 \method{do_GET()} method for a more complete explanation of the possible
  46 headers.
  47 \end{methoddesc}
  48
  49 \begin{methoddesc}{do_GET}{}
  50 The request is mapped to a local file by interpreting the request as
  51 a path relative to the current working directory.
  52
  53 If the request was mapped to a directory, the directory is checked for
  54 a file named \code{index.html} or \code{index.htm} (in that order).
  55 If found, the file's contents are returned; otherwise a directory
  56 listing is generated by calling the \method{list_directory()} method.
  57 This method uses \function{os.listdir()} to scan the directory, and
  58 returns a \code{404} error response if the \function{listdir()} fails.
  59
  60 If the request was mapped to a file, it is opened and the contents are
  61 returned.  Any \exception{IOError} exception in opening the requested
  62 file is mapped to a \code{404}, \code{'File not found'}
  63 error. Otherwise, the content type is guessed by calling the
  64 \method{guess_type()} method, which in turn uses the
  65 \var{extensions_map} variable.
  66
  67 A \code{'Content-type:'} header with the guessed content type is
  68 output, followed by a \code{'Content-Length:'} header with the file's
  69 size and a \code{'Last-Modified:'} header with the file's modification
  70 time.
  71
  72 Then follows a blank line signifying the end of the headers,
  73 and then the contents of the file are output. If the file's MIME type
  74 starts with \code{text/} the file is opened in text mode; otherwise
  75 binary mode is used.
  76
  77 For example usage, see the implementation of the \function{test()}
  78 function.
  79 \versionadded[The \code{'Last-Modified'} header]{2.5}
  80 \end{methoddesc}
  81
  82
  83 \begin{seealso}
  84   \seemodule{BaseHTTPServer}{Base class implementation for Web server
  85                              and request handler.}
  86 \end{seealso}