blob: 0c663fec3096c54af508fd13a23b5d707aa7d21d [file] [log] [blame]
Georg Brandl8ec7f652007-08-15 14:28:01 +00001:mod:`BaseHTTPServer` --- Basic HTTP server
2===========================================
3
4.. module:: BaseHTTPServer
5 :synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
6
Georg Brandl8de91192008-05-26 15:01:48 +00007.. note::
8 The :mod:`BaseHTTPServer` module has been merged into :mod:`http.server` in
Ezio Melotti510ff542012-05-03 19:21:40 +03009 Python 3. The :term:`2to3` tool will automatically adapt imports when
10 converting your sources to Python 3.
Georg Brandl8de91192008-05-26 15:01:48 +000011
Georg Brandl8ec7f652007-08-15 14:28:01 +000012
13.. index::
14 pair: WWW; server
15 pair: HTTP; protocol
16 single: URL
17 single: httpd
Georg Brandl8ec7f652007-08-15 14:28:01 +000018 module: SimpleHTTPServer
19 module: CGIHTTPServer
20
Éric Araujo29a0b572011-08-19 02:14:03 +020021**Source code:** :source:`Lib/BaseHTTPServer.py`
22
23--------------
24
Georg Brandl8ec7f652007-08-15 14:28:01 +000025This module defines two classes for implementing HTTP servers (Web servers).
26Usually, this module isn't used directly, but is used as a basis for building
27functioning Web servers. See the :mod:`SimpleHTTPServer` and
28:mod:`CGIHTTPServer` modules.
29
Georg Brandle152a772008-05-24 18:31:28 +000030The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
Georg Brandl9af0c562009-04-05 10:24:20 +000031subclass, and therefore implements the :class:`SocketServer.BaseServer`
32interface. It creates and listens at the HTTP socket, dispatching the requests
Georg Brandl8ec7f652007-08-15 14:28:01 +000033to a handler. Code to create and run the server looks like this::
34
35 def run(server_class=BaseHTTPServer.HTTPServer,
36 handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
37 server_address = ('', 8000)
38 httpd = server_class(server_address, handler_class)
39 httpd.serve_forever()
40
41
42.. class:: HTTPServer(server_address, RequestHandlerClass)
43
Benjamin Petersonc7b05922008-04-25 01:29:10 +000044 This class builds on the :class:`TCPServer` class by storing the server
45 address as instance variables named :attr:`server_name` and
46 :attr:`server_port`. The server is accessible by the handler, typically
47 through the handler's :attr:`server` instance variable.
Georg Brandl8ec7f652007-08-15 14:28:01 +000048
49
50.. class:: BaseHTTPRequestHandler(request, client_address, server)
51
52 This class is used to handle the HTTP requests that arrive at the server. By
Benjamin Petersonc7b05922008-04-25 01:29:10 +000053 itself, it cannot respond to any actual HTTP requests; it must be subclassed
54 to handle each request method (e.g. GET or
55 POST). :class:`BaseHTTPRequestHandler` provides a number of class and
56 instance variables, and methods for use by subclasses.
Georg Brandl8ec7f652007-08-15 14:28:01 +000057
Benjamin Petersonc7b05922008-04-25 01:29:10 +000058 The handler will parse the request and the headers, then call a method
59 specific to the request type. The method name is constructed from the
60 request. For example, for the request method ``SPAM``, the :meth:`do_SPAM`
61 method will be called with no arguments. All of the relevant information is
62 stored in instance variables of the handler. Subclasses should not need to
63 override or extend the :meth:`__init__` method.
Georg Brandl8ec7f652007-08-15 14:28:01 +000064
Benjamin Petersonc7b05922008-04-25 01:29:10 +000065 :class:`BaseHTTPRequestHandler` has the following instance variables:
Georg Brandl8ec7f652007-08-15 14:28:01 +000066
67
Benjamin Petersonc7b05922008-04-25 01:29:10 +000068 .. attribute:: client_address
Georg Brandl8ec7f652007-08-15 14:28:01 +000069
Benjamin Petersonc7b05922008-04-25 01:29:10 +000070 Contains a tuple of the form ``(host, port)`` referring to the client's
71 address.
Georg Brandl8ec7f652007-08-15 14:28:01 +000072
73
Georg Brandlcff0b462008-08-30 09:49:36 +000074 .. attribute:: server
75
76 Contains the server instance.
77
78
Benjamin Petersonc7b05922008-04-25 01:29:10 +000079 .. attribute:: command
Georg Brandl8ec7f652007-08-15 14:28:01 +000080
Benjamin Petersonc7b05922008-04-25 01:29:10 +000081 Contains the command (request type). For example, ``'GET'``.
Georg Brandl8ec7f652007-08-15 14:28:01 +000082
83
Benjamin Petersonc7b05922008-04-25 01:29:10 +000084 .. attribute:: path
Georg Brandl8ec7f652007-08-15 14:28:01 +000085
Benjamin Petersonc7b05922008-04-25 01:29:10 +000086 Contains the request path.
Georg Brandl8ec7f652007-08-15 14:28:01 +000087
88
Benjamin Petersonc7b05922008-04-25 01:29:10 +000089 .. attribute:: request_version
Georg Brandl8ec7f652007-08-15 14:28:01 +000090
Benjamin Petersonc7b05922008-04-25 01:29:10 +000091 Contains the version string from the request. For example, ``'HTTP/1.0'``.
Georg Brandl8ec7f652007-08-15 14:28:01 +000092
93
Benjamin Petersonc7b05922008-04-25 01:29:10 +000094 .. attribute:: headers
Georg Brandl8ec7f652007-08-15 14:28:01 +000095
Benjamin Petersonc7b05922008-04-25 01:29:10 +000096 Holds an instance of the class specified by the :attr:`MessageClass` class
97 variable. This instance parses and manages the headers in the HTTP
98 request.
Georg Brandl8ec7f652007-08-15 14:28:01 +000099
100
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000101 .. attribute:: rfile
Georg Brandl8ec7f652007-08-15 14:28:01 +0000102
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000103 Contains an input stream, positioned at the start of the optional input
104 data.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000105
106
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000107 .. attribute:: wfile
Georg Brandl8ec7f652007-08-15 14:28:01 +0000108
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000109 Contains the output stream for writing a response back to the
110 client. Proper adherence to the HTTP protocol must be used when writing to
111 this stream.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000112
Georg Brandl8ec7f652007-08-15 14:28:01 +0000113
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000114 :class:`BaseHTTPRequestHandler` has the following class variables:
Georg Brandl8ec7f652007-08-15 14:28:01 +0000115
Georg Brandl8ec7f652007-08-15 14:28:01 +0000116
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000117 .. attribute:: server_version
Georg Brandl8ec7f652007-08-15 14:28:01 +0000118
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000119 Specifies the server software version. You may want to override this. The
120 format is multiple whitespace-separated strings, where each string is of
121 the form name[/version]. For example, ``'BaseHTTP/0.2'``.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000122
Georg Brandl8ec7f652007-08-15 14:28:01 +0000123
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000124 .. attribute:: sys_version
Georg Brandl8ec7f652007-08-15 14:28:01 +0000125
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000126 Contains the Python system version, in a form usable by the
127 :attr:`version_string` method and the :attr:`server_version` class
128 variable. For example, ``'Python/1.4'``.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000129
Georg Brandl8ec7f652007-08-15 14:28:01 +0000130
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000131 .. attribute:: error_message_format
Georg Brandl8ec7f652007-08-15 14:28:01 +0000132
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000133 Specifies a format string for building an error response to the client. It
134 uses parenthesized, keyed format specifiers, so the format operand must be
135 a dictionary. The *code* key should be an integer, specifying the numeric
136 HTTP error code value. *message* should be a string containing a
137 (detailed) error message of what occurred, and *explain* should be an
138 explanation of the error code number. Default *message* and *explain*
139 values can found in the *responses* class variable.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000140
Georg Brandl16479232008-02-23 15:02:28 +0000141
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000142 .. attribute:: error_content_type
Georg Brandl16479232008-02-23 15:02:28 +0000143
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000144 Specifies the Content-Type HTTP header of error responses sent to the
145 client. The default value is ``'text/html'``.
Georg Brandl16479232008-02-23 15:02:28 +0000146
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000147 .. versionadded:: 2.6
148 Previously, the content type was always ``'text/html'``.
Georg Brandl16479232008-02-23 15:02:28 +0000149
Georg Brandl8ec7f652007-08-15 14:28:01 +0000150
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000151 .. attribute:: protocol_version
Georg Brandl8ec7f652007-08-15 14:28:01 +0000152
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000153 This specifies the HTTP protocol version used in responses. If set to
154 ``'HTTP/1.1'``, the server will permit HTTP persistent connections;
155 however, your server *must* then include an accurate ``Content-Length``
156 header (using :meth:`send_header`) in all of its responses to clients.
157 For backwards compatibility, the setting defaults to ``'HTTP/1.0'``.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000158
Georg Brandl8ec7f652007-08-15 14:28:01 +0000159
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000160 .. attribute:: MessageClass
161
162 .. index:: single: Message (in module mimetools)
163
164 Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
165 Typically, this is not overridden, and it defaults to
166 :class:`mimetools.Message`.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000167
Georg Brandl8ec7f652007-08-15 14:28:01 +0000168
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000169 .. attribute:: responses
Georg Brandl8ec7f652007-08-15 14:28:01 +0000170
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000171 This variable contains a mapping of error code integers to two-element tuples
172 containing a short and long message. For example, ``{code: (shortmessage,
173 longmessage)}``. The *shortmessage* is usually used as the *message* key in an
174 error response, and *longmessage* as the *explain* key (see the
175 :attr:`error_message_format` class variable).
Georg Brandl8ec7f652007-08-15 14:28:01 +0000176
Georg Brandl8ec7f652007-08-15 14:28:01 +0000177
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000178 A :class:`BaseHTTPRequestHandler` instance has the following methods:
Georg Brandl8ec7f652007-08-15 14:28:01 +0000179
180
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000181 .. method:: handle()
Georg Brandl8ec7f652007-08-15 14:28:01 +0000182
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000183 Calls :meth:`handle_one_request` once (or, if persistent connections are
184 enabled, multiple times) to handle incoming HTTP requests. You should
185 never need to override it; instead, implement appropriate :meth:`do_\*`
186 methods.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000187
188
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000189 .. method:: handle_one_request()
Georg Brandl8ec7f652007-08-15 14:28:01 +0000190
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000191 This method will parse and dispatch the request to the appropriate
192 :meth:`do_\*` method. You should never need to override it.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000193
194
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000195 .. method:: send_error(code[, message])
Georg Brandl8ec7f652007-08-15 14:28:01 +0000196
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000197 Sends and logs a complete error reply to the client. The numeric *code*
198 specifies the HTTP error code, with *message* as optional, more specific text. A
199 complete set of headers is sent, followed by text composed using the
Martin Panter6af1c492016-06-08 07:16:14 +0000200 :attr:`error_message_format` class variable. The body will be empty
201 if the method is HEAD or the response code is one of the following:
202 ``1xx``, ``204 No Content``, ``205 Reset Content``,
203 ``304 Not Modified``.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000204
205
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000206 .. method:: send_response(code[, message])
Georg Brandl8ec7f652007-08-15 14:28:01 +0000207
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000208 Sends a response header and logs the accepted request. The HTTP response
209 line is sent, followed by *Server* and *Date* headers. The values for
210 these two headers are picked up from the :meth:`version_string` and
211 :meth:`date_time_string` methods, respectively.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000212
213
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000214 .. method:: send_header(keyword, value)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000215
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000216 Writes a specific HTTP header to the output stream. *keyword* should
217 specify the header keyword, with *value* specifying its value.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000218
219
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000220 .. method:: end_headers()
Georg Brandl8ec7f652007-08-15 14:28:01 +0000221
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000222 Sends a blank line, indicating the end of the HTTP headers in the
223 response.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000224
225
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000226 .. method:: log_request([code[, size]])
Georg Brandl8ec7f652007-08-15 14:28:01 +0000227
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000228 Logs an accepted (successful) request. *code* should specify the numeric
229 HTTP code associated with the response. If a size of the response is
230 available, then it should be passed as the *size* parameter.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000231
232
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000233 .. method:: log_error(...)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000234
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000235 Logs an error when a request cannot be fulfilled. By default, it passes
236 the message to :meth:`log_message`, so it takes the same arguments
237 (*format* and additional values).
Georg Brandl8ec7f652007-08-15 14:28:01 +0000238
239
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000240 .. method:: log_message(format, ...)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000241
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000242 Logs an arbitrary message to ``sys.stderr``. This is typically overridden
243 to create custom error logging mechanisms. The *format* argument is a
244 standard printf-style format string, where the additional arguments to
245 :meth:`log_message` are applied as inputs to the formatting. The client
Senthil Kumaranfb5aebc2012-04-29 13:39:16 +0800246 ip address and current date and time are prefixed to every message logged.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000247
248
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000249 .. method:: version_string()
Georg Brandl8ec7f652007-08-15 14:28:01 +0000250
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000251 Returns the server software's version string. This is a combination of the
252 :attr:`server_version` and :attr:`sys_version` class variables.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000253
254
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000255 .. method:: date_time_string([timestamp])
Georg Brandl8ec7f652007-08-15 14:28:01 +0000256
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000257 Returns the date and time given by *timestamp* (which must be in the
258 format returned by :func:`time.time`), formatted for a message header. If
259 *timestamp* is omitted, it uses the current date and time.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000260
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000261 The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000262
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000263 .. versionadded:: 2.5
264 The *timestamp* parameter.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000265
266
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000267 .. method:: log_date_time_string()
Georg Brandl8ec7f652007-08-15 14:28:01 +0000268
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000269 Returns the current date and time, formatted for logging.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000270
271
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000272 .. method:: address_string()
Georg Brandl8ec7f652007-08-15 14:28:01 +0000273
Benjamin Petersonc7b05922008-04-25 01:29:10 +0000274 Returns the client address, formatted for logging. A name lookup is
275 performed on the client's IP address.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000276
277
Georg Brandl9af0c562009-04-05 10:24:20 +0000278More examples
279-------------
280
281To create a server that doesn't run forever, but until some condition is
282fulfilled::
283
284 def run_while_true(server_class=BaseHTTPServer.HTTPServer,
285 handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
286 """
287 This assumes that keep_running() is a function of no arguments which
288 is tested initially and after each request. If its return value
289 is true, the server continues.
290 """
291 server_address = ('', 8000)
292 httpd = server_class(server_address, handler_class)
293 while keep_running():
294 httpd.handle_request()
295
296
Georg Brandl8ec7f652007-08-15 14:28:01 +0000297.. seealso::
298
299 Module :mod:`CGIHTTPServer`
300 Extended request handler that supports CGI scripts.
301
302 Module :mod:`SimpleHTTPServer`
Georg Brandl9af0c562009-04-05 10:24:20 +0000303 Basic request handler that limits response to files actually under the
304 document root.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000305