Doc/library/basehttpserver.rst

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