Doc/lib/libbasehttp.tex

   1 \section{\module{BaseHTTPServer} ---
   2          Basic HTTP server}
   3
   4 \declaremodule{standard}{BaseHTTPServer}
   5 \modulesynopsis{Basic HTTP server (base class for
   6                 \class{SimpleHTTPServer} and \class{CGIHTTPServer}).}
   7
   8
   9 \indexii{WWW}{server}
  10 \indexii{HTTP}{protocol}
  11 \index{URL}
  12 \index{httpd}
  13
  14 This module defines two classes for implementing HTTP servers
  15 (web servers). Usually, this module isn't used directly, but is used
  16 as a basis for building functioning web servers. See the
  17 \module{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
  18 \refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules.
  19
  20 The first class, \class{HTTPServer}, is a
  21 \class{SocketServer.TCPServer} subclass. It creates and listens at the
  22 web socket, dispatching the requests to a handler. Code to create and
  23 run the server looks like this:
  24
  25 \begin{verbatim}
  26 def run(server_class=BaseHTTPServer.HTTPServer,
  27         handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
  28     server_address = ('', 8000)
  29     httpd = server_class(server_address, handler_class)
  30     httpd.serve_forever()
  31 \end{verbatim}
  32
  33 \begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
  34 This class builds on the \class{TCPServer} class by
  35 storing the server address as instance
  36 variables named \member{server_name} and \member{server_port}. The
  37 server is accessible by the handler, typically through the handler's
  38 \member{server} instance variable.
  39 \end{classdesc}
  40
  41 \begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
  42 This class is used
  43 to handle the HTTP requests that arrive at the server. By itself,
  44 it cannot respond to any actual HTTP requests; it must be subclassed
  45 to handle each request method (e.g. GET or POST).
  46 \class{BaseHTTPRequestHandler} provides a number of class and instance
  47 variables, and methods for use by subclasses.
  48
  49 The handler will parse the request and the headers, then call a
  50 method specific to the request type. The method name is constructed
  51 from the request. For example, for the request method \samp{SPAM}, the
  52 \method{do_SPAM()} method will be called with no arguments. All of
  53 the relevant information is stored in instance variables of the
  54 handler.  Subclasses should not need to override or extend the
  55 \method{__init__()} method.
  56 \end{classdesc}
  57
  58
  59 \class{BaseHTTPRequestHandler} has the following instance variables:
  60
  61 \begin{memberdesc}{client_address}
  62 Contains a tuple of the form \code{(\var{host}, \var{port})} referring
  63 to the client's address.
  64 \end{memberdesc}
  65
  66 \begin{memberdesc}{command}
  67 Contains the command (request type). For example, \code{'GET'}.
  68 \end{memberdesc}
  69
  70 \begin{memberdesc}{path}
  71 Contains the request path.
  72 \end{memberdesc}
  73
  74 \begin{memberdesc}{request_version}
  75 Contains the version string from the request. For example,
  76 \code{'HTTP/1.0'}.
  77 \end{memberdesc}
  78
  79 \begin{memberdesc}{headers}
  80 Holds an instance of the class specified by the \member{MessageClass}
  81 class variable. This instance parses and manages the headers in
  82 the HTTP request.
  83 \end{memberdesc}
  84
  85 \begin{memberdesc}{rfile}
  86 Contains an input stream, positioned at the start of the optional
  87 input data.
  88 \end{memberdesc}
  89
  90 \begin{memberdesc}{wfile}
  91 Contains the output stream for writing a response back to the client.
  92 Proper adherence to the HTTP protocol must be used when writing
  93 to this stream.
  94 \end{memberdesc}
  95
  96
  97 \class{BaseHTTPRequestHandler} has the following class variables:
  98
  99 \begin{memberdesc}{server_version}
 100 Specifies the server software version.  You may want to override
 101 this.
 102 The format is multiple whitespace-separated strings,
 103 where each string is of the form name[/version].
 104 For example, \code{'BaseHTTP/0.2'}.
 105 \end{memberdesc}
 106
 107 \begin{memberdesc}{sys_version}
 108 Contains the Python system version, in a form usable by the
 109 \member{version_string} method and the \member{server_version} class
 110 variable. For example, \code{'Python/1.4'}.
 111 \end{memberdesc}
 112
 113 \begin{memberdesc}{error_message_format}
 114 Specifies a format string for building an error response to the
 115 client. It uses parenthesized, keyed format specifiers, so the
 116 format operand must be a dictionary. The \var{code} key should
 117 be an integer, specifying the numeric HTTP error code value.
 118 \var{message} should be a string containing a (detailed) error
 119 message of what occurred, and \var{explain} should be an
 120 explanation of the error code number. Default \var{message}
 121 and \var{explain} values can found in the \var{responses}
 122 class variable.
 123 \end{memberdesc}
 124
 125 \begin{memberdesc}{protocol_version}
 126 This specifies the HTTP protocol version used in responses.
 127 Typically, this should not be overridden. Defaults to
 128 \code{'HTTP/1.0'}.
 129 \end{memberdesc}
 130
 131 \begin{memberdesc}{MessageClass}
 132 Specifies a \class{rfc822.Message}-like class to parse HTTP
 133 headers. Typically, this is not overridden, and it defaults to
 134 \class{mimetools.Message}.
 135 \withsubitem{(in module mimetools)}{\ttindex{Message}}
 136 \end{memberdesc}
 137
 138 \begin{memberdesc}{responses}
 139 This variable contains a mapping of error code integers to two-element
 140 tuples containing a short and long message. For example,
 141 \code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
 142 \var{shortmessage} is usually used as the \var{message} key in an
 143 error response, and \var{longmessage} as the \var{explain} key
 144 (see the \member{error_message_format} class variable).
 145 \end{memberdesc}
 146
 147
 148 A \class{BaseHTTPRequestHandler} instance has the following methods:
 149
 150 \begin{methoddesc}{handle}{}
 151 Overrides the superclass' \method{handle()} method to provide the
 152 specific handler behavior. This method will parse and dispatch
 153 the request to the appropriate \method{do_*()} method.
 154 \end{methoddesc}
 155
 156 \begin{methoddesc}{send_error}{code\optional{, message}}
 157 Sends and logs a complete error reply to the client. The numeric
 158 \var{code} specifies the HTTP error code, with \var{message} as
 159 optional, more specific text. A complete set of headers is sent,
 160 followed by text composed using the \member{error_message_format}
 161 class variable.
 162 \end{methoddesc}
 163
 164 \begin{methoddesc}{send_response}{code\optional{, message}}
 165 Sends a response header and logs the accepted request. The HTTP
 166 response line is sent, followed by \emph{Server} and \emph{Date}
 167 headers. The values for these two headers are picked up from the
 168 \method{version_string()} and \method{date_time_string()} methods,
 169 respectively.
 170 \end{methoddesc}
 171
 172 \begin{methoddesc}{send_header}{keyword, value}
 173 Writes a specific MIME header to the output stream. \var{keyword}
 174 should specify the header keyword, with \var{value} specifying
 175 its value.
 176 \end{methoddesc}
 177
 178 \begin{methoddesc}{end_headers}{}
 179 Sends a blank line, indicating the end of the MIME headers in
 180 the response.
 181 \end{methoddesc}
 182
 183 \begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
 184 Logs an accepted (successful) request. \var{code} should specify
 185 the numeric HTTP code associated with the response. If a size of
 186 the response is available, then it should be passed as the
 187 \var{size} parameter.
 188 \end{methoddesc}
 189
 190 \begin{methoddesc}{log_error}{...}
 191 Logs an error when a request cannot be fulfilled. By default,
 192 it passes the message to \method{log_message()}, so it takes the
 193 same arguments (\var{format} and additional values).
 194 \end{methoddesc}
 195
 196 \begin{methoddesc}{log_message}{format, ...}
 197 Logs an arbitrary message to \code{sys.stderr}. This is typically
 198 overridden to create custom error logging mechanisms. The
 199 \var{format} argument is a standard printf-style format string,
 200 where the additional arguments to \method{log_message()} are applied
 201 as inputs to the formatting. The client address and current date
 202 and time are prefixed to every message logged.
 203 \end{methoddesc}
 204
 205 \begin{methoddesc}{version_string}{}
 206 Returns the server software's version string. This is a combination
 207 of the \member{server_version} and \member{sys_version} class variables.
 208 \end{methoddesc}
 209
 210 \begin{methoddesc}{date_time_string}{}
 211 Returns the current date and time, formatted for a message header.
 212 \end{methoddesc}
 213
 214 \begin{methoddesc}{log_data_time_string}{}
 215 Returns the current date and time, formatted for logging.
 216 \end{methoddesc}
 217
 218 \begin{methoddesc}{address_string}{}
 219 Returns the client address, formatted for logging. A name lookup
 220 is performed on the client's IP address.
 221 \end{methoddesc}
 222
 223
 224 \begin{seealso}
 225   \seemodule{CGIHTTPServer}{Extended request handler that supports CGI
 226                             scripts.}
 227
 228   \seemodule{SimpleHTTPServer}{Basic request handler that limits response
 229                                to files actually under the document root.}
 230 \end{seealso}