User’s Guide — Bottle 0.14-dev documentation

This guide introduces you to the concepts and features of the Bottle web framework and covers basic and advanced topics alike. You can read it from start to end, or use it as a reference later on. The automatically generated API Reference may be interesting for you, too. It covers more details, but explains less than this tutorial. Solutions for the most common questions can be found in our F.A.Q. collection or on the F.A.Q. page. If you need any help, join our mailing list or visit us in our IRC channel.
Bottle does not depend on any external libraries. You can just download bottle.py into your project directory and start coding:
This will get you the latest development snapshot that includes all the new features. If you prefer a more stable environment, you should stick with the stable releases. These are available on PyPI and can be installed via pip (recommended) or your package manager:
It is usually a better idea to create a virtualenv per project and use that to install packages:
This tutorial assumes you have Bottle either installed or copied into your project directory. Let’s start with a very basic “Hello World” example:
This is it. Run this script, visit http://localhost:8080/hello and you will see “Hello World!” in your browser. Here is how it works:
The route() decorator binds a piece of code to an URL path. In this case, we link the /hello path to the hello() function. This is called a route (hence the decorator name) and is the most important concept of this framework. You can define as many routes as you want. Whenever a browser requests a URL, the associated function is called and the return value is sent back to the browser. It’s as simple as that.
The run() call in the last line starts a built-in development server. It runs on localhost port 8080 and serves requests until you hit Control-c. You can switch the server backend later (see Deployment), but for now a development server is all we need. It requires no setup at all and is an incredibly painless way to get your application up and running for local tests.
Debug Mode is very helpful during early development, but should be switched off for public applications. Keep that in mind.
This is just a demonstration of the basic concept of how applications are built with Bottle. Continue reading and you’ll see what else is possible.
For the sake of simplicity, most examples in this tutorial use a module-level route() and other decorators to define routes. Those refer to a global “default application”, an instance of Bottle that is automatically created the first time you call route() or its friends. If you prefer a more explicit approach and don’t mind the extra typing, you can create a separate application object and use that instead of the global one:
The object-oriented approach is further described in the Structuring Applications section. Just keep in mind that you have a choice.
During early development, the debug mode can be very helpful.
In this mode, Bottle is much more verbose and provides helpful debugging information whenever an error occurs. It also disables some optimisations that might get in your way and adds some checks that warn you about possible misconfiguration. Here is an incomplete list of things that change in debug mode:
The default error page shows a traceback.
Templates are not cached.
Plugins are applied immediately.
Just make sure not to use the debug mode on a production server.
Tired of restarting the server every time you change your code? The auto reloader can do this for you. Every time you edit a module file, the reloader restarts the server process and loads the newest version of your code.
How it works: the main process will not start a server, but spawn a new child process using the same command line arguments used to start the main process. All module-level code is executed at least twice! Be careful.
The child process will have os.environ['BOTTLE_CHILD'] set to True and start as a normal non-reloading app server. As soon as any of the loaded modules changes, the child process terminates and is re-spawned by the main process. Changes in template files will not trigger a reload. Please use debug mode to deactivate template caching.
Bottle is not only a module, but also a command line executable that can be used to start your app instead of calling run() programmatically. If you installed bottle via pip or similar tools, there will also be a handy bottle command on your path. Try one of the following:
Here is a quick example:
Changed in version 0.13: The executable script installed into (virtual) environments was named bottle.py, which could result in circular imports. The old name is now deprecated and the new executable ist named just bottle.
In the last chapter we built a very simple web application with only a single route. Here is the routing part of the “Hello World” example again:
The route() decorator links an URL path to a callback function, and adds a new route to the default application. An application with just one route is kind of boring, though. Let’s add some more (don’t forget from bottle import template):
This example demonstrates two things: You can bind more than one route to a single callback, and you can add wildcards to URLs and access them via keyword arguments.
Routes that contain wildcards are called dynamic routes (as opposed to static routes) and match more than one URL at the same time. A simple wildcard consists of a name enclosed in angle brackets (e.g. <name>) and accepts one or more characters up to the next slash (/). For example, the route /hello/<name> accepts requests for /hello/alice as well as /hello/bob, but not for /hello, /hello/ or /hello/mr/smith.
Each wildcard passes the covered part of the URL as a keyword argument to the request callback. You can use them right away and implement RESTful, nice-looking and meaningful URLs with ease. Here are some other examples along with the URLs they’d match:
Filters can be used to define more specific wildca