Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 1 | :mod:`http.server` --- HTTP servers |
| 2 | =================================== |
| 3 | |
| 4 | .. module:: http.server |
| 5 | :synopsis: HTTP server and request handlers. |
| 6 | |
| 7 | |
| 8 | .. index:: |
| 9 | pair: WWW; server |
| 10 | pair: HTTP; protocol |
| 11 | single: URL |
| 12 | single: httpd |
| 13 | |
| 14 | This module defines classes for implementing HTTP servers (Web servers). |
| 15 | |
| 16 | One class, :class:`HTTPServer`, is a :class:`socketserver.TCPServer` subclass. |
| 17 | It creates and listens at the HTTP socket, dispatching the requests to a |
| 18 | handler. Code to create and run the server looks like this:: |
| 19 | |
| 20 | def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler): |
| 21 | server_address = ('', 8000) |
| 22 | httpd = server_class(server_address, handler_class) |
| 23 | httpd.serve_forever() |
| 24 | |
| 25 | |
| 26 | .. class:: HTTPServer(server_address, RequestHandlerClass) |
| 27 | |
| 28 | This class builds on the :class:`TCPServer` class by storing the server |
| 29 | address as instance variables named :attr:`server_name` and |
| 30 | :attr:`server_port`. The server is accessible by the handler, typically |
| 31 | through the handler's :attr:`server` instance variable. |
| 32 | |
| 33 | |
| 34 | The :class:`HTTPServer` must be given a *RequestHandlerClass* on instantiation, |
| 35 | of which this module provides three different variants: |
| 36 | |
| 37 | .. class:: BaseHTTPRequestHandler(request, client_address, server) |
| 38 | |
| 39 | This class is used to handle the HTTP requests that arrive at the server. By |
| 40 | itself, it cannot respond to any actual HTTP requests; it must be subclassed |
| 41 | to handle each request method (e.g. GET or POST). |
| 42 | :class:`BaseHTTPRequestHandler` provides a number of class and instance |
| 43 | variables, and methods for use by subclasses. |
| 44 | |
| 45 | The handler will parse the request and the headers, then call a method |
| 46 | specific to the request type. The method name is constructed from the |
| 47 | request. For example, for the request method ``SPAM``, the :meth:`do_SPAM` |
| 48 | method will be called with no arguments. All of the relevant information is |
| 49 | stored in instance variables of the handler. Subclasses should not need to |
| 50 | override or extend the :meth:`__init__` method. |
| 51 | |
| 52 | :class:`BaseHTTPRequestHandler` has the following instance variables: |
| 53 | |
| 54 | .. attribute:: client_address |
| 55 | |
| 56 | Contains a tuple of the form ``(host, port)`` referring to the client's |
| 57 | address. |
| 58 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame^] | 59 | .. attribute:: server |
| 60 | |
| 61 | Contains the server instance. |
| 62 | |
| 63 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 64 | .. attribute:: command |
| 65 | |
| 66 | Contains the command (request type). For example, ``'GET'``. |
| 67 | |
| 68 | .. attribute:: path |
| 69 | |
| 70 | Contains the request path. |
| 71 | |
| 72 | .. attribute:: request_version |
| 73 | |
| 74 | Contains the version string from the request. For example, ``'HTTP/1.0'``. |
| 75 | |
| 76 | .. attribute:: headers |
| 77 | |
| 78 | Holds an instance of the class specified by the :attr:`MessageClass` class |
| 79 | variable. This instance parses and manages the headers in the HTTP |
| 80 | request. |
| 81 | |
| 82 | .. attribute:: rfile |
| 83 | |
| 84 | Contains an input stream, positioned at the start of the optional input |
| 85 | data. |
| 86 | |
| 87 | .. attribute:: wfile |
| 88 | |
| 89 | Contains the output stream for writing a response back to the |
| 90 | client. Proper adherence to the HTTP protocol must be used when writing to |
| 91 | this stream. |
| 92 | |
| 93 | :class:`BaseHTTPRequestHandler` has the following class variables: |
| 94 | |
| 95 | .. attribute:: server_version |
| 96 | |
| 97 | Specifies the server software version. You may want to override this. The |
| 98 | format is multiple whitespace-separated strings, where each string is of |
| 99 | the form name[/version]. For example, ``'BaseHTTP/0.2'``. |
| 100 | |
| 101 | .. attribute:: sys_version |
| 102 | |
| 103 | Contains the Python system version, in a form usable by the |
| 104 | :attr:`version_string` method and the :attr:`server_version` class |
| 105 | variable. For example, ``'Python/1.4'``. |
| 106 | |
| 107 | .. attribute:: error_message_format |
| 108 | |
| 109 | Specifies a format string for building an error response to the client. It |
| 110 | uses parenthesized, keyed format specifiers, so the format operand must be |
| 111 | a dictionary. The *code* key should be an integer, specifying the numeric |
| 112 | HTTP error code value. *message* should be a string containing a |
| 113 | (detailed) error message of what occurred, and *explain* should be an |
| 114 | explanation of the error code number. Default *message* and *explain* |
| 115 | values can found in the *responses* class variable. |
| 116 | |
| 117 | .. attribute:: error_content_type |
| 118 | |
| 119 | Specifies the Content-Type HTTP header of error responses sent to the |
| 120 | client. The default value is ``'text/html'``. |
| 121 | |
| 122 | .. attribute:: protocol_version |
| 123 | |
| 124 | This specifies the HTTP protocol version used in responses. If set to |
| 125 | ``'HTTP/1.1'``, the server will permit HTTP persistent connections; |
| 126 | however, your server *must* then include an accurate ``Content-Length`` |
| 127 | header (using :meth:`send_header`) in all of its responses to clients. |
| 128 | For backwards compatibility, the setting defaults to ``'HTTP/1.0'``. |
| 129 | |
| 130 | .. attribute:: MessageClass |
| 131 | |
Georg Brandl | 83e9f4c | 2008-06-12 18:52:31 +0000 | [diff] [blame] | 132 | Specifies an :class:`email.message.Message`\ -like class to parse HTTP |
| 133 | headers. Typically, this is not overridden, and it defaults to |
| 134 | :class:`http.client.HTTPMessage`. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 135 | |
| 136 | .. attribute:: responses |
| 137 | |
| 138 | This variable contains a mapping of error code integers to two-element tuples |
| 139 | containing a short and long message. For example, ``{code: (shortmessage, |
| 140 | longmessage)}``. The *shortmessage* is usually used as the *message* key in an |
| 141 | error response, and *longmessage* as the *explain* key (see the |
| 142 | :attr:`error_message_format` class variable). |
| 143 | |
| 144 | A :class:`BaseHTTPRequestHandler` instance has the following methods: |
| 145 | |
| 146 | .. method:: handle() |
| 147 | |
| 148 | Calls :meth:`handle_one_request` once (or, if persistent connections are |
| 149 | enabled, multiple times) to handle incoming HTTP requests. You should |
| 150 | never need to override it; instead, implement appropriate :meth:`do_\*` |
| 151 | methods. |
| 152 | |
| 153 | .. method:: handle_one_request() |
| 154 | |
| 155 | This method will parse and dispatch the request to the appropriate |
| 156 | :meth:`do_\*` method. You should never need to override it. |
| 157 | |
| 158 | .. method:: send_error(code[, message]) |
| 159 | |
| 160 | Sends and logs a complete error reply to the client. The numeric *code* |
| 161 | specifies the HTTP error code, with *message* as optional, more specific text. A |
| 162 | complete set of headers is sent, followed by text composed using the |
| 163 | :attr:`error_message_format` class variable. |
| 164 | |
| 165 | .. method:: send_response(code[, message]) |
| 166 | |
| 167 | Sends a response header and logs the accepted request. The HTTP response |
| 168 | line is sent, followed by *Server* and *Date* headers. The values for |
| 169 | these two headers are picked up from the :meth:`version_string` and |
| 170 | :meth:`date_time_string` methods, respectively. |
| 171 | |
| 172 | .. method:: send_header(keyword, value) |
| 173 | |
| 174 | Writes a specific HTTP header to the output stream. *keyword* should |
| 175 | specify the header keyword, with *value* specifying its value. |
| 176 | |
| 177 | .. method:: end_headers() |
| 178 | |
| 179 | Sends a blank line, indicating the end of the HTTP headers in the |
| 180 | response. |
| 181 | |
| 182 | .. method:: log_request([code[, size]]) |
| 183 | |
| 184 | Logs an accepted (successful) request. *code* should specify the numeric |
| 185 | HTTP code associated with the response. If a size of the response is |
| 186 | available, then it should be passed as the *size* parameter. |
| 187 | |
| 188 | .. method:: log_error(...) |
| 189 | |
| 190 | Logs an error when a request cannot be fulfilled. By default, it passes |
| 191 | the message to :meth:`log_message`, so it takes the same arguments |
| 192 | (*format* and additional values). |
| 193 | |
| 194 | |
| 195 | .. method:: log_message(format, ...) |
| 196 | |
| 197 | Logs an arbitrary message to ``sys.stderr``. This is typically overridden |
| 198 | to create custom error logging mechanisms. The *format* argument is a |
| 199 | standard printf-style format string, where the additional arguments to |
| 200 | :meth:`log_message` are applied as inputs to the formatting. The client |
| 201 | address and current date and time are prefixed to every message logged. |
| 202 | |
| 203 | .. method:: version_string() |
| 204 | |
| 205 | Returns the server software's version string. This is a combination of the |
| 206 | :attr:`server_version` and :attr:`sys_version` class variables. |
| 207 | |
| 208 | .. method:: date_time_string([timestamp]) |
| 209 | |
| 210 | Returns the date and time given by *timestamp* (which must be in the |
| 211 | format returned by :func:`time.time`), formatted for a message header. If |
| 212 | *timestamp* is omitted, it uses the current date and time. |
| 213 | |
| 214 | The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``. |
| 215 | |
| 216 | .. method:: log_date_time_string() |
| 217 | |
| 218 | Returns the current date and time, formatted for logging. |
| 219 | |
| 220 | .. method:: address_string() |
| 221 | |
| 222 | Returns the client address, formatted for logging. A name lookup is |
| 223 | performed on the client's IP address. |
| 224 | |
| 225 | |
| 226 | .. class:: SimpleHTTPRequestHandler(request, client_address, server) |
| 227 | |
| 228 | This class serves files from the current directory and below, directly |
| 229 | mapping the directory structure to HTTP requests. |
| 230 | |
| 231 | A lot of the work, such as parsing the request, is done by the base class |
| 232 | :class:`BaseHTTPRequestHandler`. This class implements the :func:`do_GET` |
| 233 | and :func:`do_HEAD` functions. |
| 234 | |
| 235 | The following are defined as class-level attributes of |
| 236 | :class:`SimpleHTTPRequestHandler`: |
| 237 | |
| 238 | .. attribute:: server_version |
| 239 | |
| 240 | This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is |
| 241 | defined at the module level. |
| 242 | |
| 243 | .. attribute:: extensions_map |
| 244 | |
| 245 | A dictionary mapping suffixes into MIME types. The default is |
| 246 | signified by an empty string, and is considered to be |
| 247 | ``application/octet-stream``. The mapping is used case-insensitively, |
| 248 | and so should contain only lower-cased keys. |
| 249 | |
| 250 | The :class:`SimpleHTTPRequestHandler` class defines the following methods: |
| 251 | |
| 252 | .. method:: do_HEAD() |
| 253 | |
| 254 | This method serves the ``'HEAD'`` request type: it sends the headers it |
| 255 | would send for the equivalent ``GET`` request. See the :meth:`do_GET` |
| 256 | method for a more complete explanation of the possible headers. |
| 257 | |
| 258 | .. method:: do_GET() |
| 259 | |
| 260 | The request is mapped to a local file by interpreting the request as a |
| 261 | path relative to the current working directory. |
| 262 | |
| 263 | If the request was mapped to a directory, the directory is checked for a |
| 264 | file named ``index.html`` or ``index.htm`` (in that order). If found, the |
| 265 | file's contents are returned; otherwise a directory listing is generated |
| 266 | by calling the :meth:`list_directory` method. This method uses |
| 267 | :func:`os.listdir` to scan the directory, and returns a ``404`` error |
| 268 | response if the :func:`listdir` fails. |
| 269 | |
| 270 | If the request was mapped to a file, it is opened and the contents are |
| 271 | returned. Any :exc:`IOError` exception in opening the requested file is |
| 272 | mapped to a ``404``, ``'File not found'`` error. Otherwise, the content |
| 273 | type is guessed by calling the :meth:`guess_type` method, which in turn |
| 274 | uses the *extensions_map* variable. |
| 275 | |
| 276 | A ``'Content-type:'`` header with the guessed content type is output, |
| 277 | followed by a ``'Content-Length:'`` header with the file's size and a |
| 278 | ``'Last-Modified:'`` header with the file's modification time. |
| 279 | |
| 280 | Then follows a blank line signifying the end of the headers, and then the |
| 281 | contents of the file are output. If the file's MIME type starts with |
| 282 | ``text/`` the file is opened in text mode; otherwise binary mode is used. |
| 283 | |
| 284 | For example usage, see the implementation of the :func:`test` function. |
| 285 | |
| 286 | |
| 287 | .. class:: CGIHTTPRequestHandler(request, client_address, server) |
| 288 | |
| 289 | This class is used to serve either files or output of CGI scripts from the |
| 290 | current directory and below. Note that mapping HTTP hierarchic structure to |
| 291 | local directory structure is exactly as in :class:`SimpleHTTPRequestHandler`. |
| 292 | |
| 293 | .. note:: |
| 294 | |
| 295 | CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute |
| 296 | redirects (HTTP code 302), because code 200 (script output follows) is |
| 297 | sent prior to execution of the CGI script. This pre-empts the status |
| 298 | code. |
| 299 | |
| 300 | The class will however, run the CGI script, instead of serving it as a file, |
| 301 | if it guesses it to be a CGI script. Only directory-based CGI are used --- |
| 302 | the other common server configuration is to treat special extensions as |
| 303 | denoting CGI scripts. |
| 304 | |
| 305 | The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts |
| 306 | and serve the output, instead of serving files, if the request leads to |
| 307 | somewhere below the ``cgi_directories`` path. |
| 308 | |
| 309 | The :class:`CGIHTTPRequestHandler` defines the following data member: |
| 310 | |
| 311 | .. attribute:: cgi_directories |
| 312 | |
| 313 | This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to |
| 314 | treat as containing CGI scripts. |
| 315 | |
| 316 | The :class:`CGIHTTPRequestHandler` defines the following method: |
| 317 | |
| 318 | .. method:: do_POST() |
| 319 | |
| 320 | This method serves the ``'POST'`` request type, only allowed for CGI |
| 321 | scripts. Error 501, "Can only POST to CGI scripts", is output when trying |
| 322 | to POST to a non-CGI url. |
| 323 | |
| 324 | Note that CGI scripts will be run with UID of user nobody, for security |
| 325 | reasons. Problems with the CGI script will be translated to error 403. |