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 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/http/server.py` |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 8 | |
| 9 | .. index:: |
| 10 | pair: WWW; server |
| 11 | pair: HTTP; protocol |
| 12 | single: URL |
| 13 | single: httpd |
| 14 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 15 | -------------- |
| 16 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 17 | This module defines classes for implementing HTTP servers (Web servers). |
| 18 | |
| 19 | One class, :class:`HTTPServer`, is a :class:`socketserver.TCPServer` subclass. |
| 20 | It creates and listens at the HTTP socket, dispatching the requests to a |
| 21 | handler. Code to create and run the server looks like this:: |
| 22 | |
| 23 | def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler): |
| 24 | server_address = ('', 8000) |
| 25 | httpd = server_class(server_address, handler_class) |
| 26 | httpd.serve_forever() |
| 27 | |
| 28 | |
| 29 | .. class:: HTTPServer(server_address, RequestHandlerClass) |
| 30 | |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 31 | This class builds on the :class:`~socketserver.TCPServer` class by storing |
| 32 | the server address as instance variables named :attr:`server_name` and |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 33 | :attr:`server_port`. The server is accessible by the handler, typically |
| 34 | through the handler's :attr:`server` instance variable. |
| 35 | |
Géry Ogam | 1cee216 | 2018-05-29 22:10:30 +0200 | [diff] [blame] | 36 | .. class:: ThreadingHTTPServer(server_address, RequestHandlerClass) |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 37 | |
Julien Palard | 8bcfa02 | 2018-03-23 17:40:33 +0100 | [diff] [blame] | 38 | This class is identical to HTTPServer but uses threads to handle |
Alex Gaynor | 1d87c7b | 2018-04-06 08:26:49 -0400 | [diff] [blame] | 39 | requests by using the :class:`~socketserver.ThreadingMixIn`. This |
Julien Palard | 79c3bab | 2018-03-28 23:24:58 +0200 | [diff] [blame] | 40 | is useful to handle web browsers pre-opening sockets, on which |
| 41 | :class:`HTTPServer` would wait indefinitely. |
| 42 | |
| 43 | .. versionadded:: 3.7 |
| 44 | |
Julien Palard | 8bcfa02 | 2018-03-23 17:40:33 +0100 | [diff] [blame] | 45 | |
Géry Ogam | 1cee216 | 2018-05-29 22:10:30 +0200 | [diff] [blame] | 46 | The :class:`HTTPServer` and :class:`ThreadingHTTPServer` must be given |
Julien Palard | 8bcfa02 | 2018-03-23 17:40:33 +0100 | [diff] [blame] | 47 | a *RequestHandlerClass* on instantiation, of which this module |
| 48 | provides three different variants: |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 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 POST). |
| 55 | :class:`BaseHTTPRequestHandler` provides a number of class and instance |
| 56 | 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 | .. attribute:: client_address |
| 68 | |
| 69 | Contains a tuple of the form ``(host, port)`` referring to the client's |
| 70 | address. |
| 71 | |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 72 | .. attribute:: server |
| 73 | |
| 74 | Contains the server instance. |
| 75 | |
Benjamin Peterson | 70e2847 | 2015-02-17 21:11:10 -0500 | [diff] [blame] | 76 | .. attribute:: close_connection |
| 77 | |
| 78 | Boolean that should be set before :meth:`handle_one_request` returns, |
| 79 | indicating if another request may be expected, or if the connection should |
| 80 | be shut down. |
| 81 | |
| 82 | .. attribute:: requestline |
| 83 | |
| 84 | Contains the string representation of the HTTP request line. The |
| 85 | terminating CRLF is stripped. This attribute should be set by |
| 86 | :meth:`handle_one_request`. If no valid request line was processed, it |
| 87 | should be set to the empty string. |
Benjamin Peterson | 3e4f055 | 2008-09-02 00:31:15 +0000 | [diff] [blame] | 88 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 89 | .. attribute:: command |
| 90 | |
| 91 | Contains the command (request type). For example, ``'GET'``. |
| 92 | |
| 93 | .. attribute:: path |
| 94 | |
| 95 | Contains the request path. |
| 96 | |
| 97 | .. attribute:: request_version |
| 98 | |
| 99 | Contains the version string from the request. For example, ``'HTTP/1.0'``. |
| 100 | |
| 101 | .. attribute:: headers |
| 102 | |
| 103 | Holds an instance of the class specified by the :attr:`MessageClass` class |
| 104 | variable. This instance parses and manages the headers in the HTTP |
Senthil Kumaran | cad2bf2 | 2014-04-16 13:56:19 -0400 | [diff] [blame] | 105 | request. The :func:`~http.client.parse_headers` function from |
| 106 | :mod:`http.client` is used to parse the headers and it requires that the |
| 107 | HTTP request provide a valid :rfc:`2822` style header. |
| 108 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 109 | .. attribute:: rfile |
| 110 | |
Martin Panter | 34eeed4 | 2016-06-29 10:12:22 +0000 | [diff] [blame] | 111 | An :class:`io.BufferedIOBase` input stream, ready to read from |
| 112 | the start of the optional input data. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 113 | |
| 114 | .. attribute:: wfile |
| 115 | |
| 116 | Contains the output stream for writing a response back to the |
| 117 | client. Proper adherence to the HTTP protocol must be used when writing to |
jugglinmike | a083c8e | 2017-05-24 14:25:50 -0400 | [diff] [blame] | 118 | this stream in order to achieve successful interoperation with HTTP |
| 119 | clients. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 120 | |
Martin Panter | 34eeed4 | 2016-06-29 10:12:22 +0000 | [diff] [blame] | 121 | .. versionchanged:: 3.6 |
| 122 | This is an :class:`io.BufferedIOBase` stream. |
| 123 | |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 124 | :class:`BaseHTTPRequestHandler` has the following attributes: |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 125 | |
| 126 | .. attribute:: server_version |
| 127 | |
| 128 | Specifies the server software version. You may want to override this. The |
| 129 | format is multiple whitespace-separated strings, where each string is of |
| 130 | the form name[/version]. For example, ``'BaseHTTP/0.2'``. |
| 131 | |
| 132 | .. attribute:: sys_version |
| 133 | |
| 134 | Contains the Python system version, in a form usable by the |
| 135 | :attr:`version_string` method and the :attr:`server_version` class |
| 136 | variable. For example, ``'Python/1.4'``. |
| 137 | |
| 138 | .. attribute:: error_message_format |
| 139 | |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 140 | Specifies a format string that should be used by :meth:`send_error` method |
| 141 | for building an error response to the client. The string is filled by |
| 142 | default with variables from :attr:`responses` based on the status code |
| 143 | that passed to :meth:`send_error`. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 144 | |
| 145 | .. attribute:: error_content_type |
| 146 | |
| 147 | Specifies the Content-Type HTTP header of error responses sent to the |
| 148 | client. The default value is ``'text/html'``. |
| 149 | |
| 150 | .. attribute:: protocol_version |
| 151 | |
| 152 | This specifies the HTTP protocol version used in responses. If set to |
| 153 | ``'HTTP/1.1'``, the server will permit HTTP persistent connections; |
| 154 | however, your server *must* then include an accurate ``Content-Length`` |
| 155 | header (using :meth:`send_header`) in all of its responses to clients. |
| 156 | For backwards compatibility, the setting defaults to ``'HTTP/1.0'``. |
| 157 | |
| 158 | .. attribute:: MessageClass |
| 159 | |
Georg Brandl | 83e9f4c | 2008-06-12 18:52:31 +0000 | [diff] [blame] | 160 | Specifies an :class:`email.message.Message`\ -like class to parse HTTP |
| 161 | headers. Typically, this is not overridden, and it defaults to |
| 162 | :class:`http.client.HTTPMessage`. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 163 | |
| 164 | .. attribute:: responses |
| 165 | |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 166 | This attribute contains a mapping of error code integers to two-element tuples |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 167 | containing a short and long message. For example, ``{code: (shortmessage, |
| 168 | longmessage)}``. The *shortmessage* is usually used as the *message* key in an |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 169 | error response, and *longmessage* as the *explain* key. It is used by |
| 170 | :meth:`send_response_only` and :meth:`send_error` methods. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 171 | |
| 172 | A :class:`BaseHTTPRequestHandler` instance has the following methods: |
| 173 | |
| 174 | .. method:: handle() |
| 175 | |
| 176 | Calls :meth:`handle_one_request` once (or, if persistent connections are |
| 177 | enabled, multiple times) to handle incoming HTTP requests. You should |
| 178 | never need to override it; instead, implement appropriate :meth:`do_\*` |
| 179 | methods. |
| 180 | |
| 181 | .. method:: handle_one_request() |
| 182 | |
| 183 | This method will parse and dispatch the request to the appropriate |
| 184 | :meth:`do_\*` method. You should never need to override it. |
| 185 | |
Senthil Kumaran | 0f476d4 | 2010-09-30 06:09:18 +0000 | [diff] [blame] | 186 | .. method:: handle_expect_100() |
| 187 | |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 188 | When a HTTP/1.1 compliant server receives an ``Expect: 100-continue`` |
Senthil Kumaran | 0f476d4 | 2010-09-30 06:09:18 +0000 | [diff] [blame] | 189 | request header it responds back with a ``100 Continue`` followed by ``200 |
| 190 | OK`` headers. |
| 191 | This method can be overridden to raise an error if the server does not |
| 192 | want the client to continue. For e.g. server can chose to send ``417 |
| 193 | Expectation Failed`` as a response header and ``return False``. |
| 194 | |
| 195 | .. versionadded:: 3.2 |
| 196 | |
Senthil Kumaran | 2688644 | 2013-03-15 07:53:21 -0700 | [diff] [blame] | 197 | .. method:: send_error(code, message=None, explain=None) |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 198 | |
| 199 | Sends and logs a complete error reply to the client. The numeric *code* |
R David Murray | a475a8d | 2014-01-03 13:03:00 -0500 | [diff] [blame] | 200 | specifies the HTTP error code, with *message* as an optional, short, human |
| 201 | readable description of the error. The *explain* argument can be used to |
| 202 | provide more detailed information about the error; it will be formatted |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 203 | using the :attr:`error_message_format` attribute and emitted, after |
R David Murray | a475a8d | 2014-01-03 13:03:00 -0500 | [diff] [blame] | 204 | a complete set of headers, as the response body. The :attr:`responses` |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 205 | attribute holds the default values for *message* and *explain* that |
R David Murray | a475a8d | 2014-01-03 13:03:00 -0500 | [diff] [blame] | 206 | will be used if no value is provided; for unknown codes the default value |
Martin Panter | e42e129 | 2016-06-08 08:29:13 +0000 | [diff] [blame] | 207 | for both is the string ``???``. The body will be empty if the method is |
| 208 | HEAD or the response code is one of the following: ``1xx``, |
| 209 | ``204 No Content``, ``205 Reset Content``, ``304 Not Modified``. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 210 | |
Senthil Kumaran | 52d2720 | 2012-10-10 23:16:21 -0700 | [diff] [blame] | 211 | .. versionchanged:: 3.4 |
| 212 | The error response includes a Content-Length header. |
Ezio Melotti | 2acd293 | 2013-03-16 22:23:30 +0200 | [diff] [blame] | 213 | Added the *explain* argument. |
Senthil Kumaran | 2688644 | 2013-03-15 07:53:21 -0700 | [diff] [blame] | 214 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 215 | .. method:: send_response(code, message=None) |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 216 | |
Senthil Kumaran | c7ae19b | 2011-05-09 23:25:02 +0800 | [diff] [blame] | 217 | Adds a response header to the headers buffer and logs the accepted |
Senthil Kumaran | cc99528 | 2011-05-11 16:04:28 +0800 | [diff] [blame] | 218 | request. The HTTP response line is written to the internal buffer, |
| 219 | followed by *Server* and *Date* headers. The values for these two headers |
| 220 | are picked up from the :meth:`version_string` and |
| 221 | :meth:`date_time_string` methods, respectively. If the server does not |
| 222 | intend to send any other headers using the :meth:`send_header` method, |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 223 | then :meth:`send_response` should be followed by an :meth:`end_headers` |
Ezio Melotti | e9c7d6c | 2011-05-12 01:10:57 +0300 | [diff] [blame] | 224 | call. |
Senthil Kumaran | cc99528 | 2011-05-11 16:04:28 +0800 | [diff] [blame] | 225 | |
Ezio Melotti | e9c7d6c | 2011-05-12 01:10:57 +0300 | [diff] [blame] | 226 | .. versionchanged:: 3.3 |
| 227 | Headers are stored to an internal buffer and :meth:`end_headers` |
| 228 | needs to be called explicitly. |
Senthil Kumaran | cc99528 | 2011-05-11 16:04:28 +0800 | [diff] [blame] | 229 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 230 | .. method:: send_header(keyword, value) |
| 231 | |
Senthil Kumaran | c7ae19b | 2011-05-09 23:25:02 +0800 | [diff] [blame] | 232 | Adds the HTTP header to an internal buffer which will be written to the |
Senthil Kumaran | 6ea17a8 | 2011-05-11 11:45:48 +0800 | [diff] [blame] | 233 | output stream when either :meth:`end_headers` or :meth:`flush_headers` is |
| 234 | invoked. *keyword* should specify the header keyword, with *value* |
| 235 | specifying its value. Note that, after the send_header calls are done, |
| 236 | :meth:`end_headers` MUST BE called in order to complete the operation. |
Senthil Kumaran | e4dad4f | 2010-11-21 14:36:14 +0000 | [diff] [blame] | 237 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 238 | .. versionchanged:: 3.2 |
| 239 | Headers are stored in an internal buffer. |
Senthil Kumaran | e4dad4f | 2010-11-21 14:36:14 +0000 | [diff] [blame] | 240 | |
Senthil Kumaran | 0f476d4 | 2010-09-30 06:09:18 +0000 | [diff] [blame] | 241 | .. method:: send_response_only(code, message=None) |
| 242 | |
Senthil Kumaran | b4760ef | 2015-06-14 17:35:37 -0700 | [diff] [blame] | 243 | Sends the response header only, used for the purposes when ``100 |
Senthil Kumaran | e4dad4f | 2010-11-21 14:36:14 +0000 | [diff] [blame] | 244 | Continue`` response is sent by the server to the client. The headers not |
| 245 | buffered and sent directly the output stream.If the *message* is not |
| 246 | specified, the HTTP message corresponding the response *code* is sent. |
Senthil Kumaran | 0f476d4 | 2010-09-30 06:09:18 +0000 | [diff] [blame] | 247 | |
| 248 | .. versionadded:: 3.2 |
| 249 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 250 | .. method:: end_headers() |
| 251 | |
Senthil Kumaran | c7ae19b | 2011-05-09 23:25:02 +0800 | [diff] [blame] | 252 | Adds a blank line |
| 253 | (indicating the end of the HTTP headers in the response) |
Ezio Melotti | e9c7d6c | 2011-05-12 01:10:57 +0300 | [diff] [blame] | 254 | to the headers buffer and calls :meth:`flush_headers()`. |
Senthil Kumaran | e4dad4f | 2010-11-21 14:36:14 +0000 | [diff] [blame] | 255 | |
Ezio Melotti | e9c7d6c | 2011-05-12 01:10:57 +0300 | [diff] [blame] | 256 | .. versionchanged:: 3.2 |
| 257 | The buffered headers are written to the output stream. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 258 | |
Senthil Kumaran | c7ae19b | 2011-05-09 23:25:02 +0800 | [diff] [blame] | 259 | .. method:: flush_headers() |
| 260 | |
| 261 | Finally send the headers to the output stream and flush the internal |
| 262 | headers buffer. |
| 263 | |
| 264 | .. versionadded:: 3.3 |
| 265 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 266 | .. method:: log_request(code='-', size='-') |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 267 | |
| 268 | Logs an accepted (successful) request. *code* should specify the numeric |
| 269 | HTTP code associated with the response. If a size of the response is |
| 270 | available, then it should be passed as the *size* parameter. |
| 271 | |
| 272 | .. method:: log_error(...) |
| 273 | |
| 274 | Logs an error when a request cannot be fulfilled. By default, it passes |
| 275 | the message to :meth:`log_message`, so it takes the same arguments |
| 276 | (*format* and additional values). |
| 277 | |
| 278 | |
| 279 | .. method:: log_message(format, ...) |
| 280 | |
| 281 | Logs an arbitrary message to ``sys.stderr``. This is typically overridden |
| 282 | to create custom error logging mechanisms. The *format* argument is a |
| 283 | standard printf-style format string, where the additional arguments to |
| 284 | :meth:`log_message` are applied as inputs to the formatting. The client |
Senthil Kumaran | db727b4 | 2012-04-29 13:41:03 +0800 | [diff] [blame] | 285 | ip address and current date and time are prefixed to every message logged. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 286 | |
| 287 | .. method:: version_string() |
| 288 | |
| 289 | Returns the server software's version string. This is a combination of the |
Berker Peksag | 0269828 | 2016-04-24 01:51:02 +0300 | [diff] [blame] | 290 | :attr:`server_version` and :attr:`sys_version` attributes. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 291 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 292 | .. method:: date_time_string(timestamp=None) |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 293 | |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 294 | Returns the date and time given by *timestamp* (which must be ``None`` or in |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 295 | the format returned by :func:`time.time`), formatted for a message |
| 296 | header. If *timestamp* is omitted, it uses the current date and time. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 297 | |
| 298 | The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``. |
| 299 | |
| 300 | .. method:: log_date_time_string() |
| 301 | |
| 302 | Returns the current date and time, formatted for logging. |
| 303 | |
| 304 | .. method:: address_string() |
| 305 | |
Senthil Kumaran | 1aacba4 | 2012-04-29 12:51:54 +0800 | [diff] [blame] | 306 | Returns the client address. |
| 307 | |
| 308 | .. versionchanged:: 3.3 |
| 309 | Previously, a name lookup was performed. To avoid name resolution |
| 310 | delays, it now always returns the IP address. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 311 | |
| 312 | |
Stéphane Wirtel | a17a2f5 | 2017-05-24 09:29:06 +0200 | [diff] [blame] | 313 | .. class:: SimpleHTTPRequestHandler(request, client_address, server, directory=None) |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 314 | |
| 315 | This class serves files from the current directory and below, directly |
| 316 | mapping the directory structure to HTTP requests. |
| 317 | |
| 318 | A lot of the work, such as parsing the request, is done by the base class |
| 319 | :class:`BaseHTTPRequestHandler`. This class implements the :func:`do_GET` |
| 320 | and :func:`do_HEAD` functions. |
| 321 | |
| 322 | The following are defined as class-level attributes of |
| 323 | :class:`SimpleHTTPRequestHandler`: |
| 324 | |
| 325 | .. attribute:: server_version |
| 326 | |
| 327 | This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is |
| 328 | defined at the module level. |
| 329 | |
| 330 | .. attribute:: extensions_map |
| 331 | |
| 332 | A dictionary mapping suffixes into MIME types. The default is |
| 333 | signified by an empty string, and is considered to be |
| 334 | ``application/octet-stream``. The mapping is used case-insensitively, |
| 335 | and so should contain only lower-cased keys. |
| 336 | |
Stéphane Wirtel | a17a2f5 | 2017-05-24 09:29:06 +0200 | [diff] [blame] | 337 | .. attribute:: directory |
| 338 | |
| 339 | If not specified, the directory to serve is the current working directory. |
| 340 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 341 | The :class:`SimpleHTTPRequestHandler` class defines the following methods: |
| 342 | |
| 343 | .. method:: do_HEAD() |
| 344 | |
| 345 | This method serves the ``'HEAD'`` request type: it sends the headers it |
| 346 | would send for the equivalent ``GET`` request. See the :meth:`do_GET` |
| 347 | method for a more complete explanation of the possible headers. |
| 348 | |
| 349 | .. method:: do_GET() |
| 350 | |
| 351 | The request is mapped to a local file by interpreting the request as a |
| 352 | path relative to the current working directory. |
| 353 | |
| 354 | If the request was mapped to a directory, the directory is checked for a |
| 355 | file named ``index.html`` or ``index.htm`` (in that order). If found, the |
| 356 | file's contents are returned; otherwise a directory listing is generated |
| 357 | by calling the :meth:`list_directory` method. This method uses |
| 358 | :func:`os.listdir` to scan the directory, and returns a ``404`` error |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 359 | response if the :func:`~os.listdir` fails. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 360 | |
Pierre Quentel | 351adda | 2017-04-02 12:26:12 +0200 | [diff] [blame] | 361 | If the request was mapped to a file, it is opened. Any :exc:`OSError` |
| 362 | exception in opening the requested file is mapped to a ``404``, |
| 363 | ``'File not found'`` error. If there was a ``'If-Modified-Since'`` |
| 364 | header in the request, and the file was not modified after this time, |
| 365 | a ``304``, ``'Not Modified'`` response is sent. Otherwise, the content |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 366 | type is guessed by calling the :meth:`guess_type` method, which in turn |
Pierre Quentel | 351adda | 2017-04-02 12:26:12 +0200 | [diff] [blame] | 367 | uses the *extensions_map* variable, and the file contents are returned. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 368 | |
| 369 | A ``'Content-type:'`` header with the guessed content type is output, |
| 370 | followed by a ``'Content-Length:'`` header with the file's size and a |
| 371 | ``'Last-Modified:'`` header with the file's modification time. |
| 372 | |
| 373 | Then follows a blank line signifying the end of the headers, and then the |
| 374 | contents of the file are output. If the file's MIME type starts with |
| 375 | ``text/`` the file is opened in text mode; otherwise binary mode is used. |
| 376 | |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 377 | For example usage, see the implementation of the :func:`test` function |
| 378 | invocation in the :mod:`http.server` module. |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 379 | |
Pierre Quentel | 351adda | 2017-04-02 12:26:12 +0200 | [diff] [blame] | 380 | .. versionchanged:: 3.7 |
| 381 | Support of the ``'If-Modified-Since'`` header. |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 382 | |
Georg Brandl | 8971f74 | 2010-07-02 07:41:51 +0000 | [diff] [blame] | 383 | The :class:`SimpleHTTPRequestHandler` class can be used in the following |
| 384 | manner in order to create a very basic webserver serving files relative to |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 385 | the current directory:: |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 386 | |
Georg Brandl | 8971f74 | 2010-07-02 07:41:51 +0000 | [diff] [blame] | 387 | import http.server |
| 388 | import socketserver |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 389 | |
Georg Brandl | 8971f74 | 2010-07-02 07:41:51 +0000 | [diff] [blame] | 390 | PORT = 8000 |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 391 | |
Georg Brandl | 8971f74 | 2010-07-02 07:41:51 +0000 | [diff] [blame] | 392 | Handler = http.server.SimpleHTTPRequestHandler |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 393 | |
Martin Panter | 0cab9c1 | 2016-04-13 00:36:52 +0000 | [diff] [blame] | 394 | with socketserver.TCPServer(("", PORT), Handler) as httpd: |
| 395 | print("serving at port", PORT) |
| 396 | httpd.serve_forever() |
Georg Brandl | 8971f74 | 2010-07-02 07:41:51 +0000 | [diff] [blame] | 397 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 398 | .. _http-server-cli: |
| 399 | |
Georg Brandl | f68798b | 2010-07-03 10:22:10 +0000 | [diff] [blame] | 400 | :mod:`http.server` can also be invoked directly using the :option:`-m` |
R David Murray | e7bade5 | 2012-04-11 20:13:25 -0400 | [diff] [blame] | 401 | switch of the interpreter with a ``port number`` argument. Similar to |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 402 | the previous example, this serves files relative to the current directory:: |
Senthil Kumaran | 97db43b | 2010-06-16 16:41:11 +0000 | [diff] [blame] | 403 | |
| 404 | python -m http.server 8000 |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 405 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 406 | By default, server binds itself to all interfaces. The option ``-b/--bind`` |
| 407 | specifies a specific address to which it should bind. For example, the |
| 408 | following command causes the server to bind to localhost only:: |
Senthil Kumaran | defe7f4 | 2013-09-15 09:37:27 -0700 | [diff] [blame] | 409 | |
| 410 | python -m http.server 8000 --bind 127.0.0.1 |
| 411 | |
| 412 | .. versionadded:: 3.4 |
| 413 | ``--bind`` argument was introduced. |
| 414 | |
Stéphane Wirtel | a17a2f5 | 2017-05-24 09:29:06 +0200 | [diff] [blame] | 415 | By default, server uses the current directory. The option ``-d/--directory`` |
| 416 | specifies a directory to which it should serve the files. For example, |
| 417 | the following command uses a specific directory:: |
| 418 | |
| 419 | python -m http.server --directory /tmp/ |
| 420 | |
| 421 | .. versionadded:: 3.7 |
| 422 | ``--directory`` specify alternate directory |
Georg Brandl | 8971f74 | 2010-07-02 07:41:51 +0000 | [diff] [blame] | 423 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 424 | .. class:: CGIHTTPRequestHandler(request, client_address, server) |
| 425 | |
| 426 | This class is used to serve either files or output of CGI scripts from the |
| 427 | current directory and below. Note that mapping HTTP hierarchic structure to |
| 428 | local directory structure is exactly as in :class:`SimpleHTTPRequestHandler`. |
| 429 | |
| 430 | .. note:: |
| 431 | |
| 432 | CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute |
| 433 | redirects (HTTP code 302), because code 200 (script output follows) is |
| 434 | sent prior to execution of the CGI script. This pre-empts the status |
| 435 | code. |
| 436 | |
| 437 | The class will however, run the CGI script, instead of serving it as a file, |
| 438 | if it guesses it to be a CGI script. Only directory-based CGI are used --- |
| 439 | the other common server configuration is to treat special extensions as |
| 440 | denoting CGI scripts. |
| 441 | |
| 442 | The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts |
| 443 | and serve the output, instead of serving files, if the request leads to |
| 444 | somewhere below the ``cgi_directories`` path. |
| 445 | |
| 446 | The :class:`CGIHTTPRequestHandler` defines the following data member: |
| 447 | |
| 448 | .. attribute:: cgi_directories |
| 449 | |
| 450 | This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to |
| 451 | treat as containing CGI scripts. |
| 452 | |
| 453 | The :class:`CGIHTTPRequestHandler` defines the following method: |
| 454 | |
| 455 | .. method:: do_POST() |
| 456 | |
| 457 | This method serves the ``'POST'`` request type, only allowed for CGI |
| 458 | scripts. Error 501, "Can only POST to CGI scripts", is output when trying |
| 459 | to POST to a non-CGI url. |
| 460 | |
| 461 | Note that CGI scripts will be run with UID of user nobody, for security |
| 462 | reasons. Problems with the CGI script will be translated to error 403. |
Senthil Kumaran | 1251faf | 2012-06-03 16:15:54 +0800 | [diff] [blame] | 463 | |
| 464 | :class:`CGIHTTPRequestHandler` can be enabled in the command line by passing |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 465 | the ``--cgi`` option:: |
Senthil Kumaran | 1251faf | 2012-06-03 16:15:54 +0800 | [diff] [blame] | 466 | |
| 467 | python -m http.server --cgi 8000 |