Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Hyperminimal WSGI framework

branch: master

Fetching latest commit…


Cannot retrieve the latest commit at this time

Octocat-spinner-32 debian
Octocat-spinner-32 dream
Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE
Octocat-spinner-32 Makefile


Dream is a hyper-minimal framework for creating WSGI apps, which leverages decoroute and WebOb to dispach and abstract requests. It’s particularly good for API type applications, as this is what it was originally written to support.


Abstracted away from WSGI

You only have to deal with WebOb’s Request objects, and your functions return Response objects.

Nothing you don’t need

Very lightweight. No ORM. No admin page. Just URL routing and request/response objects.

Per-method endpoints

Decoroute has been extended to allow invoking different functions for the same URL based on the request method. This avoids ugly conditional code in your endpoint functions.

Conveniently namespaced

Common classes from WebOb & Decoroute are imported into the dream namespace — no need for anything other than import dream.

JSONResponse class

Since returning JSON is a common thing to do with Dream, there’s a Response subclass which will serialize it out for you. If you want a response intended for human consumption, there is also the clunkily-named HumanReadableJSONResponse.

Exception handling

Unhanded exceptions are caught and returned as 500 responses, with the exception reason in a JSON payload.

Endpoint introspection

Easily see the endpoints you’ve defined:

Crash course

Drop this into in

import dream

App = dream.App()

def hello_json(request):
    return dream.JSONResponse(body={'greeting': 'Hello, world!'})

def hello_text(request):
    return dream.Response(body='Hello, world!',
                          headers={'Content-Type': 'text/plain'})

def hello_user(request, person):
    return dream.Response(body='Nice to meet you, %s' % person,
                          headers={'Content-Type': 'text/plain'})

Run it:

$ gunicorn my_app:App &
$ curl -i http://localhost:8080/greeting.json
$ curl -i http://localhost:8080/greeting.txt

Endpoint introspection

If you’d like to add an endpoint which returns known endpoints, add the following line:

dream.endpoints(App, '/endpoints.json')
Something went wrong with that request. Please try again.