Werkzeug

Entry Point

There should be one central file that provides the WSGI application and dispatches the requests. It's also a good idea to assemble the final URL map there if you use the Werkzeug routing system.

It's a good idea to call the file something like main.py or application.py and locate it in the root of the package. This is what it could look like:

from mypackage.urls import map, not_found
from mypackage.utils import Request, Response
from werkzeug.routing import RequestRedirect
from werkzeug.exceptions import HTTPException

def application(environ, start_response):
    urls = map.bind_to_environ(environ)
    req = Request(environ, urls)
    try:
        endpoint, args = urls.match(req.path)
        module, func = endpoint.split('/', 1)
        mod = __import__('mypackage.views.' + module, None,
                         None, [''])
        view = getattr(mod, func)
        resp = view(req, **args)
    except (RequestRedirect, HTTPException), e:
        resp = e
    return resp(environ, start_response)

You can even further simplify the dispatching by using urls.dispatch as explained on the routing page.

This will look for the controller functions in mypackage.views.module. If the URL is configured with an endpoint of 'static/index' the module mypackage.views.static is loaded and index(req) is called.

The URL rule parameters are passed to the function as keyword argument then.

Note: This is just one idea of how things can look like. This doesn't necessarily have to represent your application. You can for example save the request object in a thread local storage or have your views as methods of a controller class you instantiate with the request as argument for each incoming request. You can also use other request objects or no request object at all etc.

Utils

If we continue the example above we need an utils module with the request and response objects. This would also contain other utilities and a bridge to a template engine. In this example we will use the Jinja as template engine - basically because it's something we use too - but you can of course use any template engine:

from werkzeug import BaseRequest, BaseResponse
from jinja import Environment, PackageLoader

env = Environment(loader=PackageLoader('mypackage', 'templates'))

class Request(BaseRequest):

    def __init__(self, environ, urls):
        self.environ = environ
        self.urls = urls

    def url_for(self, endpoint, **values):
        return self.urls.build(endpoint, values)

class Response(BaseResponse):
    pass

class TemplateResponse(Response):

    def __init__(self, template_name, **values):
        tmpl = env.get_template(template_name)
        output = tmpl.render(values)
        super(TemplateResponse, self).__init__(output, mimetype='text/html')

Note: templates in this example are saved in the templates folder inside the mypackage package. The way template loading and rendering works depends on the template engine, have a look at the template engine's documentation regarding that.

We just subclass request and response for our needs and provide a second response subclass that is used to render templates. It's used in the example view below.

req.url_for can be used to get an URL to another view.

URLs

Because we use the Werkzeug URL routing system in this example and the URLs are stored in urls.py we need that file:

from werkzeug.routing import Map, Rule

map = Map([
    Rule('/', 'static/index')
])

This is just one small URL rule for one view.

View

Here is the view defined above. It must be saved in myprojects/views/static.py as defined above:

from myproject.utils import TemplateResponse

def index(req):
    return TemplateResponse('index.html', title='Welcome')

Models and Templates

Models and templates are out of the scope for this documentation but you should get an idea how you can organize your WSGI application built with the help of Werkzeug.

Generating Boilerplate Code

Getting the application started is usually a quite boring process because you write the same code again and again. Because of that Werkzeug comes with a tiny script that can generate a package structure from a package template.

Have a look at the bootstrap documentation for more information about this topic.