1 :mod:`BaseHTTPServer` --- Basic HTTP server

     2 ===========================================

     3 

     4 .. module:: BaseHTTPServer

     5    :synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).

     6 

     7 .. note::

     8    The :mod:`BaseHTTPServer` module has been merged into :mod:`http.server` in

     9    Python 3.0.  The :term:`2to3` tool will automatically adapt imports when

    10    converting your sources to 3.0.

    11 

    12 

    13 .. index::

    14    pair: WWW; server

    15    pair: HTTP; protocol

    16    single: URL

    17    single: httpd

    18 

    19 .. index::

    20    module: SimpleHTTPServer

    21    module: CGIHTTPServer

    22 

    23 This module defines two classes for implementing HTTP servers (Web servers).

    24 Usually, this module isn't used directly, but is used as a basis for building

    25 functioning Web servers. See the :mod:`SimpleHTTPServer` and

    26 :mod:`CGIHTTPServer` modules.

    27 

    28 The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`

    29 subclass.  It creates and listens at the HTTP socket, dispatching the requests

    30 to a handler.  Code to create and run the server looks like this::

    31 

    32    def run(server_class=BaseHTTPServer.HTTPServer,

    33            handler_class=BaseHTTPServer.BaseHTTPRequestHandler):

    34        server_address = ('', 8000)

    35        httpd = server_class(server_address, handler_class)

    36        httpd.serve_forever()

    37 

    38 

    39 .. class:: HTTPServer(server_address, RequestHandlerClass)

    40 

    41    This class builds on the :class:`TCPServer` class by storing the server

    42    address as instance variables named :attr:`server_name` and

    43    :attr:`server_port`. The server is accessible by the handler, typically

    44    through the handler's :attr:`server` instance variable.

    45 

    46 

    47 .. class:: BaseHTTPRequestHandler(request, client_address, server)

    48 

    49    This class is used to handle the HTTP requests that arrive at the server. By

    50    itself, it cannot respond to any actual HTTP requests; it must be subclassed

    51    to handle each request method (e.g. GET or

    52    POST). :class:`BaseHTTPRequestHandler` provides a number of class and

    53    instance variables, and methods for use by subclasses.

    54 

    55    The handler will parse the request and the headers, then call a method

    56    specific to the request type. The method name is constructed from the

    57    request. For example, for the request method ``SPAM``, the :meth:`do_SPAM`

    58    method will be called with no arguments. All of the relevant information is

    59    stored in instance variables of the handler.  Subclasses should not need to

    60    override or extend the :meth:`__init__` method.

    61 

    62    :class:`BaseHTTPRequestHandler` has the following instance variables:

    63 

    64 

    65    .. attribute:: client_address

    66 

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

    68       address.

    69 

    70 

    71    .. attribute:: server

    72 

    73       Contains the server instance.

    74 

    75 

    76    .. attribute:: command

    77 

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

    79 

    80 

    81    .. attribute:: path

    82 

    83       Contains the request path.

    84 

    85 

    86    .. attribute:: request_version

    87 

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

    89 

    90 

    91    .. attribute:: headers

    92 

    93       Holds an instance of the class specified by the :attr:`MessageClass` class

    94       variable. This instance parses and manages the headers in the HTTP

    95       request.

    96 

    97 

    98    .. attribute:: rfile

    99 

   100       Contains an input stream, positioned at the start of the optional input

   101       data.

   102 

   103 

   104    .. attribute:: wfile

   105 

   106       Contains the output stream for writing a response back to the

   107       client. Proper adherence to the HTTP protocol must be used when writing to

   108       this stream.

   109 

   110 

   111    :class:`BaseHTTPRequestHandler` has the following class variables:

   112 

   113 

   114    .. attribute:: server_version

   115 

   116       Specifies the server software version.  You may want to override this. The

   117       format is multiple whitespace-separated strings, where each string is of

   118       the form name[/version]. For example, ``'BaseHTTP/0.2'``.

   119 

   120 

   121    .. attribute:: sys_version

   122 

   123       Contains the Python system version, in a form usable by the

   124       :attr:`version_string` method and the :attr:`server_version` class

   125       variable. For example, ``'Python/1.4'``.

   126 

   127 

   128    .. attribute:: error_message_format

   129 

   130       Specifies a format string for building an error response to the client. It

   131       uses parenthesized, keyed format specifiers, so the format operand must be

   132       a dictionary. The *code* key should be an integer, specifying the numeric

   133       HTTP error code value. *message* should be a string containing a

   134       (detailed) error message of what occurred, and *explain* should be an

   135       explanation of the error code number. Default *message* and *explain*

   136       values can found in the *responses* class variable.

   137 

   138 

   139    .. attribute:: error_content_type

   140 

   141       Specifies the Content-Type HTTP header of error responses sent to the

   142       client.  The default value is ``'text/html'``.

   143 

   144       .. versionadded:: 2.6

   145          Previously, the content type was always ``'text/html'``.

   146 

   147 

   148    .. attribute:: protocol_version

   149 

   150       This specifies the HTTP protocol version used in responses.  If set to

   151       ``'HTTP/1.1'``, the server will permit HTTP persistent connections;

   152       however, your server *must* then include an accurate ``Content-Length``

   153       header (using :meth:`send_header`) in all of its responses to clients.

   154       For backwards compatibility, the setting defaults to ``'HTTP/1.0'``.

   155 

   156 

   157    .. attribute:: MessageClass

   158 

   159       .. index:: single: Message (in module mimetools)

   160 

   161       Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.

   162       Typically, this is not overridden, and it defaults to

   163       :class:`mimetools.Message`.

   164 

   165 

   166    .. attribute:: responses

   167 

   168       This variable contains a mapping of error code integers to two-element tuples

   169       containing a short and long message. For example, ``{code: (shortmessage,

   170       longmessage)}``. The *shortmessage* is usually used as the *message* key in an

   171       error response, and *longmessage* as the *explain* key (see the

   172       :attr:`error_message_format` class variable).

   173 

   174 

   175    A :class:`BaseHTTPRequestHandler` instance has the following methods:

   176 

   177 

   178    .. method:: handle()

   179 

   180       Calls :meth:`handle_one_request` once (or, if persistent connections are

   181       enabled, multiple times) to handle incoming HTTP requests. You should

   182       never need to override it; instead, implement appropriate :meth:`do_\*`

   183       methods.

   184 

   185 

   186    .. method:: handle_one_request()

   187 

   188       This method will parse and dispatch the request to the appropriate

   189       :meth:`do_\*` method.  You should never need to override it.

   190 

   191 

   192    .. method:: send_error(code[, message])

   193 

   194       Sends and logs a complete error reply to the client. The numeric *code*

   195       specifies the HTTP error code, with *message* as optional, more specific text. A

   196       complete set of headers is sent, followed by text composed using the

   197       :attr:`error_message_format` class variable.

   198 

   199 

   200    .. method:: send_response(code[, message])

   201 

   202       Sends a response header and logs the accepted request. The HTTP response

   203       line is sent, followed by *Server* and *Date* headers. The values for

   204       these two headers are picked up from the :meth:`version_string` and

   205       :meth:`date_time_string` methods, respectively.

   206 

   207 

   208    .. method:: send_header(keyword, value)

   209 

   210       Writes a specific HTTP header to the output stream. *keyword* should

   211       specify the header keyword, with *value* specifying its value.

   212 

   213 

   214    .. method:: end_headers()

   215 

   216       Sends a blank line, indicating the end of the HTTP headers in the

   217       response.

   218 

   219 

   220    .. method:: log_request([code[, size]])

   221 

   222       Logs an accepted (successful) request. *code* should specify the numeric

   223       HTTP code associated with the response. If a size of the response is

   224       available, then it should be passed as the *size* parameter.

   225 

   226 

   227    .. method:: log_error(...)

   228 

   229       Logs an error when a request cannot be fulfilled. By default, it passes

   230       the message to :meth:`log_message`, so it takes the same arguments

   231       (*format* and additional values).

   232 

   233 

   234    .. method:: log_message(format, ...)

   235 

   236       Logs an arbitrary message to ``sys.stderr``. This is typically overridden

   237       to create custom error logging mechanisms. The *format* argument is a

   238       standard printf-style format string, where the additional arguments to

   239       :meth:`log_message` are applied as inputs to the formatting. The client

   240       address and current date and time are prefixed to every message logged.

   241 

   242 

   243    .. method:: version_string()

   244 

   245       Returns the server software's version string. This is a combination of the

   246       :attr:`server_version` and :attr:`sys_version` class variables.

   247 

   248 

   249    .. method:: date_time_string([timestamp])

   250 

   251       Returns the date and time given by *timestamp* (which must be in the

   252       format returned by :func:`time.time`), formatted for a message header. If

   253       *timestamp* is omitted, it uses the current date and time.

   254 

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

   256 

   257       .. versionadded:: 2.5

   258          The *timestamp* parameter.

   259 

   260 

   261    .. method:: log_date_time_string()

   262 

   263       Returns the current date and time, formatted for logging.

   264 

   265 

   266    .. method:: address_string()

   267 

   268       Returns the client address, formatted for logging. A name lookup is

   269       performed on the client's IP address.

   270 

   271 

   272 .. seealso::

   273 

   274    Module :mod:`CGIHTTPServer`

   275       Extended request handler that supports CGI scripts.

   276 

   277    Module :mod:`SimpleHTTPServer`

   278       Basic request handler that limits response to files actually under the document

   279       root.

   280