:mod:`wsgiref` --- WSGI Utilities and Reference Implementation

==============================================================

.. module:: wsgiref

   :synopsis: WSGI Utilities and Reference Implementation.

.. moduleauthor:: Phillip J. Eby <pje@telecommunity.com>

.. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>

.. versionadded:: 2.5

The Web Server Gateway Interface (WSGI) is a standard interface between web

server software and web applications written in Python. Having a standard

interface makes it easy to use an application that supports WSGI with a number

of different web servers.

Only authors of web servers and programming frameworks need to know every detail

and corner case of the WSGI design.  You don't need to understand every detail

of WSGI just to install a WSGI application or to write a web application using

an existing framework.

: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`).

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...

:mod:`wsgiref.util` -- WSGI environment utilities

-------------------------------------------------

.. module:: wsgiref.util

   :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.

.. function:: guess_scheme(environ)

   Return a guess for whether ``wsgi.url_scheme`` should be "http" or "https", by

   checking for a ``HTTPS`` environment variable in the *environ* dictionary.  The

   return value is a string.

   This function is useful when creating a gateway that wraps CGI or a CGI-like

   protocol such as FastCGI.  Typically, servers providing such protocols will

   include a ``HTTPS`` variable with a value of "1" "yes", or "on" when a request

   is received via SSL.  So, this function returns "https" if such a value is

   found, and "http" otherwise.

.. function:: request_uri(environ [, include_query=1])

   Return the full request URI, optionally including the query string, using the

   algorithm found in the "URL Reconstruction" section of :pep:`333`.  If

   *include_query* is false, the query string is not included in the resulting URI.

.. function:: application_uri(environ)

   Similar to :func:`request_uri`, except that the ``PATH_INFO`` and

   ``QUERY_STRING`` variables are ignored.  The result is the base URI of the

   application object addressed by the request.

.. function:: shift_path_info(environ)

   Shift a single name from ``PATH_INFO`` to ``SCRIPT_NAME`` and return the name.

   The *environ* dictionary is *modified* in-place; use a copy if you need to keep

   the original ``PATH_INFO`` or ``SCRIPT_NAME`` intact.

   If there are no remaining path segments in ``PATH_INFO``, ``None`` is returned.

   Typically, this routine is used to process each portion of a request URI path,

   for example to treat the path as a series of dictionary keys. This routine

   modifies the passed-in environment to make it suitable for invoking another WSGI

   application that is located at the target URI. For example, if there is a WSGI

   application at ``/foo``, and the request URI path is ``/foo/bar/baz``, and the

   WSGI application at ``/foo`` calls :func:`shift_path_info`, it will receive the

   string "bar", and the environment will be updated to be suitable for passing to

   a WSGI application at ``/foo/bar``.  That is, ``SCRIPT_NAME`` will change from

   ``/foo`` to ``/foo/bar``, and ``PATH_INFO`` will change from ``/bar/baz`` to

   ``/baz``.

   When ``PATH_INFO`` is just a "/", this routine returns an empty string and

   appends a trailing slash to ``SCRIPT_NAME``, even though empty path segments are

   normally ignored, and ``SCRIPT_NAME`` doesn't normally end in a slash.  This is

   intentional behavior, to ensure that an application can tell the difference

   between URIs ending in ``/x`` from ones ending in ``/x/`` when using this

   routine to do object traversal.

.. function:: setup_testing_defaults(environ)

   Update *environ* with trivial defaults for testing purposes.

   This routine adds various parameters required for WSGI, including ``HTTP_HOST``,

   ``SERVER_NAME``, ``SERVER_PORT``, ``REQUEST_METHOD``, ``SCRIPT_NAME``,

   ``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!

   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])

   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.

   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

   :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)

   Create a mapping-like object wrapping *headers*, which must be a list of header

   name/value tuples as described in :pep:`333`.  Any changes made to the new

   :class:`Headers` object will directly update the *headers* list it was created

   with.

   :class:`Headers` objects support typical mapping operations including

   :meth:`__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`,

   :meth:`__delitem__`, :meth:`__contains__` and :meth:`has_key`.  For each of

   these methods, the key is the header name (treated case-insensitively), and the

   value is the first value associated with that header name.  Setting a header

   deletes any existing values for that header, then adds a new value at the end of

   the wrapped header list.  Headers' existing order is generally maintained, with

   new headers added to the end of the wrapped list.

   Unlike a dictionary, :class:`Headers` objects do not raise an error when you try

   to get or delete a key that isn't in the wrapped header list. Getting a

   nonexistent header just returns ``None``, and deleting a nonexistent header does

   nothing.

   :class:`Headers` objects also support :meth:`keys`, :meth:`values`, and

   :meth:`items` methods.  The lists returned by :meth:`keys` and :meth:`items` can

   include the same key more than once if there is a multi-valued header.  The

   ``len()`` of a :class:`Headers` object is the same as the length of its

   :meth:`items`, which is the same as the length of the wrapped header list.  In

   fact, the :meth:`items` method just returns a copy of the wrapped header list.

   Calling ``str()`` on a :class:`Headers` object returns a formatted string

   suitable for transmission as HTTP response headers.  Each header is placed on a

   line with its value, separated by a colon and a space. Each line is terminated

   by a carriage return and line feed, and the string is terminated with a blank

   line.

   In addition to their mapping interface and formatting features, :class:`Headers`

   objects also have the following methods for querying and adding multi-valued

   headers, and for adding headers with MIME parameters:

   .. method:: Headers.get_all(name)

      Return a list of all the values for the named header.

      The returned list will be sorted in the order they appeared in the original

      header list or were added to this instance, and may contain duplicates.  Any

      fields deleted and re-inserted are always appended to the header list.  If no

      fields exist with the given name, returns an empty list.

   .. method:: Headers.add_header(name, value, **_params)

      Add a (possibly multi-valued) header, with optional MIME parameters specified

      via keyword arguments.

      *name* is the header field to add.  Keyword arguments can be used to set MIME

      parameters for the header field.  Each parameter must be a string or ``None``.

      Underscores in parameter names are converted to dashes, since dashes are illegal

      in Python identifiers, but many MIME parameter names include dashes.  If the

      parameter value is a string, it is added to the header value parameters in the

      form ``name="value"``. If it is ``None``, only the parameter name is added.

      (This is used for MIME parameters without a value.)  Example usage::

         h.add_header('content-disposition', 'attachment', filename='bud.gif')

      The above will add a header that looks like this::

         Content-Disposition: attachment; filename="bud.gif"

:mod:`wsgiref.simple_server` -- a simple WSGI HTTP server

---------------------------------------------------------

.. module:: wsgiref.simple_server

   :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`.)

.. 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::

      from wsgiref.simple_server import make_server, demo_app

      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

      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

   correctly.

.. class:: WSGIServer(server_address, RequestHandlerClass)

   Create a :class:`WSGIServer` instance.  *server_address* should be a

   ``(host,port)`` tuple, and *RequestHandlerClass* should be the subclass of

   :class:`BaseHTTPServer.BaseHTTPRequestHandler` that will be used to process

   requests.

   You do not normally need to call this constructor, as the :func:`make_server`

   function can handle all the details for you.

   :class:`WSGIServer` is a subclass of :class:`BaseHTTPServer.HTTPServer`, so all

   of its methods (such as :meth:`serve_forever` and :meth:`handle_request`) are

   available. :class:`WSGIServer` also provides these WSGI-specific methods:

   .. method:: WSGIServer.set_app(application)

      Sets the callable *application* as the WSGI application that will receive

      requests.

   .. method:: WSGIServer.get_app()

      Returns the currently-set application callable.

   Normally, however, you do not need to use these additional methods, as

   :meth:`set_app` is normally called by :func:`make_server`, and the

   :meth:`get_app` exists mainly for the benefit of request handler instances.

.. class:: WSGIRequestHandler(request, client_address, server)

   Create an HTTP handler for the given *request* (i.e. a socket), *client_address*

   (a ``(host,port)`` tuple), and *server* (:class:`WSGIServer` instance).

   You do not need to create instances of this class directly; they are

   automatically created as needed by :class:`WSGIServer` objects.  You can,

   however, subclass this class and supply it as a *handler_class* to the

   :func:`make_server` function.  Some possibly relevant methods for overriding in

   subclasses:

   .. method:: WSGIRequestHandler.get_environ()

      Returns a dictionary containing the WSGI environment for a request.  The default

      implementation copies the contents of the :class:`WSGIServer` object's

      :attr:`base_environ` dictionary attribute and then adds various headers derived

      from the HTTP request.  Each call to this method should return a new dictionary

      containing all of the relevant CGI environment variables as specified in

      :pep:`333`.

   .. method:: WSGIRequestHandler.get_stderr()

      Return the object that should be used as the ``wsgi.errors`` stream. The default

      implementation just returns ``sys.stderr``.

   .. 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.

:mod:`wsgiref.validate` --- WSGI conformance checker

----------------------------------------------------

.. module:: wsgiref.validate

   :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.

Note that this utility does not guarantee complete :pep:`333` compliance; an

absence of errors from this module does not necessarily mean that errors do not

exist.  However, if this module does produce an error, then it is virtually

certain that either the server or application is not 100% compliant.

This module is based on the :mod:`paste.lint` module from Ian Bicking's "Python

Paste" library.

.. function:: validator(application)

   Wrap *application* and return a new WSGI application object.  The returned

   application will forward all requests to the original *application*, and will

   check that both the *application* and the server invoking it are conforming to

   the WSGI specification and to RFC 2616.

   Any detected nonconformance results in an :exc:`AssertionError` being raised;

   note, however, that how these errors are handled is server-dependent.  For

   example, :mod:`wsgiref.simple_server` and other servers based on

   :mod:`wsgiref.handlers` (that don't override the error handling methods to do

   something else) will simply output a message that an error has occurred, and

   dump the traceback to ``sys.stderr`` or some other error stream.

   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).

   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

   :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:: CGIHandler()

   CGI-based invocation via ``sys.stdin``, ``sys.stdout``, ``sys.stderr`` and

   ``os.environ``.  This is useful when you have a WSGI application and want to run

   it as a CGI script.  Simply invoke ``CGIHandler().run(app)``, where ``app`` is

   the WSGI application object you wish to invoke.

   This class is a subclass of :class:`BaseCGIHandler` that sets ``wsgi.run_once``

   to true, ``wsgi.multithread`` to false, and ``wsgi.multiprocess`` to true, and

   always uses :mod:`sys` and :mod:`os` to obtain the necessary CGI streams and

   environment.

.. class:: BaseCGIHandler(stdin, stdout, stderr, environ [, multithread=True [, multiprocess=False]])

   Similar to :class:`CGIHandler`, but instead of using the :mod:`sys` and

   :mod:`os` modules, the CGI environment and I/O streams are specified explicitly.

   The *multithread* and *multiprocess* values are used to set the

   ``wsgi.multithread`` and ``wsgi.multiprocess`` flags for any applications run by

   the handler instance.

   This class is a subclass of :class:`SimpleHandler` intended for use with

   software other than HTTP "origin servers".  If you are writing a gateway

   protocol implementation (such as CGI, FastCGI, SCGI, etc.) that uses a

   ``Status:`` header to send an HTTP status, you probably want to subclass this

   instead of :class:`SimpleHandler`.

.. class:: SimpleHandler(stdin, stdout, stderr, environ [,multithread=True [, multiprocess=False]])

   Similar to :class:`BaseCGIHandler`, but designed for use with HTTP origin

   servers.  If you are writing an HTTP server implementation, you will probably

   want to subclass this instead of :class:`BaseCGIHandler`

   This class is a subclass of :class:`BaseHandler`.  It overrides the

   :meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`,

   :meth:`_write`, and :meth:`_flush` methods to support explicitly setting the

   environment and streams via the constructor.  The supplied environment and

   streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and

   :attr:`environ` attributes.

.. class:: BaseHandler()

   This is an abstract base class for running WSGI applications.  Each instance

   will handle a single HTTP request, although in principle you could create a

   subclass that was reusable for multiple requests.

   :class:`BaseHandler` instances have only one method intended for external use:

   .. method:: BaseHandler.run(app)

      Run the specified WSGI application, *app*.

   All of the other :class:`BaseHandler` methods are invoked by this method in the

   process of running the application, and thus exist primarily to allow

   customizing the process.

   The following methods MUST be overridden in a subclass:

   .. method:: BaseHandler._write(data)

      Buffer the string *data* for transmission to the client.  It's okay if this

      method actually transmits the data; :class:`BaseHandler` just separates write

      and flush operations for greater efficiency when the underlying system actually

      has such a distinction.

   .. method:: BaseHandler._flush()

      Force buffered data to be transmitted to the client.  It's okay if this method

      is a no-op (i.e., if :meth:`_write` actually sends the data).

   .. method:: BaseHandler.get_stdin()

      Return an input stream object suitable for use as the ``wsgi.input`` of the

      request currently being processed.