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