Werkzeug

WSGI

Back in 2003, Python had a number of web applications and frameworks but all of them had to reimplement a common interface to FastCGI, CGI and mod_python which were the prefered hosting environments. To solve the problem that all these implementations were incompatible Phillip J. Eby wrote the WSGI specification which defines a very basic interface, now the standard among all frameworks.

Django which is a very common framework nowadays was initially developed for mod_python and as a result of that the WSGI layer is nearly invisible. Werkzeug on the other hand only gives you the tools you need to get a WSGI running but the process of implementing the actual dispatching method is up to you.

So you need to understand the very basic concept behind to WSGI to get started. The following example is a very basic WSGI application:

from cgi import escape, parse_qs

def application(environ, start_response):
    parameters = parse_qs(environ.get('QUERY_STRING', ''))
    name = parameters.get('name', ['World'])[0]
    start_response('200 OK', [('Content-Type', 'text/html')])
    return ['''
      <title>Hello World</title>
      <p>Hello %s!</p>
    ''' % escape(name)]

A WSGI application is just a simple function or a callable class that accepts two arguments. The first one is the WSGI environment which contains all the incoming data and the start_response function which starts the response. The return value of the server is then an iterable. Every iteration sends a chunk to the client.

As you can see from this example it feels unnatural so Werkzeug provides wrappers which wrap the request and the response parts (environ and start_response). The request object is passed the environ and parses form data, the query string, http headers and much more whereas the response object is a WSGI application itself you can instanciate and call on return. In the typical Werkzeug application you will never see something from WSGI unless you are working on the dispatcher code.

All the details are in the documentation.