| |
| :mod:`wsgiref` is a reference implementation of the WSGI specification that can |
| be used to add WSGI support to a web server or framework. It provides utilities |
| for manipulating WSGI environment variables and response headers, base classes |
| for implementing WSGI servers, a demo HTTP server that serves WSGI applications, |
| and a validation tool that checks WSGI servers and applications for conformance |
| to the WSGI specification (:pep:`333`). |
| |
n | See http://www.wsgi.org for more information about WSGI, and links to tutorials |
| and other resources. |
| |
| .. % XXX If you're just trying to write a web application... |
| .. XXX If you're just trying to write a web application... |
| .. % XXX should create a URL on python.org to point people to. |
| |
| |
| :mod:`wsgiref.util` -- WSGI environment utilities |
| ------------------------------------------------- |
| |
| .. module:: wsgiref.util |
n | :synopsis: WSGI environment utilities. |
| |
| |
| This module provides a variety of utility functions for working with WSGI |
| environments. A WSGI environment is a dictionary containing HTTP request |
| variables as described in :pep:`333`. All of the functions taking an *environ* |
| parameter expect a WSGI-compliant dictionary to be supplied; please see |
| :pep:`333` for a detailed specification. |
| |
| ``PATH_INFO``, and all of the :pep:`333`\ -defined ``wsgi.*`` variables. It |
| only supplies default values, and does not replace any existing settings for |
| these variables. |
| |
| This routine is intended to make it easier for unit tests of WSGI servers and |
| applications to set up dummy environments. It should NOT be used by actual WSGI |
| servers or applications, since the data is fake! |
| |
n | Example usage:: |
| |
| from wsgiref.util import setup_testing_defaults |
| from wsgiref.simple_server import make_server |
| |
| # A relatively simple WSGI application. It's going to print out the |
| # environment dictionary after being updated by setup_testing_defaults |
| def simple_app(environ, start_response): |
| setup_testing_defaults(environ) |
| |
| status = '200 OK' |
| headers = [('Content-type', 'text/plain')] |
| |
| start_response(status, headers) |
| |
| ret = ["%s: %s\n" % (key, value) |
| for key, value in environ.iteritems()] |
| return ret |
| |
| httpd = make_server('', 8000, simple_app) |
| print "Serving on port 8000..." |
| httpd.serve_forever() |
| |
| |
| In addition to the environment functions above, the :mod:`wsgiref.util` module |
| also provides these miscellaneous utilities: |
| |
| |
| .. function:: is_hop_by_hop(header_name) |
| |
| Return true if 'header_name' is an HTTP/1.1 "Hop-by-Hop" header, as defined by |
| :rfc:`2616`. |
| |
| |
| .. class:: FileWrapper(filelike [, blksize=8192]) |
| |
n | A wrapper to convert a file-like object to an iterator. The resulting objects |
n | A wrapper to convert a file-like object to an :term:`iterator`. The resulting objects |
| support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for |
| compatibility with Python 2.1 and Jython. As the object is iterated over, the |
| optional *blksize* parameter will be repeatedly passed to the *filelike* |
| object's :meth:`read` method to obtain strings to yield. When :meth:`read` |
| returns an empty string, iteration is ended and is not resumable. |
| |
| If *filelike* has a :meth:`close` method, the returned object will also have a |
| :meth:`close` method, and it will invoke the *filelike* object's :meth:`close` |
| method when called. |
| |
n | Example usage:: |
| |
| from StringIO import StringIO |
| from wsgiref.util import FileWrapper |
| |
| # We're using a StringIO-buffer for as the file-like object |
| filelike = StringIO("This is an example file-like object"*10) |
| wrapper = FileWrapper(filelike, blksize=5) |
| |
| for chunk in wrapper: |
| print chunk |
| |
| |
| |
| :mod:`wsgiref.headers` -- WSGI response header tools |
| ---------------------------------------------------- |
| |
| .. module:: wsgiref.headers |
n | :synopsis: WSGI response header tools. |
| |
| |
| This module provides a single class, :class:`Headers`, for convenient |
| manipulation of WSGI response headers using a mapping-like interface. |
| |
| |
| .. class:: Headers(headers) |
| |
| |
| Content-Disposition: attachment; filename="bud.gif" |
| |
| |
| :mod:`wsgiref.simple_server` -- a simple WSGI HTTP server |
| --------------------------------------------------------- |
| |
| .. module:: wsgiref.simple_server |
n | :synopsis: A simple WSGI HTTP server. |
| |
| |
| This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`) |
| that serves WSGI applications. Each server instance serves a single WSGI |
| application on a given host and port. If you want to serve multiple |
| applications on a single host and port, you should create a WSGI application |
| that parses ``PATH_INFO`` to select which application to invoke for each |
| request. (E.g., using the :func:`shift_path_info` function from |
| :mod:`wsgiref.util`.) |
| |
| |
n | .. function:: make_server(host, port, app [, server_class=:class:`WSGIServer` [, handler_class=:class:`WSGIRequestHandler`]]) |
n | .. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=WSGIRequestHandler]]) |
| |
| Create a new WSGI server listening on *host* and *port*, accepting connections |
| for *app*. The return value is an instance of the supplied *server_class*, and |
| will process requests using the specified *handler_class*. *app* must be a WSGI |
| application object, as defined by :pep:`333`. |
| |
| Example usage:: |
| |
| |
| httpd = make_server('', 8000, demo_app) |
| print "Serving HTTP on port 8000..." |
| |
| # Respond to requests until process is killed |
| httpd.serve_forever() |
| |
| # Alternative: serve one request, then exit |
n | ##httpd.handle_request() |
n | httpd.handle_request() |
| |
| |
| .. function:: demo_app(environ, start_response) |
| |
| This function is a small but complete WSGI application that returns a text page |
| containing the message "Hello world!" and a list of the key/value pairs provided |
| in the *environ* parameter. It's useful for verifying that a WSGI server (such |
| as :mod:`wsgiref.simple_server`) is able to run a simple WSGI application |
| |
| .. method:: WSGIRequestHandler.handle() |
| |
| Process the HTTP request. The default implementation creates a handler instance |
| using a :mod:`wsgiref.handlers` class to implement the actual WSGI application |
| interface. |
| |
| |
n | :mod:`wsgiref.validate` -- WSGI conformance checker |
n | :mod:`wsgiref.validate` --- WSGI conformance checker |
| --------------------------------------------------- |
| ---------------------------------------------------- |
| |
| .. module:: wsgiref.validate |
n | :synopsis: WSGI conformance checker. |
| |
| |
| When creating new WSGI application objects, frameworks, servers, or middleware, |
| it can be useful to validate the new code's conformance using |
| :mod:`wsgiref.validate`. This module provides a function that creates WSGI |
| application objects that validate communications between a WSGI server or |
| gateway and a WSGI application object, to check both sides for protocol |
| conformance. |
| |
| This wrapper may also generate output using the :mod:`warnings` module to |
| indicate behaviors that are questionable but which may not actually be |
| prohibited by :pep:`333`. Unless they are suppressed using Python command-line |
| options or the :mod:`warnings` API, any such warnings will be written to |
| ``sys.stderr`` (*not* ``wsgi.errors``, unless they happen to be the same |
| object). |
| |
n | Example usage:: |
| |
| from wsgiref.validate import validator |
| from wsgiref.simple_server import make_server |
| |
| # Our callable object which is intentionally not compliant to the |
| # standard, so the validator is going to break |
| def simple_app(environ, start_response): |
| status = '200 OK' # HTTP Status |
| headers = [('Content-type', 'text/plain')] # HTTP Headers |
| start_response(status, headers) |
| |
| # This is going to break because we need to return a list, and |
| # the validator is going to inform us |
| return "Hello World" |
| |
| # This is the application wrapped in a validator |
| validator_app = validator(simple_app) |
| |
| httpd = make_server('', 8000, validator_app) |
| print "Listening on port 8000...." |
| httpd.serve_forever() |
| |
| |
| :mod:`wsgiref.handlers` -- server/gateway base classes |
| ------------------------------------------------------ |
| |
| .. module:: wsgiref.handlers |
n | :synopsis: WSGI server/gateway base classes. |
| |
| |
| This module provides base handler classes for implementing WSGI servers and |
| gateways. These base classes handle most of the work of communicating with a |
| WSGI application, as long as they are given a CGI-like environment, along with |
| input, output, and error streams. |
| |
| |
| :class:`BaseCGIHandler` and :class:`CGIHandler`. |
| |
| |
| .. attribute:: BaseHandler.http_version |
| |
| If :attr:`origin_server` is true, this string attribute is used to set the HTTP |
| version of the response set to the client. It defaults to ``"1.0"``. |
| |
t | |
| Examples |
| -------- |
| |
| This is a working "Hello World" WSGI application:: |
| |
| from wsgiref.simple_server import make_server |
| |
| # Every WSGI application must have an application object - a callable |
| # object that accepts two arguments. For that purpose, we're going to |
| # use a function (note that you're not limited to a function, you can |
| # use a class for example). The first argument passed to the function |
| # is a dictionary containing CGI-style envrironment variables and the |
| # second variable is the callable object (see PEP333) |
| def hello_world_app(environ, start_response): |
| status = '200 OK' # HTTP Status |
| headers = [('Content-type', 'text/plain')] # HTTP Headers |
| start_response(status, headers) |
| |
| # The returned object is going to be printed |
| return ["Hello World"] |
| |
| httpd = make_server('', 8000, hello_world_app) |
| print "Serving on port 8000..." |
| |
| # Serve until process is killed |
| httpd.serve_forever() |