Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`wsgiref` --- WSGI Utilities and Reference Implementation |
| 2 | ============================================================== |
| 3 | |
| 4 | .. module:: wsgiref |
| 5 | :synopsis: WSGI Utilities and Reference Implementation. |
| 6 | .. moduleauthor:: Phillip J. Eby <pje@telecommunity.com> |
| 7 | .. sectionauthor:: Phillip J. Eby <pje@telecommunity.com> |
| 8 | |
| 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | The Web Server Gateway Interface (WSGI) is a standard interface between web |
| 11 | server software and web applications written in Python. Having a standard |
| 12 | interface makes it easy to use an application that supports WSGI with a number |
| 13 | of different web servers. |
| 14 | |
| 15 | Only authors of web servers and programming frameworks need to know every detail |
| 16 | and corner case of the WSGI design. You don't need to understand every detail |
| 17 | of WSGI just to install a WSGI application or to write a web application using |
| 18 | an existing framework. |
| 19 | |
| 20 | :mod:`wsgiref` is a reference implementation of the WSGI specification that can |
| 21 | be used to add WSGI support to a web server or framework. It provides utilities |
| 22 | for manipulating WSGI environment variables and response headers, base classes |
| 23 | for implementing WSGI servers, a demo HTTP server that serves WSGI applications, |
| 24 | and a validation tool that checks WSGI servers and applications for conformance |
| 25 | to the WSGI specification (:pep:`333`). |
| 26 | |
| 27 | See http://www.wsgi.org for more information about WSGI, and links to tutorials |
| 28 | and other resources. |
| 29 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 30 | .. XXX If you're just trying to write a web application... |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | |
| 32 | |
| 33 | :mod:`wsgiref.util` -- WSGI environment utilities |
| 34 | ------------------------------------------------- |
| 35 | |
| 36 | .. module:: wsgiref.util |
| 37 | :synopsis: WSGI environment utilities. |
| 38 | |
| 39 | |
| 40 | This module provides a variety of utility functions for working with WSGI |
| 41 | environments. A WSGI environment is a dictionary containing HTTP request |
| 42 | variables as described in :pep:`333`. All of the functions taking an *environ* |
| 43 | parameter expect a WSGI-compliant dictionary to be supplied; please see |
| 44 | :pep:`333` for a detailed specification. |
| 45 | |
| 46 | |
| 47 | .. function:: guess_scheme(environ) |
| 48 | |
| 49 | Return a guess for whether ``wsgi.url_scheme`` should be "http" or "https", by |
| 50 | checking for a ``HTTPS`` environment variable in the *environ* dictionary. The |
| 51 | return value is a string. |
| 52 | |
| 53 | This function is useful when creating a gateway that wraps CGI or a CGI-like |
| 54 | protocol such as FastCGI. Typically, servers providing such protocols will |
| 55 | include a ``HTTPS`` variable with a value of "1" "yes", or "on" when a request |
| 56 | is received via SSL. So, this function returns "https" if such a value is |
| 57 | found, and "http" otherwise. |
| 58 | |
| 59 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 60 | .. function:: request_uri(environ, include_query=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
| 62 | Return the full request URI, optionally including the query string, using the |
| 63 | algorithm found in the "URL Reconstruction" section of :pep:`333`. If |
| 64 | *include_query* is false, the query string is not included in the resulting URI. |
| 65 | |
| 66 | |
| 67 | .. function:: application_uri(environ) |
| 68 | |
| 69 | Similar to :func:`request_uri`, except that the ``PATH_INFO`` and |
| 70 | ``QUERY_STRING`` variables are ignored. The result is the base URI of the |
| 71 | application object addressed by the request. |
| 72 | |
| 73 | |
| 74 | .. function:: shift_path_info(environ) |
| 75 | |
| 76 | Shift a single name from ``PATH_INFO`` to ``SCRIPT_NAME`` and return the name. |
| 77 | The *environ* dictionary is *modified* in-place; use a copy if you need to keep |
| 78 | the original ``PATH_INFO`` or ``SCRIPT_NAME`` intact. |
| 79 | |
| 80 | If there are no remaining path segments in ``PATH_INFO``, ``None`` is returned. |
| 81 | |
| 82 | Typically, this routine is used to process each portion of a request URI path, |
| 83 | for example to treat the path as a series of dictionary keys. This routine |
| 84 | modifies the passed-in environment to make it suitable for invoking another WSGI |
| 85 | application that is located at the target URI. For example, if there is a WSGI |
| 86 | application at ``/foo``, and the request URI path is ``/foo/bar/baz``, and the |
| 87 | WSGI application at ``/foo`` calls :func:`shift_path_info`, it will receive the |
| 88 | string "bar", and the environment will be updated to be suitable for passing to |
| 89 | a WSGI application at ``/foo/bar``. That is, ``SCRIPT_NAME`` will change from |
| 90 | ``/foo`` to ``/foo/bar``, and ``PATH_INFO`` will change from ``/bar/baz`` to |
| 91 | ``/baz``. |
| 92 | |
| 93 | When ``PATH_INFO`` is just a "/", this routine returns an empty string and |
| 94 | appends a trailing slash to ``SCRIPT_NAME``, even though empty path segments are |
| 95 | normally ignored, and ``SCRIPT_NAME`` doesn't normally end in a slash. This is |
| 96 | intentional behavior, to ensure that an application can tell the difference |
| 97 | between URIs ending in ``/x`` from ones ending in ``/x/`` when using this |
| 98 | routine to do object traversal. |
| 99 | |
| 100 | |
| 101 | .. function:: setup_testing_defaults(environ) |
| 102 | |
| 103 | Update *environ* with trivial defaults for testing purposes. |
| 104 | |
| 105 | This routine adds various parameters required for WSGI, including ``HTTP_HOST``, |
| 106 | ``SERVER_NAME``, ``SERVER_PORT``, ``REQUEST_METHOD``, ``SCRIPT_NAME``, |
| 107 | ``PATH_INFO``, and all of the :pep:`333`\ -defined ``wsgi.*`` variables. It |
| 108 | only supplies default values, and does not replace any existing settings for |
| 109 | these variables. |
| 110 | |
| 111 | This routine is intended to make it easier for unit tests of WSGI servers and |
| 112 | applications to set up dummy environments. It should NOT be used by actual WSGI |
| 113 | servers or applications, since the data is fake! |
| 114 | |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 115 | Example usage:: |
| 116 | |
| 117 | from wsgiref.util import setup_testing_defaults |
| 118 | from wsgiref.simple_server import make_server |
| 119 | |
| 120 | # A relatively simple WSGI application. It's going to print out the |
| 121 | # environment dictionary after being updated by setup_testing_defaults |
| 122 | def simple_app(environ, start_response): |
| 123 | setup_testing_defaults(environ) |
| 124 | |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 125 | status = b'200 OK' |
| 126 | headers = [(b'Content-type', b'text/plain; charset=utf-8')] |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 127 | |
| 128 | start_response(status, headers) |
| 129 | |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 130 | ret = [("%s: %s\n" % (key, value)).encode("utf-8") |
| 131 | for key, value in environ.items()] |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 132 | return ret |
| 133 | |
| 134 | httpd = make_server('', 8000, simple_app) |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 135 | print("Serving on port 8000...") |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 136 | httpd.serve_forever() |
| 137 | |
| 138 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | In addition to the environment functions above, the :mod:`wsgiref.util` module |
| 140 | also provides these miscellaneous utilities: |
| 141 | |
| 142 | |
| 143 | .. function:: is_hop_by_hop(header_name) |
| 144 | |
| 145 | Return true if 'header_name' is an HTTP/1.1 "Hop-by-Hop" header, as defined by |
| 146 | :rfc:`2616`. |
| 147 | |
| 148 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 149 | .. class:: FileWrapper(filelike, blksize=8192) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 151 | A wrapper to convert a file-like object to an :term:`iterator`. The resulting objects |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for |
| 153 | compatibility with Python 2.1 and Jython. As the object is iterated over, the |
| 154 | optional *blksize* parameter will be repeatedly passed to the *filelike* |
| 155 | object's :meth:`read` method to obtain strings to yield. When :meth:`read` |
| 156 | returns an empty string, iteration is ended and is not resumable. |
| 157 | |
| 158 | If *filelike* has a :meth:`close` method, the returned object will also have a |
| 159 | :meth:`close` method, and it will invoke the *filelike* object's :meth:`close` |
| 160 | method when called. |
| 161 | |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 162 | Example usage:: |
| 163 | |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 164 | from io import StringIO |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 165 | from wsgiref.util import FileWrapper |
| 166 | |
| 167 | # We're using a StringIO-buffer for as the file-like object |
| 168 | filelike = StringIO("This is an example file-like object"*10) |
| 169 | wrapper = FileWrapper(filelike, blksize=5) |
| 170 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 171 | for chunk in wrapper: |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 172 | print(chunk) |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 173 | |
| 174 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | |
| 176 | :mod:`wsgiref.headers` -- WSGI response header tools |
| 177 | ---------------------------------------------------- |
| 178 | |
| 179 | .. module:: wsgiref.headers |
| 180 | :synopsis: WSGI response header tools. |
| 181 | |
| 182 | |
| 183 | This module provides a single class, :class:`Headers`, for convenient |
| 184 | manipulation of WSGI response headers using a mapping-like interface. |
| 185 | |
| 186 | |
| 187 | .. class:: Headers(headers) |
| 188 | |
| 189 | Create a mapping-like object wrapping *headers*, which must be a list of header |
| 190 | name/value tuples as described in :pep:`333`. Any changes made to the new |
| 191 | :class:`Headers` object will directly update the *headers* list it was created |
| 192 | with. |
| 193 | |
| 194 | :class:`Headers` objects support typical mapping operations including |
| 195 | :meth:`__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`, |
Collin Winter | f6b8121 | 2007-09-10 00:03:41 +0000 | [diff] [blame] | 196 | :meth:`__delitem__` and :meth:`__contains__`. For each of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 197 | these methods, the key is the header name (treated case-insensitively), and the |
| 198 | value is the first value associated with that header name. Setting a header |
| 199 | deletes any existing values for that header, then adds a new value at the end of |
| 200 | the wrapped header list. Headers' existing order is generally maintained, with |
| 201 | new headers added to the end of the wrapped list. |
| 202 | |
| 203 | Unlike a dictionary, :class:`Headers` objects do not raise an error when you try |
| 204 | to get or delete a key that isn't in the wrapped header list. Getting a |
| 205 | nonexistent header just returns ``None``, and deleting a nonexistent header does |
| 206 | nothing. |
| 207 | |
| 208 | :class:`Headers` objects also support :meth:`keys`, :meth:`values`, and |
| 209 | :meth:`items` methods. The lists returned by :meth:`keys` and :meth:`items` can |
| 210 | include the same key more than once if there is a multi-valued header. The |
| 211 | ``len()`` of a :class:`Headers` object is the same as the length of its |
| 212 | :meth:`items`, which is the same as the length of the wrapped header list. In |
| 213 | fact, the :meth:`items` method just returns a copy of the wrapped header list. |
| 214 | |
| 215 | Calling ``str()`` on a :class:`Headers` object returns a formatted string |
| 216 | suitable for transmission as HTTP response headers. Each header is placed on a |
| 217 | line with its value, separated by a colon and a space. Each line is terminated |
| 218 | by a carriage return and line feed, and the string is terminated with a blank |
| 219 | line. |
| 220 | |
| 221 | In addition to their mapping interface and formatting features, :class:`Headers` |
| 222 | objects also have the following methods for querying and adding multi-valued |
| 223 | headers, and for adding headers with MIME parameters: |
| 224 | |
| 225 | |
| 226 | .. method:: Headers.get_all(name) |
| 227 | |
| 228 | Return a list of all the values for the named header. |
| 229 | |
| 230 | The returned list will be sorted in the order they appeared in the original |
| 231 | header list or were added to this instance, and may contain duplicates. Any |
| 232 | fields deleted and re-inserted are always appended to the header list. If no |
| 233 | fields exist with the given name, returns an empty list. |
| 234 | |
| 235 | |
| 236 | .. method:: Headers.add_header(name, value, **_params) |
| 237 | |
| 238 | Add a (possibly multi-valued) header, with optional MIME parameters specified |
| 239 | via keyword arguments. |
| 240 | |
| 241 | *name* is the header field to add. Keyword arguments can be used to set MIME |
| 242 | parameters for the header field. Each parameter must be a string or ``None``. |
| 243 | Underscores in parameter names are converted to dashes, since dashes are illegal |
| 244 | in Python identifiers, but many MIME parameter names include dashes. If the |
| 245 | parameter value is a string, it is added to the header value parameters in the |
| 246 | form ``name="value"``. If it is ``None``, only the parameter name is added. |
| 247 | (This is used for MIME parameters without a value.) Example usage:: |
| 248 | |
| 249 | h.add_header('content-disposition', 'attachment', filename='bud.gif') |
| 250 | |
| 251 | The above will add a header that looks like this:: |
| 252 | |
| 253 | Content-Disposition: attachment; filename="bud.gif" |
| 254 | |
| 255 | |
| 256 | :mod:`wsgiref.simple_server` -- a simple WSGI HTTP server |
| 257 | --------------------------------------------------------- |
| 258 | |
| 259 | .. module:: wsgiref.simple_server |
| 260 | :synopsis: A simple WSGI HTTP server. |
| 261 | |
| 262 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 263 | This module implements a simple HTTP server (based on :mod:`http.server`) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | that serves WSGI applications. Each server instance serves a single WSGI |
| 265 | application on a given host and port. If you want to serve multiple |
| 266 | applications on a single host and port, you should create a WSGI application |
| 267 | that parses ``PATH_INFO`` to select which application to invoke for each |
| 268 | request. (E.g., using the :func:`shift_path_info` function from |
| 269 | :mod:`wsgiref.util`.) |
| 270 | |
| 271 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 272 | .. function:: make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 273 | |
| 274 | Create a new WSGI server listening on *host* and *port*, accepting connections |
| 275 | for *app*. The return value is an instance of the supplied *server_class*, and |
| 276 | will process requests using the specified *handler_class*. *app* must be a WSGI |
| 277 | application object, as defined by :pep:`333`. |
| 278 | |
| 279 | Example usage:: |
| 280 | |
| 281 | from wsgiref.simple_server import make_server, demo_app |
| 282 | |
| 283 | httpd = make_server('', 8000, demo_app) |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 284 | print("Serving HTTP on port 8000...") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
| 286 | # Respond to requests until process is killed |
| 287 | httpd.serve_forever() |
| 288 | |
| 289 | # Alternative: serve one request, then exit |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 290 | httpd.handle_request() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 291 | |
| 292 | |
| 293 | .. function:: demo_app(environ, start_response) |
| 294 | |
| 295 | This function is a small but complete WSGI application that returns a text page |
| 296 | containing the message "Hello world!" and a list of the key/value pairs provided |
| 297 | in the *environ* parameter. It's useful for verifying that a WSGI server (such |
| 298 | as :mod:`wsgiref.simple_server`) is able to run a simple WSGI application |
| 299 | correctly. |
| 300 | |
| 301 | |
| 302 | .. class:: WSGIServer(server_address, RequestHandlerClass) |
| 303 | |
| 304 | Create a :class:`WSGIServer` instance. *server_address* should be a |
| 305 | ``(host,port)`` tuple, and *RequestHandlerClass* should be the subclass of |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 306 | :class:`http.server.BaseHTTPRequestHandler` that will be used to process |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 307 | requests. |
| 308 | |
| 309 | You do not normally need to call this constructor, as the :func:`make_server` |
| 310 | function can handle all the details for you. |
| 311 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 312 | :class:`WSGIServer` is a subclass of :class:`http.server.HTTPServer`, so all |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 313 | of its methods (such as :meth:`serve_forever` and :meth:`handle_request`) are |
| 314 | available. :class:`WSGIServer` also provides these WSGI-specific methods: |
| 315 | |
| 316 | |
| 317 | .. method:: WSGIServer.set_app(application) |
| 318 | |
| 319 | Sets the callable *application* as the WSGI application that will receive |
| 320 | requests. |
| 321 | |
| 322 | |
| 323 | .. method:: WSGIServer.get_app() |
| 324 | |
| 325 | Returns the currently-set application callable. |
| 326 | |
| 327 | Normally, however, you do not need to use these additional methods, as |
| 328 | :meth:`set_app` is normally called by :func:`make_server`, and the |
| 329 | :meth:`get_app` exists mainly for the benefit of request handler instances. |
| 330 | |
| 331 | |
| 332 | .. class:: WSGIRequestHandler(request, client_address, server) |
| 333 | |
| 334 | Create an HTTP handler for the given *request* (i.e. a socket), *client_address* |
| 335 | (a ``(host,port)`` tuple), and *server* (:class:`WSGIServer` instance). |
| 336 | |
| 337 | You do not need to create instances of this class directly; they are |
| 338 | automatically created as needed by :class:`WSGIServer` objects. You can, |
| 339 | however, subclass this class and supply it as a *handler_class* to the |
| 340 | :func:`make_server` function. Some possibly relevant methods for overriding in |
| 341 | subclasses: |
| 342 | |
| 343 | |
| 344 | .. method:: WSGIRequestHandler.get_environ() |
| 345 | |
| 346 | Returns a dictionary containing the WSGI environment for a request. The default |
| 347 | implementation copies the contents of the :class:`WSGIServer` object's |
| 348 | :attr:`base_environ` dictionary attribute and then adds various headers derived |
| 349 | from the HTTP request. Each call to this method should return a new dictionary |
| 350 | containing all of the relevant CGI environment variables as specified in |
| 351 | :pep:`333`. |
| 352 | |
| 353 | |
| 354 | .. method:: WSGIRequestHandler.get_stderr() |
| 355 | |
| 356 | Return the object that should be used as the ``wsgi.errors`` stream. The default |
| 357 | implementation just returns ``sys.stderr``. |
| 358 | |
| 359 | |
| 360 | .. method:: WSGIRequestHandler.handle() |
| 361 | |
| 362 | Process the HTTP request. The default implementation creates a handler instance |
| 363 | using a :mod:`wsgiref.handlers` class to implement the actual WSGI application |
| 364 | interface. |
| 365 | |
| 366 | |
| 367 | :mod:`wsgiref.validate` --- WSGI conformance checker |
| 368 | ---------------------------------------------------- |
| 369 | |
| 370 | .. module:: wsgiref.validate |
| 371 | :synopsis: WSGI conformance checker. |
| 372 | |
| 373 | |
| 374 | When creating new WSGI application objects, frameworks, servers, or middleware, |
| 375 | it can be useful to validate the new code's conformance using |
| 376 | :mod:`wsgiref.validate`. This module provides a function that creates WSGI |
| 377 | application objects that validate communications between a WSGI server or |
| 378 | gateway and a WSGI application object, to check both sides for protocol |
| 379 | conformance. |
| 380 | |
| 381 | Note that this utility does not guarantee complete :pep:`333` compliance; an |
| 382 | absence of errors from this module does not necessarily mean that errors do not |
| 383 | exist. However, if this module does produce an error, then it is virtually |
| 384 | certain that either the server or application is not 100% compliant. |
| 385 | |
| 386 | This module is based on the :mod:`paste.lint` module from Ian Bicking's "Python |
| 387 | Paste" library. |
| 388 | |
| 389 | |
| 390 | .. function:: validator(application) |
| 391 | |
| 392 | Wrap *application* and return a new WSGI application object. The returned |
| 393 | application will forward all requests to the original *application*, and will |
| 394 | check that both the *application* and the server invoking it are conforming to |
| 395 | the WSGI specification and to RFC 2616. |
| 396 | |
| 397 | Any detected nonconformance results in an :exc:`AssertionError` being raised; |
| 398 | note, however, that how these errors are handled is server-dependent. For |
| 399 | example, :mod:`wsgiref.simple_server` and other servers based on |
| 400 | :mod:`wsgiref.handlers` (that don't override the error handling methods to do |
| 401 | something else) will simply output a message that an error has occurred, and |
| 402 | dump the traceback to ``sys.stderr`` or some other error stream. |
| 403 | |
| 404 | This wrapper may also generate output using the :mod:`warnings` module to |
| 405 | indicate behaviors that are questionable but which may not actually be |
| 406 | prohibited by :pep:`333`. Unless they are suppressed using Python command-line |
| 407 | options or the :mod:`warnings` API, any such warnings will be written to |
| 408 | ``sys.stderr`` (*not* ``wsgi.errors``, unless they happen to be the same |
| 409 | object). |
| 410 | |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 411 | Example usage:: |
| 412 | |
| 413 | from wsgiref.validate import validator |
| 414 | from wsgiref.simple_server import make_server |
| 415 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 416 | # Our callable object which is intentionally not compliant to the |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 417 | # standard, so the validator is going to break |
| 418 | def simple_app(environ, start_response): |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 419 | status = b'200 OK' # HTTP Status |
| 420 | headers = [(b'Content-type', b'text/plain')] # HTTP Headers |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 421 | start_response(status, headers) |
| 422 | |
| 423 | # This is going to break because we need to return a list, and |
| 424 | # the validator is going to inform us |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 425 | return b"Hello World" |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 426 | |
| 427 | # This is the application wrapped in a validator |
| 428 | validator_app = validator(simple_app) |
| 429 | |
| 430 | httpd = make_server('', 8000, validator_app) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 431 | print("Listening on port 8000....") |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 432 | httpd.serve_forever() |
| 433 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 434 | |
| 435 | :mod:`wsgiref.handlers` -- server/gateway base classes |
| 436 | ------------------------------------------------------ |
| 437 | |
| 438 | .. module:: wsgiref.handlers |
| 439 | :synopsis: WSGI server/gateway base classes. |
| 440 | |
| 441 | |
| 442 | This module provides base handler classes for implementing WSGI servers and |
| 443 | gateways. These base classes handle most of the work of communicating with a |
| 444 | WSGI application, as long as they are given a CGI-like environment, along with |
| 445 | input, output, and error streams. |
| 446 | |
| 447 | |
| 448 | .. class:: CGIHandler() |
| 449 | |
| 450 | CGI-based invocation via ``sys.stdin``, ``sys.stdout``, ``sys.stderr`` and |
| 451 | ``os.environ``. This is useful when you have a WSGI application and want to run |
| 452 | it as a CGI script. Simply invoke ``CGIHandler().run(app)``, where ``app`` is |
| 453 | the WSGI application object you wish to invoke. |
| 454 | |
| 455 | This class is a subclass of :class:`BaseCGIHandler` that sets ``wsgi.run_once`` |
| 456 | to true, ``wsgi.multithread`` to false, and ``wsgi.multiprocess`` to true, and |
| 457 | always uses :mod:`sys` and :mod:`os` to obtain the necessary CGI streams and |
| 458 | environment. |
| 459 | |
| 460 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 461 | .. class:: BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 462 | |
| 463 | Similar to :class:`CGIHandler`, but instead of using the :mod:`sys` and |
| 464 | :mod:`os` modules, the CGI environment and I/O streams are specified explicitly. |
| 465 | The *multithread* and *multiprocess* values are used to set the |
| 466 | ``wsgi.multithread`` and ``wsgi.multiprocess`` flags for any applications run by |
| 467 | the handler instance. |
| 468 | |
| 469 | This class is a subclass of :class:`SimpleHandler` intended for use with |
| 470 | software other than HTTP "origin servers". If you are writing a gateway |
| 471 | protocol implementation (such as CGI, FastCGI, SCGI, etc.) that uses a |
| 472 | ``Status:`` header to send an HTTP status, you probably want to subclass this |
| 473 | instead of :class:`SimpleHandler`. |
| 474 | |
| 475 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 476 | .. class:: SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 477 | |
| 478 | Similar to :class:`BaseCGIHandler`, but designed for use with HTTP origin |
| 479 | servers. If you are writing an HTTP server implementation, you will probably |
| 480 | want to subclass this instead of :class:`BaseCGIHandler` |
| 481 | |
| 482 | This class is a subclass of :class:`BaseHandler`. It overrides the |
| 483 | :meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`, |
| 484 | :meth:`_write`, and :meth:`_flush` methods to support explicitly setting the |
| 485 | environment and streams via the constructor. The supplied environment and |
| 486 | streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and |
| 487 | :attr:`environ` attributes. |
| 488 | |
| 489 | |
| 490 | .. class:: BaseHandler() |
| 491 | |
| 492 | This is an abstract base class for running WSGI applications. Each instance |
| 493 | will handle a single HTTP request, although in principle you could create a |
| 494 | subclass that was reusable for multiple requests. |
| 495 | |
| 496 | :class:`BaseHandler` instances have only one method intended for external use: |
| 497 | |
| 498 | |
| 499 | .. method:: BaseHandler.run(app) |
| 500 | |
| 501 | Run the specified WSGI application, *app*. |
| 502 | |
| 503 | All of the other :class:`BaseHandler` methods are invoked by this method in the |
| 504 | process of running the application, and thus exist primarily to allow |
| 505 | customizing the process. |
| 506 | |
| 507 | The following methods MUST be overridden in a subclass: |
| 508 | |
| 509 | |
| 510 | .. method:: BaseHandler._write(data) |
| 511 | |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 512 | Buffer the bytes *data* for transmission to the client. It's okay if this |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 513 | method actually transmits the data; :class:`BaseHandler` just separates write |
| 514 | and flush operations for greater efficiency when the underlying system actually |
| 515 | has such a distinction. |
| 516 | |
| 517 | |
| 518 | .. method:: BaseHandler._flush() |
| 519 | |
| 520 | Force buffered data to be transmitted to the client. It's okay if this method |
| 521 | is a no-op (i.e., if :meth:`_write` actually sends the data). |
| 522 | |
| 523 | |
| 524 | .. method:: BaseHandler.get_stdin() |
| 525 | |
| 526 | Return an input stream object suitable for use as the ``wsgi.input`` of the |
| 527 | request currently being processed. |
| 528 | |
| 529 | |
| 530 | .. method:: BaseHandler.get_stderr() |
| 531 | |
| 532 | Return an output stream object suitable for use as the ``wsgi.errors`` of the |
| 533 | request currently being processed. |
| 534 | |
| 535 | |
| 536 | .. method:: BaseHandler.add_cgi_vars() |
| 537 | |
| 538 | Insert CGI variables for the current request into the :attr:`environ` attribute. |
| 539 | |
| 540 | Here are some other methods and attributes you may wish to override. This list |
| 541 | is only a summary, however, and does not include every method that can be |
| 542 | overridden. You should consult the docstrings and source code for additional |
| 543 | information before attempting to create a customized :class:`BaseHandler` |
| 544 | subclass. |
| 545 | |
| 546 | Attributes and methods for customizing the WSGI environment: |
| 547 | |
| 548 | |
| 549 | .. attribute:: BaseHandler.wsgi_multithread |
| 550 | |
| 551 | The value to be used for the ``wsgi.multithread`` environment variable. It |
| 552 | defaults to true in :class:`BaseHandler`, but may have a different default (or |
| 553 | be set by the constructor) in the other subclasses. |
| 554 | |
| 555 | |
| 556 | .. attribute:: BaseHandler.wsgi_multiprocess |
| 557 | |
| 558 | The value to be used for the ``wsgi.multiprocess`` environment variable. It |
| 559 | defaults to true in :class:`BaseHandler`, but may have a different default (or |
| 560 | be set by the constructor) in the other subclasses. |
| 561 | |
| 562 | |
| 563 | .. attribute:: BaseHandler.wsgi_run_once |
| 564 | |
| 565 | The value to be used for the ``wsgi.run_once`` environment variable. It |
| 566 | defaults to false in :class:`BaseHandler`, but :class:`CGIHandler` sets it to |
| 567 | true by default. |
| 568 | |
| 569 | |
| 570 | .. attribute:: BaseHandler.os_environ |
| 571 | |
| 572 | The default environment variables to be included in every request's WSGI |
| 573 | environment. By default, this is a copy of ``os.environ`` at the time that |
| 574 | :mod:`wsgiref.handlers` was imported, but subclasses can either create their own |
| 575 | at the class or instance level. Note that the dictionary should be considered |
| 576 | read-only, since the default value is shared between multiple classes and |
| 577 | instances. |
| 578 | |
| 579 | |
| 580 | .. attribute:: BaseHandler.server_software |
| 581 | |
| 582 | If the :attr:`origin_server` attribute is set, this attribute's value is used to |
| 583 | set the default ``SERVER_SOFTWARE`` WSGI environment variable, and also to set a |
| 584 | default ``Server:`` header in HTTP responses. It is ignored for handlers (such |
| 585 | as :class:`BaseCGIHandler` and :class:`CGIHandler`) that are not HTTP origin |
| 586 | servers. |
| 587 | |
| 588 | |
| 589 | .. method:: BaseHandler.get_scheme() |
| 590 | |
| 591 | Return the URL scheme being used for the current request. The default |
| 592 | implementation uses the :func:`guess_scheme` function from :mod:`wsgiref.util` |
| 593 | to guess whether the scheme should be "http" or "https", based on the current |
| 594 | request's :attr:`environ` variables. |
| 595 | |
| 596 | |
| 597 | .. method:: BaseHandler.setup_environ() |
| 598 | |
| 599 | Set the :attr:`environ` attribute to a fully-populated WSGI environment. The |
| 600 | default implementation uses all of the above methods and attributes, plus the |
| 601 | :meth:`get_stdin`, :meth:`get_stderr`, and :meth:`add_cgi_vars` methods and the |
| 602 | :attr:`wsgi_file_wrapper` attribute. It also inserts a ``SERVER_SOFTWARE`` key |
| 603 | if not present, as long as the :attr:`origin_server` attribute is a true value |
| 604 | and the :attr:`server_software` attribute is set. |
| 605 | |
| 606 | Methods and attributes for customizing exception handling: |
| 607 | |
| 608 | |
| 609 | .. method:: BaseHandler.log_exception(exc_info) |
| 610 | |
| 611 | Log the *exc_info* tuple in the server log. *exc_info* is a ``(type, value, |
| 612 | traceback)`` tuple. The default implementation simply writes the traceback to |
| 613 | the request's ``wsgi.errors`` stream and flushes it. Subclasses can override |
| 614 | this method to change the format or retarget the output, mail the traceback to |
| 615 | an administrator, or whatever other action may be deemed suitable. |
| 616 | |
| 617 | |
| 618 | .. attribute:: BaseHandler.traceback_limit |
| 619 | |
| 620 | The maximum number of frames to include in tracebacks output by the default |
| 621 | :meth:`log_exception` method. If ``None``, all frames are included. |
| 622 | |
| 623 | |
| 624 | .. method:: BaseHandler.error_output(environ, start_response) |
| 625 | |
| 626 | This method is a WSGI application to generate an error page for the user. It is |
| 627 | only invoked if an error occurs before headers are sent to the client. |
| 628 | |
| 629 | This method can access the current error information using ``sys.exc_info()``, |
| 630 | and should pass that information to *start_response* when calling it (as |
| 631 | described in the "Error Handling" section of :pep:`333`). |
| 632 | |
| 633 | The default implementation just uses the :attr:`error_status`, |
| 634 | :attr:`error_headers`, and :attr:`error_body` attributes to generate an output |
| 635 | page. Subclasses can override this to produce more dynamic error output. |
| 636 | |
| 637 | Note, however, that it's not recommended from a security perspective to spit out |
| 638 | diagnostics to any old user; ideally, you should have to do something special to |
| 639 | enable diagnostic output, which is why the default implementation doesn't |
| 640 | include any. |
| 641 | |
| 642 | |
| 643 | .. attribute:: BaseHandler.error_status |
| 644 | |
| 645 | The HTTP status used for error responses. This should be a status string as |
| 646 | defined in :pep:`333`; it defaults to a 500 code and message. |
| 647 | |
| 648 | |
| 649 | .. attribute:: BaseHandler.error_headers |
| 650 | |
| 651 | The HTTP headers used for error responses. This should be a list of WSGI |
| 652 | response headers (``(name, value)`` tuples), as described in :pep:`333`. The |
| 653 | default list just sets the content type to ``text/plain``. |
| 654 | |
| 655 | |
| 656 | .. attribute:: BaseHandler.error_body |
| 657 | |
| 658 | The error response body. This should be an HTTP response body string. It |
| 659 | defaults to the plain text, "A server error occurred. Please contact the |
| 660 | administrator." |
| 661 | |
| 662 | Methods and attributes for :pep:`333`'s "Optional Platform-Specific File |
| 663 | Handling" feature: |
| 664 | |
| 665 | |
| 666 | .. attribute:: BaseHandler.wsgi_file_wrapper |
| 667 | |
| 668 | A ``wsgi.file_wrapper`` factory, or ``None``. The default value of this |
| 669 | attribute is the :class:`FileWrapper` class from :mod:`wsgiref.util`. |
| 670 | |
| 671 | |
| 672 | .. method:: BaseHandler.sendfile() |
| 673 | |
| 674 | Override to implement platform-specific file transmission. This method is |
| 675 | called only if the application's return value is an instance of the class |
| 676 | specified by the :attr:`wsgi_file_wrapper` attribute. It should return a true |
| 677 | value if it was able to successfully transmit the file, so that the default |
| 678 | transmission code will not be executed. The default implementation of this |
| 679 | method just returns a false value. |
| 680 | |
| 681 | Miscellaneous methods and attributes: |
| 682 | |
| 683 | |
| 684 | .. attribute:: BaseHandler.origin_server |
| 685 | |
| 686 | This attribute should be set to a true value if the handler's :meth:`_write` and |
| 687 | :meth:`_flush` are being used to communicate directly to the client, rather than |
| 688 | via a CGI-like gateway protocol that wants the HTTP status in a special |
| 689 | ``Status:`` header. |
| 690 | |
| 691 | This attribute's default value is true in :class:`BaseHandler`, but false in |
| 692 | :class:`BaseCGIHandler` and :class:`CGIHandler`. |
| 693 | |
| 694 | |
| 695 | .. attribute:: BaseHandler.http_version |
| 696 | |
| 697 | If :attr:`origin_server` is true, this string attribute is used to set the HTTP |
| 698 | version of the response set to the client. It defaults to ``"1.0"``. |
| 699 | |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 700 | |
| 701 | Examples |
| 702 | -------- |
| 703 | |
| 704 | This is a working "Hello World" WSGI application:: |
| 705 | |
| 706 | from wsgiref.simple_server import make_server |
| 707 | |
| 708 | # Every WSGI application must have an application object - a callable |
| 709 | # object that accepts two arguments. For that purpose, we're going to |
| 710 | # use a function (note that you're not limited to a function, you can |
| 711 | # use a class for example). The first argument passed to the function |
| 712 | # is a dictionary containing CGI-style envrironment variables and the |
| 713 | # second variable is the callable object (see PEP333) |
| 714 | def hello_world_app(environ, start_response): |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 715 | status = b'200 OK' # HTTP Status |
| 716 | headers = [(b'Content-type', b'text/plain; charset=utf-8')] # HTTP Headers |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 717 | start_response(status, headers) |
| 718 | |
| 719 | # The returned object is going to be printed |
Antoine Pitrou | 38a66ad | 2009-01-03 18:41:49 +0000 | [diff] [blame] | 720 | return [b"Hello World"] |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 721 | |
| 722 | httpd = make_server('', 8000, hello_world_app) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 723 | print("Serving on port 8000...") |
Christian Heimes | 7d2ff88 | 2007-11-30 14:35:04 +0000 | [diff] [blame] | 724 | |
| 725 | # Serve until process is killed |
| 726 | httpd.serve_forever() |