11.14 BaseHTTPServer -- Basic HTTP server
Keywords: lib

# 11.14 `BaseHTTPServer` -- Basic HTTP server

This module defines two classes for implementing HTTP servers (web servers). Usually, this module isn't used directly, but is used as a basis for building functioning web servers. See the `SimpleHTTPServer` and `CGIHTTPServer` modules.

The first class, `HTTPServer`, is a `SocketServer.TCPServer` subclass. It creates and listens at the web socket, dispatching the requests to a handler. Code to create and run the server looks like this:

      def run(server_class=BaseHTTPServer.HTTPServer,
              handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
          server_address = ('', 8000)
          httpd = server_class(server_address, handler_class)
          httpd.serve_forever()

`HTTPServer` (server_address, RequestHandlerClass)
  This class builds on the `TCPServer` class by storing the server address as instance variables named `server_name` and `server_port`. The server is accessible by the handler, typically through the handler's `server` instance variable.

`BaseHTTPRequestHandler` (request, client_address, server)
  This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). `BaseHTTPRequestHandler` provides a number of class and instance variables, and methods for use by subclasses.

  The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed from the request. For example, for the request method "`SPAM`", the `do_SPAM()` method will be called with no arguments. All of the relevant information is stored in instance variables of the handler. Subclasses should not need to override or extend the `__init__()` method.

`BaseHTTPRequestHandler` has the following instance variables:

`client_address`
  Contains a tuple of the form `(host, port)` referring to the client's address.

`command`
  Contains the command (request type). For example, `'GET'`.

`path`
  Contains the request path.

`request_version`
  Contains the version string from the request. For example, `'HTTP/1.0'`.

`headers`
  Holds an instance of the class specified by the `MessageClass` class variable. This instance parses and manages the headers in the HTTP request.

`rfile`
  Contains an input stream, positioned at the start of the optional input data.

`wfile`
  Contains the output stream for writing a response back to the client. Proper adherence to the HTTP protocol must be used when writing to this stream.

`BaseHTTPRequestHandler` has the following class variables:

`server_version`
  Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, `'BaseHTTP/0.2'`.

`sys_version`
  Contains the Python system version, in a form usable by the `version_string` method and the `server_version` class variable. For example, `'Python/1.4'`.

`error_message_format`
  Specifies a format string for building an error response to the client. It uses parenthesized, keyed format specifiers, so the format operand must be a dictionary. The code key should be an integer, specifying the numeric HTTP error code value. message should be a string containing a (detailed) error message of what occurred, and explain should be an explanation of the error code number. Default message and explain values can found in the responses class variable.

`protocol_version`
  This specifies the HTTP protocol version used in responses. Typically, this should not be overridden. Defaults to `'HTTP/1.0'`.

`MessageClass`
  Specifies a `rfc822.Message`-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to `mimetools.Message`.

`responses`
  This variable contains a mapping of error code integers to two-element tuples containing a short and long message. For example, `{code: (shortmessage, longmessage)}`. The shortmessage is usually used as the message key in an error response, and longmessage as the explain key (see the `error_message_format` class variable).

A `BaseHTTPRequestHandler` instance has the following methods:

`handle` ()
  Overrides the superclass' `handle()` method to provide the specific handler behavior. This method will parse and dispatch the request to the appropriate `do_*()` method.

`send_error` (code[, message])
  Sends and logs a complete error reply to the client. The numeric code specifies the HTTP error code, with message as optional, more specific text. A complete set of headers is sent, followed by text composed using the `error_message_format` class variable.

`send_response` (code[, message])
  Sends a response header and logs the accepted request. The HTTP response line is sent, followed by Server and Date headers. The values for these two headers are picked up from the `version_string()` and `date_time_string()` methods, respectively.

`send_header` (keyword, value)
  Writes a specific MIME header to the output stream. keyword should specify the header keyword, with value specifying its value.

`end_headers` ()
  Sends a blank line, indicating the end of the MIME headers in the response.

`log_request` ([code[, size]])
  Logs an accepted (successful) request. code should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the size parameter.

`log_error` (...)
  Logs an error when a request cannot be fulfilled. By default, it passes the message to `log_message()`, so it takes the same arguments (format and additional values).

`log_message` (format, ...)
  Logs an arbitrary message to `sys.stderr`. This is typically overridden to create custom error logging mechanisms. The format argument is a standard printf-style format string, where the additional arguments to `log_message()` are applied as inputs to the formatting. The client address and current date and time are prefixed to every message logged.

`version_string` ()
  Returns the server software's version string. This is a combination of the `server_version` and `sys_version` class variables.

`date_time_string` ()
  Returns the current date and time, formatted for a message header.

`log_data_time_string` ()
  Returns the current date and time, formatted for logging.

`address_string` ()
  Returns the client address, formatted for logging. A name lookup is performed on the client's IP address.

See Also:

Module `CGIHTTPServer`:
  Extended request handler that supports CGI scripts.

Module `SimpleHTTPServer`:
  Basic request handler that limits response to files actually under the document root.