Recipes¶

This is a collection of code snippets and examples for common use cases.

Keeping track of Sessions¶

There is no built-in support for sessions because there is no right way to do it (in a micro framework). Depending on requirements and environment you could use beaker middleware with a fitting backend or implement it yourself. Here is an example for beaker sessions with a file-based backend:

import bottle
from beaker.middleware import SessionMiddleware

session_opts = {
    'session.type': 'file',
    'session.cookie_expires': 300,
    'session.data_dir': './data',
    'session.auto': True
}
app = SessionMiddleware(bottle.app(), session_opts)

@bottle.route('/test')
def test():
  s = bottle.request.environ.get('beaker.session')
  s['test'] = s.get('test',0) + 1
  s.save()
  return 'Test counter: %d' % s['test']

bottle.run(app=app)

WARNING: Beaker’s SessionMiddleware is not thread safe. If two concurrent requests modify the same session at the same time, one of the updates might get lost. For this reason, sessions should only be populated once and treated as a read-only store after that. If you find yourself updating sessions regularly, and don’t want to risk losing any updates, think about using a real database instead or seek alternative session middleware libraries.

Debugging with Style: Debugging Middleware¶

Bottle catches all Exceptions raised in your app code to prevent your WSGI server from crashing. If the built-in debug() mode is not enough and you need exceptions to propagate to a debugging middleware, you can turn off this behaviour:

import bottle
app = bottle.app()
app.catchall = False #Now most exceptions are re-raised within bottle.
myapp = DebuggingMiddleware(app) #Replace this with a middleware of your choice (see below)
bottle.run(app=myapp)

Now, bottle only catches its own exceptions (HTTPError, HTTPResponse and BottleException) and your middleware can handle the rest.

The werkzeug and paste libraries both ship with very powerful debugging WSGI middleware. Look at werkzeug.debug.DebuggedApplication for werkzeug and paste.evalexception.middleware.EvalException for paste. They both allow you do inspect the stack and even execute python code within the stack context, so do not use them in production.

Unit-Testing Bottle Applications¶

Unit-testing is usually performed against methods defined in your web application without running a WSGI environment.

A simple example using Nose:

import bottle

@bottle.route('/')
def index():
    return 'Hi!'

if __name__ == '__main__':
    bottle.run()

Test script:

import mywebapp

def test_webapp_index():
    assert mywebapp.index() == 'Hi!'

In the example the Bottle route() method is never executed - only index() is tested.

If the code being tested requires access to bottle.request you can mock it using Boddle:

import bottle

@bottle.route('/')
def index():
    return 'Hi %s!' % bottle.request.params['name']

Test script:

import mywebapp
from boddle import boddle

def test_webapp_index():
    with boddle(params={'name':'Derek'}):
        assert mywebapp.index() == 'Hi Derek!'

Functional Testing Bottle Applications¶

Any HTTP-based testing system can be used with a running WSGI server, but some testing frameworks work more intimately with WSGI, and provide the ability the call WSGI applications in a controlled environment, with tracebacks and full use of debugging tools. Testing tools for WSGI is a good starting point.

Example using WebTest and Nose:

from webtest import TestApp
import mywebapp

def test_functional_login_logout():
    app = TestApp(mywebapp.app)

    app.post('/login', {'user': 'foo', 'pass': 'bar'}) # log in and get a cookie

    assert app.get('/admin').status == '200 OK'        # fetch a page successfully

    assert app.get('/logout').status_code == 200        # log out
    app.reset()                                        # drop the cookie

    # fetch the same page, unsuccessfully
    assert app.get('/admin', expect_errors=True).status == '401 Unauthorized'

Embedding other WSGI Apps¶

This is not the recommend way (you should use a middleware in front of bottle to do this) but you can call other WSGI applications from within your bottle app and let bottle act as a pseudo-middleware. Here is an example:

from bottle import request, response, route
subproject = SomeWSGIApplication()

@route('/subproject/<subpath:re:.*>', method='ANY')
def call_wsgi(subpath):
    new_environ = request.environ.copy()
    new_environ['SCRIPT_NAME'] = new_environ.get('SCRIPT_NAME','') + '/subproject'
    new_environ['PATH_INFO'] = '/' + subpath
    def start_response(status, headerlist):
        response.status = int(status.split()[0])
        for key, value in headerlist:
            response.add_header(key, value)
    return app(new_environ, start_response)

Again, this is not the recommend way to implement subprojects. It is only here because many people asked for this and to show how bottle maps to WSGI.

Ignore trailing slashes¶

For Bottle, /example and /example/ are two different routes [1]. To treat both URLs the same you can add two @route decorators:

@route('/test')
@route('/test/')
def test(): return 'Slash? no?'

add a WSGI middleware that strips trailing slashes from all URLs:

class StripPathMiddleware(object):
  def __init__(self, app):
    self.app = app
  def __call__(self, e, h):
    e['PATH_INFO'] = e['PATH_INFO'].rstrip('/')
    return self.app(e,h)

app = bottle.app()
myapp = StripPathMiddleware(app)
bottle.run(app=myapp)

or add a before_request hook to strip the trailing slashes:

@hook('before_request')
def strip_path():
    request.environ['PATH_INFO'] = request.environ['PATH_INFO'].rstrip('/')

Footnotes

[1]	Because they are. See <http://www.ietf.org/rfc/rfc3986.txt>

Keep-alive requests¶

Note

For a more detailed explanation, see Primer to Asynchronous Applications.

Several “push” mechanisms like XHR multipart need the ability to write response data without closing the connection in conjunction with the response header “Connection: keep-alive”. WSGI does not easily lend itself to this behavior, but it is still possible to do so in Bottle by using the gevent async framework. Here is a sample that works with either the gevent HTTP server or the paste HTTP server (it may work with others, but I have not tried). Just change server='gevent' to server='paste' to use the paste server:

from gevent import monkey; monkey.patch_all()

import gevent
from bottle import route, run

@route('/stream')
def stream():
    yield 'START'
    gevent.sleep(3)
    yield 'MIDDLE'
    gevent.sleep(5)
    yield 'END'

run(host='0.0.0.0', port=8080, server='gevent')

If you browse to http://localhost:8080/stream, you should see ‘START’, ‘MIDDLE’, and ‘END’ show up one at a time (rather than waiting 8 seconds to see them all at once).

Gzip Compression in Bottle¶

Note

For a detailed discussion, see compression

A common feature request is for Bottle to support Gzip compression, which speeds up sites by compressing static resources (like CSS and JS files) during a request.

Supporting Gzip compression is not a straightforward proposition, due to a number of corner cases that crop up frequently. A proper Gzip implementation must:

Compress on the fly and be fast doing so.
Do not compress for browsers that don’t support it.
Do not compress files that are compressed already (images, videos).
Do not compress dynamic files.
Support two differed compression algorithms (gzip and deflate).
Cache compressed files that don’t change often.
De-validate the cache if one of the files changed anyway.
Make sure the cache does not get to big.
Do not cache small files because a disk seek would take longer than on-the-fly compression.

Because of these requirements, it is the recommendation of the Bottle project that Gzip compression is best handled by the WSGI server Bottle runs on top of. WSGI servers such as cherrypy provide a GzipFilter middleware that can be used to accomplish this.

Using hooks to handle CORS¶

Hooks are useful to unconditionally do something before or after each request. For example, if you want to allow Cross-Origin requests for your entire application, instead of writing a plugin you can use hooks to add the appropiate headers:

from bottle import hook, response, HTTPResponse

cors_headers = {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
    # 'Access-Control-Allow-Headers': 'X-Token, ...',
    # 'Access-Control-Expose-Headers': 'X-My-Custom-Header, ...',
    # 'Access-Control-Max-Age': '86400',
    # 'Access-Control-Allow-Credentials': 'true',
}

@hook('before_request')
def handle_options():
    if request.method == 'OPTIONS':
        # Bypass request routing and immediately return a response
        raise HTTPResponse(headers=cors_headers)

@hook('after_request')
def enable_cors():
    for key, value in cors_headers.items():
       response.set_header(key, value)

Using Bottle with Heroku¶

Heroku, a popular cloud application platform now provides support for running Python applications on their infrastructure.

This recipe is based upon the Heroku Quickstart, with Bottle specific code replacing the Write Your App section of the Getting Started with Python on Heroku/Cedar guide:

import os
from bottle import route, run

@route("/")
def hello_world():
    return "Hello World!"

run(host="0.0.0.0", port=int(os.environ.get("PORT", 5000)))

Heroku’s app stack passes the port that the application needs to listen on for requests, using the os.environ dictionary.

Recipes¶

Keeping track of Sessions¶

Debugging with Style: Debugging Middleware¶

Unit-Testing Bottle Applications¶

Functional Testing Bottle Applications¶

Embedding other WSGI Apps¶

Ignore trailing slashes¶

Keep-alive requests¶

Gzip Compression in Bottle¶

Using hooks to handle CORS¶

Using Bottle with Heroku¶

Table of Contents

Previous topic

Next topic

Like it?

Hosted by: