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 \refmodule{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 HTTP 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.  If set
 127 to \code{'HTTP/1.1'}, the server will permit HTTP persistent
 128 connections; however, your server \emph{must} then include an
 129 accurate \code{Content-Length} header (using \method{send_header()})
 130 in all of its responses to clients.  For backwards compatibility,
 131 the setting defaults to \code{'HTTP/1.0'}.
 132 \end{memberdesc}
 133
 134 \begin{memberdesc}{MessageClass}
 135 Specifies a \class{rfc822.Message}-like class to parse HTTP
 136 headers. Typically, this is not overridden, and it defaults to
 137 \class{mimetools.Message}.
 138 \withsubitem{(in module mimetools)}{\ttindex{Message}}
 139 \end{memberdesc}
 140
 141 \begin{memberdesc}{responses}
 142 This variable contains a mapping of error code integers to two-element
 143 tuples containing a short and long message. For example,
 144 \code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
 145 \var{shortmessage} is usually used as the \var{message} key in an
 146 error response, and \var{longmessage} as the \var{explain} key
 147 (see the \member{error_message_format} class variable).
 148 \end{memberdesc}
 149
 150
 151 A \class{BaseHTTPRequestHandler} instance has the following methods:
 152
 153 \begin{methoddesc}{handle}{}
 154 Calls \method{handle_one_request()} once (or, if persistent connections
 155 are enabled, multiple times) to handle incoming HTTP requests.
 156 You should never need to override it; instead, implement appropriate
 157 \method{do_*()} methods.
 158 \end{methoddesc}
 159
 160 \begin{methoddesc}{handle_one_request}{}
 161 This method will parse and dispatch
 162 the request to the appropriate \method{do_*()} method.  You should
 163 never need to override it.
 164 \end{methoddesc}
 165
 166 \begin{methoddesc}{send_error}{code\optional{, message}}
 167 Sends and logs a complete error reply to the client. The numeric
 168 \var{code} specifies the HTTP error code, with \var{message} as
 169 optional, more specific text. A complete set of headers is sent,
 170 followed by text composed using the \member{error_message_format}
 171 class variable.
 172 \end{methoddesc}
 173
 174 \begin{methoddesc}{send_response}{code\optional{, message}}
 175 Sends a response header and logs the accepted request. The HTTP
 176 response line is sent, followed by \emph{Server} and \emph{Date}
 177 headers. The values for these two headers are picked up from the
 178 \method{version_string()} and \method{date_time_string()} methods,
 179 respectively.
 180 \end{methoddesc}
 181
 182 \begin{methoddesc}{send_header}{keyword, value}
 183 Writes a specific HTTP header to the output stream. \var{keyword}
 184 should specify the header keyword, with \var{value} specifying
 185 its value.
 186 \end{methoddesc}
 187
 188 \begin{methoddesc}{end_headers}{}
 189 Sends a blank line, indicating the end of the HTTP headers in
 190 the response.
 191 \end{methoddesc}
 192
 193 \begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
 194 Logs an accepted (successful) request. \var{code} should specify
 195 the numeric HTTP code associated with the response. If a size of
 196 the response is available, then it should be passed as the
 197 \var{size} parameter.
 198 \end{methoddesc}
 199
 200 \begin{methoddesc}{log_error}{...}
 201 Logs an error when a request cannot be fulfilled. By default,
 202 it passes the message to \method{log_message()}, so it takes the
 203 same arguments (\var{format} and additional values).
 204 \end{methoddesc}
 205
 206 \begin{methoddesc}{log_message}{format, ...}
 207 Logs an arbitrary message to \code{sys.stderr}. This is typically
 208 overridden to create custom error logging mechanisms. The
 209 \var{format} argument is a standard printf-style format string,
 210 where the additional arguments to \method{log_message()} are applied
 211 as inputs to the formatting. The client address and current date
 212 and time are prefixed to every message logged.
 213 \end{methoddesc}
 214
 215 \begin{methoddesc}{version_string}{}
 216 Returns the server software's version string. This is a combination
 217 of the \member{server_version} and \member{sys_version} class variables.
 218 \end{methoddesc}
 219
 220 \begin{methoddesc}{date_time_string}{}
 221 Returns the current date and time, formatted for a message header.
 222 \end{methoddesc}
 223
 224 \begin{methoddesc}{log_data_time_string}{}
 225 Returns the current date and time, formatted for logging.
 226 \end{methoddesc}
 227
 228 \begin{methoddesc}{address_string}{}
 229 Returns the client address, formatted for logging. A name lookup
 230 is performed on the client's IP address.
 231 \end{methoddesc}
 232
 233
 234 \begin{seealso}
 235   \seemodule{CGIHTTPServer}{Extended request handler that supports CGI
 236                             scripts.}
 237
 238   \seemodule{SimpleHTTPServer}{Basic request handler that limits response
 239                                to files actually under the document root.}
 240 \end{seealso}