Is bottle suitable for complex applications?¶

Bottle is first and foremost amicro framework. It is small, fast, easy to learn, stays out of your way and provides just enough functionality to get you started. This is perfect for prototyping, weekend projects, small applications, REST APIs or micro services, but you’ll have to get your hands dirty at some point. If there is noplugin available for the feature you need, you’ll have to write some glue code yourself. But that’s not as bad as it sounds. Bottle is small and straight forward. Unlike most other frameworks, you can actually find answers by reading its code. If you want to really understand and fully gasp your tech stack, then bottle is for you. But if you have tight deadlines and do not want to deal with any details, a more complete full-stack framework likedjango may be a better choice.

What about Flask?¶

Flask was heavily inspired by Bottle (*) and looks very similar on the surface, but took some very different design decisions. Most importantly, Flask is built on top of other libraries (e.g. Werkzeug, Jinja, Click and many more) which makes Flask itself small, but the actual code required to serve a single request is huge in comparison. I would not call it amicro framework at this point, but that’s just my personal opinion. If you prefer Flask, go for it.

“Template Not Found” in mod_wsgi/mod_python¶

Bottle searches in./ and./views/ for templates. In amod_python ormod_wsgi environment, the working directory (./) depends on your Apache settings. You should add an absolute path to the template search path:

bottle.TEMPLATE_PATH.insert(0,'/absolut/path/to/templates/')

so bottle searches the right paths.

Dynamic Routes and Slashes¶

Indynamic route syntax, a placeholder token (<name>) matches everything up to the next slash. This equals to[^/]+ in regular expression syntax. To accept slashes too, you have to add a custom regular pattern to the placeholder. An example:/images/<filepath:path> would match/images/icons/error.png but/images/<filename> won’t.

Problems with reverse proxies¶

Redirects and url-building only works if bottle knows the public address and location of your application. If you run bottle locally behind a reverse proxy or load balancer, some information might get lost along the way. For example, thewsgi.url_scheme value or theHost header might reflect the local request by your proxy, not the real request by the client. Here is a small WSGI middleware snippet that helps to fix these values:

deffix_environ_middleware(app):deffixed_app(environ,start_response):environ['wsgi.url_scheme']='https'environ['HTTP_X_FORWARDED_HOST']='example.com'returnapp(environ,start_response)returnfixed_appapp=bottle.default_app()app.wsgi=fix_environ_middleware(app.wsgi)

Keeping track of Sessions¶

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

frombottleimportBottle,requestfrombeaker.middlewareimportSessionMiddlewareapp=Bottle()session_opts={'session.type':'file','session.cookie_expires':300,'session.data_dir':'./data','session.auto':True}app=SessionMiddleware(app,session_opts)@app.route('/test')deftest():s=request['beaker.session']s['test']=s.get('test',0)+1s.save()return'Test counter:%d'%s['test']app.run()

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-indebug() mode is not enough and you need exceptions to propagate to a debugging middleware, you can turn off this behaviour:

importbottleapp=bottle.Bottle()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 andBottleException) and your middleware can handle the rest.

Thewerkzeug andpaste libraries both ship with very powerful debugging WSGI middleware. Look atwerkzeug.debug.DebuggedApplication forwerkzeug andpaste.evalexception.middleware.EvalException forpaste. They both allow you do inspect the stack and even execute python code within the stack context, sodo not use these 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:

importbottle@bottle.route('/')defindex():return'Hi!'if__name__=='__main__':bottle.run()

Test script:

importmywebappdeftest_webapp_index():assertmywebapp.index()=='Hi!'

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

If the code being tested requires access tobottle.request you can mock it usingBoddle:

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

Test script:

importmywebappfromboddleimportboddledeftest_webapp_index():withboddle(params={'name':'Derek'}):assertmywebapp.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.

Example usingWebTest:

fromwebtestimportTestAppimportmyappdeftest_functional_login_logout():app=TestApp(myapp.app)app.post('/login',{'user':'foo','pass':'bar'})# log in and get a cookieassertapp.get('/admin').status=='200 OK'# fetch a page successfullyassertapp.get('/logout').status_code==200# log outapp.reset()# drop the cookie# fetch the same page, unsuccessfullyassertapp.get('/admin',expect_errors=True).status=='401 Unauthorized'

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/')deftest():return'Slash? no?'

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

classStripPathMiddleware(object):def__init__(self,app):self.app=appdef__call__(self,e,h):e['PATH_INFO']=e['PATH_INFO'].rstrip('/')returnself.app(e,h)app=bottle.app()myapp=StripPathMiddleware(app)bottle.run(app=myapp)

or add abefore_request hook to strip the trailing slashes:

@hook('before_request')defstrip_path():request['PATH_INFO']=request['PATH_INFO'].rstrip('/')

Footnotes

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

Keep-alive requests¶

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 thegevent async framework. Here is a sample that works with either thegevent HTTP server or thepaste HTTP server (it may work with others, but I have not tried). Just changeserver='gevent' toserver='paste' to use thepaste server:

fromgeventimportmonkey;monkey.patch_all()importgeventfrombottleimportroute,run@route('/stream')defstream():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 tohttp://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¶

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 and reverse proxies often provide built-in features that allow transparent compression without changing the application itself.

Using hooks to handle CORS¶

Hooks are useful to unconditionally do something before or after eachrequest. For example, if you want to allow Cross-Origin requests for yourentire application, instead of writing aplugin you canuse hooks to add the appropiate headers:

frombottleimporthook,response,HTTPResponsecors_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')defhandle_options():ifrequest.method=='OPTIONS':# Bypass request routing and immediately return a responseraiseHTTPResponse(headers=cors_headers)@hook('after_request')defenable_cors():forkey,valueincors_headers.items():response.set_header(key,value)

Using Bottle with Heroku¶

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

This recipe is based upon theHeroku Quickstart,with Bottle specific code replacing theWrite Your Appsection of theGetting Started with Python on Heroku/Cedar guide:

importosfrombottleimportroute,run@route("/")defhello_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 tolisten on for requests, using theos.environ dictionary.