
"BaseHTTPServer" --- Basic HTTP server
**************************************

Note: The "BaseHTTPServer" module has been merged into "http.server"
  in Python 3.  The *2to3* tool will automatically adapt imports when
  converting your sources to Python 3.

**Source code:** Lib/BaseHTTPServer.py

======================================================================

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,
and therefore implements the "SocketServer.BaseServer" interface.  It
creates and listens at the HTTP 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()

class BaseHTTPServer.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.

class BaseHTTPServer.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.

   server

      Contains the server instance.

   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.

   error_content_type

      Specifies the Content-Type HTTP header of error responses sent
      to the client.  The default value is "'text/html'".

      New in version 2.6: Previously, the content type was always
      "'text/html'".

   protocol_version

      This specifies the HTTP protocol version used in responses.  If
      set to "'HTTP/1.1'", the server will permit HTTP persistent
      connections; however, your server *must* then include an
      accurate "Content-Length" header (using "send_header()") in all
      of its responses to clients. For backwards compatibility, the
      setting 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()

      Calls "handle_one_request()" once (or, if persistent connections
      are enabled, multiple times) to handle incoming HTTP requests.
      You should never need to override it; instead, implement
      appropriate "do_*()" methods.

   handle_one_request()

      This method will parse and dispatch the request to the
      appropriate "do_*()" method.  You should never need to override
      it.

   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. The body will be empty if the method is HEAD or the
      response code is one of the following: "1xx", "204 No Content",
      "205 Reset Content", "304 Not Modified".

   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 HTTP 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 HTTP 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 ip 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([timestamp])

      Returns the date and time given by *timestamp* (which must be in
      the format returned by "time.time()"), formatted for a message
      header. If *timestamp* is omitted, it uses the current date and
      time.

      The result looks like "'Sun, 06 Nov 1994 08:49:37 GMT'".

      New in version 2.5: The *timestamp* parameter.

   log_date_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.


More examples
=============

To create a server that doesn't run forever, but until some condition
is fulfilled:

   def run_while_true(server_class=BaseHTTPServer.HTTPServer,
                      handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
       """
       This assumes that keep_running() is a function of no arguments which
       is tested initially and after each request.  If its return value
       is true, the server continues.
       """
       server_address = ('', 8000)
       httpd = server_class(server_address, handler_class)
       while keep_running():
           httpd.handle_request()

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.
