October 23rd, 2012

Bottle 0.11

Bottle is a fast, simple and lightweight WSGI micro web-framework for Python. It is distributed as a single file module and has no dependencies other than the Python Standard Library.


I am providing a Setup of 5 stars as bottle is a single file and very very easy to download and get started for anyone with at least some Python knowledge. You can either install it's single module file via PyPI or by using wget, it's very practical. It seems like a good option for embedded systems which lack the ability to use large disks or lack the RAM for full frameworks like Django or Web2py.

Since it is just a single python module, you won't see some rich web development APIs here. The largest APIs would be the templates and plugin system. More on the plugins later. If all you need is to drive a simple Python application through a web interface, such as for a router or other network device, this will definitely do the trick for you.

If you are planning on using a Database, then here's some good news for those hardcore Python developers out there... You can use any Database API/Abstraction layer you want, including SQLAlchemy. Although, this is generally a feature for Microframeworks such as bottle.

Here is their overly simple Hello World example right from their tutorial to show how simple it's overall syntax is. You can use a mutli-file Python project, however for smaller and simpler applications, it's nice to be-able to use a single file:

from bottle import route, run

def hello():
    return "Hello World!"

run(host='localhost', port=8000, debug=True)

To view this example page, you would visit localhost:8000/hello in your browser. To run the application, simple go into your command line, or even hit Run in your IDE. You run the application just like any other Python application, there's no need to worry about a special command that manages your application, it runs directly from the file you make. This allows you to do a number of things even before your application sees the world, you could even build a simple GUI or Windows Service(for those on Windows/OS X platforms).

Since the single Python module is less than 3,000 lines of code, it is really easy to browse the code while building your web application. It is less than 3,000 lines if you take away all the helpful comments and docstrings. For developers who like to read the source code of the underlying API, then bottle is a great framework for you. Although keep in mind, that there are other microframeworks which are also single file Python modules as well.

Routing in bottle is very simple and straightforward. As you can see from the example above, you simply decorate the Python functions you want exposed to the outside world. You can also assign multiple URLs to single Python function, as well as make the Python function take a parameter or two. Parameters are handled in the same way which they are in Django, you have a tag of some sort in the route which refers to which parameter it uses in Python. This enables your application to easy take in data from the outside world without having to worry about a request variable or parsing the URI string yourself. It also enables as a result, clean URIs. Bottle also supports Explicit routing configuration like Django uses. Here is a short example directly from their guide:

def setup_routing(app):
    app.route('/new', method=['GET', 'POST'], form_new)
    app.route('/edit', method=['GET', 'POST'], form_edit)

app = Bottle()

This bring us to the next major part of routing in the Web 2.0 days, RESTful routing. Although this framework is a single Python module, don't let it fool you by what standards it supports out of the box. Just like the route decorator above, bottle also includes get, post, put, and delete decorators for easily enabling RESTful functions. For more information on their routing, visit their tutorial page for it. This is a review of bottle, not a tutorial.

One feature I really like about bottle is the content generator, depending what is returned in your Python function, bottle will handle it elegantly. Here is a small table of various returns and what will happen as a result:

DictAutomatically generates and returns an application/json Content type.
None/False/Empty StringProduces a Content-Length header of 0
Unicode Strings*Automatically encoded with the codec specified in the Content-Type, of which utf8 is the default, then treated as a normal Byte String.
Byte Strings*Outputs to browser while adding the appropriate Content-Length header for the string size, if it fits in memory.
Instances of HTTPError or HTTPResponseSame effect as raising them as Exceptions.
File objectsEverything that has a .read() method is treated as File object and passed to the wsgi.file_wrapper callable defined by the WSGI server framework.
Iterables and generatorsYou are allowed to use yield in your callbacks or return an iterable. The only supported iterables are Unicode and Byte Strings(as mentioned above by use of *'s), or HTTPError and HTTPResponse instances. Nested iterables are not supported.
* You can send lists of these types of objects

Bottle fully supports cookie handling using the global request variable. Something you may not expect from a microframework, is the ability to handle signed cookies, this is a very pleasant surprise. Signed cookies can be used to replace sessions, or they can store other data which you don't otherwise want to store in a session on the server. This is very useful if your web directory is mostly read-only for security reasons, but still want to allow some sort of sign-in, tracking, or anything that requires user tracking on the website. The information in these cookies is not encrypted and of course not copy protected. Because of that, don't store sensitive information in them. The signing merely prevents user manipulation, so you can store their user ID, or username without worrying about them messing with it to hack someone elses account.

Bottle supports the use of many popular third party template engines, with a very subtle configuration change in Bottle itself. Bottle also comes with it's own simple template engine for those who are limited on disk space or RAM, or when a large full-featured template engine isn't needed. Mind you, the bottle template engine is good for most uses. It supports what you would expect from a template engine, conditional checking, variables, embedded python, including other templates, and template inheritance.

This now brings us to Plugins, Bottle has a growing list of plugins which are already available for use in your applications. Some noteworthy plugins are SQLAlchemy, Web2PyDAL, and Memcache. It is entirely your choice to use these plugins or call their respective APIs directly. Plugins do make integration with these APIs much easier when developing in bottle, and I highly recommend looking at the examples on their respective project pages. If you find that you need to make your own plugin for Bottle, they have a development guide you can read. Creating a plugin doesn't require lots of Bottle API knowledge, as it's very similar to building a Python decorator, and all Python developers should know what a decorator is and how to make them.

Although I cannot find any list of supporting companies of Bottle itself. I can see that there are plenty of places online which you can ask for help while using Bottle, all listed in a central place on their homepage. The activity on these support venues is good, although not as active as the larger frameworks(for obvious reasons).

This concluded this review, to learn more about Bottle, you should read their excellent documentation and knowledge base. It is directly on the front page of their website, you can't miss it. I rated the pros and cons based on the project type, since this is a micro-framework, I didn't list anything about an admin interface or missing AJAX integration. Well, since it natively supports returning application/json, it does make AJAX integration easier than some other full-fledged frameworks.


  • Full support of Python 3.x
  • Single file Python module, it's very small
  • No Python dependencies
  • Easy Integration with third party template engines
  • Easily enables clean URI routes
  • Supports RESTful out of the box
  • Useful selection of plugins


  • None I can think of


A great micro-framework with plenty of useful features right out of the box. If your needs are small, or you need a relatively small application footprint, consider Bottle as your web application micro-framework. Bottle can be easily used for larger application as well, don't let the Micro part fool you.

Package Website

About Me

My Photo
Names Kevin, hugely into UNIX technologies, not just Linux. I've dabbled with the demons, played with the Sun, and now with the Penguins.

Kevin Veroneau Consulting Services
Do you require the services of a Django contractor? Do you need both a website and hosting services? Perhaps I can help.

This Month

If you like what you read, please consider donating to help with hosting costs, and to fund future books to review.

Python Powered | © 2012-2019 Kevin Veroneau