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. The :term:`2to3` tool will automatically adapt imports when 10 converting your sources to Python 3. 11 12 13 .. index:: 14 pair: WWW; server 15 pair: HTTP; protocol 16 single: URL 17 single: httpd 18 module: SimpleHTTPServer 19 module: CGIHTTPServer 20 21 **Source code:** :source:`Lib/BaseHTTPServer.py` 22 23 -------------- 24 25 This module defines two classes for implementing HTTP servers (Web servers). 26 Usually, this module isn't used directly, but is used as a basis for building 27 functioning Web servers. See the :mod:`SimpleHTTPServer` and 28 :mod:`CGIHTTPServer` modules. 29 30 The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer` 31 subclass, and therefore implements the :class:`SocketServer.BaseServer` 32 interface. It creates and listens at the HTTP socket, dispatching the requests 33 to 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 44 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. 48 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 53 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. 57 58 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. 64 65 :class:`BaseHTTPRequestHandler` has the following instance variables: 66 67 68 .. attribute:: client_address 69 70 Contains a tuple of the form ``(host, port)`` referring to the client's 71 address. 72 73 74 .. attribute:: server 75 76 Contains the server instance. 77 78 79 .. attribute:: command 80 81 Contains the command (request type). For example, ``'GET'``. 82 83 84 .. attribute:: path 85 86 Contains the request path. 87 88 89 .. attribute:: request_version 90 91 Contains the version string from the request. For example, ``'HTTP/1.0'``. 92 93 94 .. attribute:: headers 95 96 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. 99 100 101 .. attribute:: rfile 102 103 Contains an input stream, positioned at the start of the optional input 104 data. 105 106 107 .. attribute:: wfile 108 109 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. 112 113 114 :class:`BaseHTTPRequestHandler` has the following class variables: 115 116 117 .. attribute:: server_version 118 119 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'``. 122 123 124 .. attribute:: sys_version 125 126 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'``. 129 130 131 .. attribute:: error_message_format 132 133 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. 140 141 142 .. attribute:: error_content_type 143 144 Specifies the Content-Type HTTP header of error responses sent to the 145 client. The default value is ``'text/html'``. 146 147 .. versionadded:: 2.6 148 Previously, the content type was always ``'text/html'``. 149 150 151 .. attribute:: protocol_version 152 153 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'``. 158 159 160 .. 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`. 167 168 169 .. attribute:: responses 170 171 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). 176 177 178 A :class:`BaseHTTPRequestHandler` instance has the following methods: 179 180 181 .. method:: handle() 182 183 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. 187 188 189 .. method:: handle_one_request() 190 191 This method will parse and dispatch the request to the appropriate 192 :meth:`do_\*` method. You should never need to override it. 193 194 195 .. method:: send_error(code[, message]) 196 197 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 200 :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``. 204 205 206 .. method:: send_response(code[, message]) 207 208 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. 212 213 214 .. method:: send_header(keyword, value) 215 216 Writes a specific HTTP header to the output stream. *keyword* should 217 specify the header keyword, with *value* specifying its value. 218 219 220 .. method:: end_headers() 221 222 Sends a blank line, indicating the end of the HTTP headers in the 223 response. 224 225 226 .. method:: log_request([code[, size]]) 227 228 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. 231 232 233 .. method:: log_error(...) 234 235 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). 238 239 240 .. method:: log_message(format, ...) 241 242 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 246 ip address and current date and time are prefixed to every message logged. 247 248 249 .. method:: version_string() 250 251 Returns the server software's version string. This is a combination of the 252 :attr:`server_version` and :attr:`sys_version` class variables. 253 254 255 .. method:: date_time_string([timestamp]) 256 257 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. 260 261 The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``. 262 263 .. versionadded:: 2.5 264 The *timestamp* parameter. 265 266 267 .. method:: log_date_time_string() 268 269 Returns the current date and time, formatted for logging. 270 271 272 .. method:: address_string() 273 274 Returns the client address, formatted for logging. A name lookup is 275 performed on the client's IP address. 276 277 278 More examples 279 ------------- 280 281 To create a server that doesn't run forever, but until some condition is 282 fulfilled:: 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 297 .. seealso:: 298 299 Module :mod:`CGIHTTPServer` 300 Extended request handler that supports CGI scripts. 301 302 Module :mod:`SimpleHTTPServer` 303 Basic request handler that limits response to files actually under the 304 document root. 305 306
