Doc/lib/libbasehttp.tex

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