Fixed: #2914 (RFE for UTC support in TimedRotatingFileHandler) and #2929 (wrong filen...
[python.git] / Doc / library / basehttpserver.rst
blob7d5061343839338add837dba7220f93495512199
2 :mod:`BaseHTTPServer` --- Basic HTTP server
3 ===========================================
5 .. module:: BaseHTTPServer
6    :synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
9 .. index::
10    pair: WWW; server
11    pair: HTTP; protocol
12    single: URL
13    single: httpd
15 .. index::
16    module: SimpleHTTPServer
17    module: CGIHTTPServer
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.
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::
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()
35 .. class:: HTTPServer(server_address, RequestHandlerClass)
37    This class builds on the :class:`TCPServer` class by storing the server
38    address as instance variables named :attr:`server_name` and
39    :attr:`server_port`. The server is accessible by the handler, typically
40    through the handler's :attr:`server` instance variable.
43 .. class:: BaseHTTPRequestHandler(request, client_address, server)
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
47    to handle each request method (e.g. GET or
48    POST). :class:`BaseHTTPRequestHandler` provides a number of class and
49    instance variables, and methods for use by subclasses.
51    The handler will parse the request and the headers, then call a method
52    specific to the request type. The method name is constructed from the
53    request. For example, for the request method ``SPAM``, the :meth:`do_SPAM`
54    method will be called with no arguments. All of the relevant information is
55    stored in instance variables of the handler.  Subclasses should not need to
56    override or extend the :meth:`__init__` method.
58    :class:`BaseHTTPRequestHandler` has the following instance variables:
61    .. attribute:: client_address
63       Contains a tuple of the form ``(host, port)`` referring to the client's
64       address.
67    .. attribute:: command
69       Contains the command (request type). For example, ``'GET'``.
72    .. attribute:: path
74       Contains the request path.
77    .. attribute:: request_version
79       Contains the version string from the request. For example, ``'HTTP/1.0'``.
82    .. attribute:: headers
84       Holds an instance of the class specified by the :attr:`MessageClass` class
85       variable. This instance parses and manages the headers in the HTTP
86       request.
89    .. attribute:: rfile
91       Contains an input stream, positioned at the start of the optional input
92       data.
95    .. attribute:: wfile
97       Contains the output stream for writing a response back to the
98       client. Proper adherence to the HTTP protocol must be used when writing to
99       this stream.
102    :class:`BaseHTTPRequestHandler` has the following class variables:
105    .. attribute:: server_version
107       Specifies the server software version.  You may want to override this. The
108       format is multiple whitespace-separated strings, where each string is of
109       the form name[/version]. For example, ``'BaseHTTP/0.2'``.
112    .. attribute:: sys_version
114       Contains the Python system version, in a form usable by the
115       :attr:`version_string` method and the :attr:`server_version` class
116       variable. For example, ``'Python/1.4'``.
119    .. attribute:: error_message_format
121       Specifies a format string for building an error response to the client. It
122       uses parenthesized, keyed format specifiers, so the format operand must be
123       a dictionary. The *code* key should be an integer, specifying the numeric
124       HTTP error code value. *message* should be a string containing a
125       (detailed) error message of what occurred, and *explain* should be an
126       explanation of the error code number. Default *message* and *explain*
127       values can found in the *responses* class variable.
130    .. attribute:: error_content_type
132       Specifies the Content-Type HTTP header of error responses sent to the
133       client.  The default value is ``'text/html'``.
135       .. versionadded:: 2.6
136          Previously, the content type was always ``'text/html'``.
139    .. attribute:: protocol_version
141       This specifies the HTTP protocol version used in responses.  If set to
142       ``'HTTP/1.1'``, the server will permit HTTP persistent connections;
143       however, your server *must* then include an accurate ``Content-Length``
144       header (using :meth:`send_header`) in all of its responses to clients.
145       For backwards compatibility, the setting defaults to ``'HTTP/1.0'``.
148    .. attribute:: MessageClass
150       .. index:: single: Message (in module mimetools)
152       Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
153       Typically, this is not overridden, and it defaults to
154       :class:`mimetools.Message`.
157    .. attribute:: responses
159       This variable contains a mapping of error code integers to two-element tuples
160       containing a short and long message. For example, ``{code: (shortmessage,
161       longmessage)}``. The *shortmessage* is usually used as the *message* key in an
162       error response, and *longmessage* as the *explain* key (see the
163       :attr:`error_message_format` class variable).
166    A :class:`BaseHTTPRequestHandler` instance has the following methods:
169    .. method:: handle()
171       Calls :meth:`handle_one_request` once (or, if persistent connections are
172       enabled, multiple times) to handle incoming HTTP requests. You should
173       never need to override it; instead, implement appropriate :meth:`do_\*`
174       methods.
177    .. method:: handle_one_request()
179       This method will parse and dispatch the request to the appropriate
180       :meth:`do_\*` method.  You should never need to override it.
183    .. method:: send_error(code[, message])
185       Sends and logs a complete error reply to the client. The numeric *code*
186       specifies the HTTP error code, with *message* as optional, more specific text. A
187       complete set of headers is sent, followed by text composed using the
188       :attr:`error_message_format` class variable.
191    .. method:: send_response(code[, message])
193       Sends a response header and logs the accepted request. The HTTP response
194       line is sent, followed by *Server* and *Date* headers. The values for
195       these two headers are picked up from the :meth:`version_string` and
196       :meth:`date_time_string` methods, respectively.
199    .. method:: send_header(keyword, value)
201       Writes a specific HTTP header to the output stream. *keyword* should
202       specify the header keyword, with *value* specifying its value.
205    .. method:: end_headers()
207       Sends a blank line, indicating the end of the HTTP headers in the
208       response.
211    .. method:: log_request([code[, size]])
213       Logs an accepted (successful) request. *code* should specify the numeric
214       HTTP code associated with the response. If a size of the response is
215       available, then it should be passed as the *size* parameter.
218    .. method:: log_error(...)
220       Logs an error when a request cannot be fulfilled. By default, it passes
221       the message to :meth:`log_message`, so it takes the same arguments
222       (*format* and additional values).
225    .. method:: log_message(format, ...)
227       Logs an arbitrary message to ``sys.stderr``. This is typically overridden
228       to create custom error logging mechanisms. The *format* argument is a
229       standard printf-style format string, where the additional arguments to
230       :meth:`log_message` are applied as inputs to the formatting. The client
231       address and current date and time are prefixed to every message logged.
234    .. method:: version_string()
236       Returns the server software's version string. This is a combination of the
237       :attr:`server_version` and :attr:`sys_version` class variables.
240    .. method:: date_time_string([timestamp])
242       Returns the date and time given by *timestamp* (which must be in the
243       format returned by :func:`time.time`), formatted for a message header. If
244       *timestamp* is omitted, it uses the current date and time.
246       The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
248       .. versionadded:: 2.5
249          The *timestamp* parameter.
252    .. method:: log_date_time_string()
254       Returns the current date and time, formatted for logging.
257    .. method:: address_string()
259       Returns the client address, formatted for logging. A name lookup is
260       performed on the client's IP address.
263 .. seealso::
265    Module :mod:`CGIHTTPServer`
266       Extended request handler that supports CGI scripts.
268    Module :mod:`SimpleHTTPServer`
269       Basic request handler that limits response to files actually under the document
270       root.