Tutorial¶

The Default Application¶

For the sake of simplicity, most examples in this tutorial use a module-level route() decorator to define routes. This adds routes to a global “default application”, an instance of Bottle that is automatically created the first time you call route(). Several other module-level decorators and functions relate to this default application, but if you prefer a more object oriented approach and don’t mind the extra typing, you can create a separate application object and use that instead of the global one:

from bottle import Bottle, run

app = Bottle()

@app.route('/hello')
def hello():
    return "Hello World!"

run(app, host='localhost', port=8080)

The object-oriented approach is further described in the Default Application section. Just keep in mind that you have a choice.

Dynamic Routes¶

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:

@route('/wiki/<pagename>')            # matches /wiki/Learning_Python
def show_wiki_page(pagename)):
    ...

@route('/<action>/<user>')            # matches /follow/defnull
def user_api(action, user):
    ...

Filters are used to define more specific wildcards, and/or transform the covered part of the URL before it is passed to the callback. A filtered wildcard is declared as <name:filter> or <name:filter:config>. The syntax for the optional config part depends on the filter used.

The following filters are implemented by default and more may be added:

• :int matches (signed) digits only and converts the value to integer.

• :float similar to :int but for decimal numbers.

• :path matches all characters including the slash character in a non-greedy way and can be used to match more than one path segment.

• :re allows you to specify a custom regular expression in the config field. The matched value is not modified.

Let’s have a look at some practical examples:

@route('/object/<id:int>')
def callback(id):
    assert isinstance(id, int)

@route('/show/<name:re:[a-z]+>')
def callback(name):
    assert name.isalpha()

@route('/static/<path:path>')
def callback(path):
    return static_file(path, ...)

You can add your own filters as well. See Routing for details.

The new rule syntax was introduce in Bottle 0.10 to simplify some common use cases, but the old syntax still works and you can find lot code examples still using it. The differences are best described by example:

Try to avoid the old syntax in future projects if you can. It is not deprecated for now, but will be eventually.

HTTP Request Methods¶

The HTTP protocol defines several request methods (sometimes referred to as “verbs”) for different tasks. GET is the default for all routes with no other method specified. These routes will match GET requests only. To handle other methods such as POST, PUT or DELETE, add a method keyword argument to the route() decorator or use one of the four alternative decorators: get(), post(), put() or delete().

The POST method is commonly used for HTML form submission. This example shows how to handle a login form using POST:

from bottle import get, post, request

@get('/login') # or @route('/login')
def login_form():
    return '''<form method="POST">
                <input name="name"     type="text" />
                <input name="password" type="password" />
              </form>'''

@post('/login') # or @route('/login', method='POST')
def login_submit():
    name     = request.forms.get('name')
    password = request.forms.get('password')
    if check_login(name, password):
        return "<p>Your login was correct</p>"
    else:
        return "<p>Login failed</p>"

In this example the /login URL is linked to two distinct callbacks, one for GET requests and another for POST requests. The first one displays a HTML form to the user. The second callback is invoked on a form submission and checks the login credentials the user entered into the form. The use of Request.forms is further described in the Request Data section.

Special Methods: HEAD and ANY

The HEAD method is used to ask for the response identical to the one that would correspond to a GET request, but without the response body. This is useful for retrieving meta-information about a resource without having to download the entire document. Bottle handles these requests automatically by falling back to the corresponding GET route and cutting off the request body, if present. You don’t have to specify any HEAD routes yourself.

Additionally, the non-standard ANY method works as a low priority fallback: Routes that listen to ANY will match requests regardless of their HTTP method but only if no other more specific route is defined. This is helpful for proxy-routes that redirect requests to more specific sub-applications.

To sum it up: HEAD requests fall back to GET routes and all requests fall back to ANY routes, but only if there is no matching route for the original request method. It’s as simple as that.

Routing Static Files¶

Static files such as images or css files are not served automatically. You have to add a route and a callback to control which files get served and where to find them:

from bottle import static_file
@route('/static/<filename>')
def server_static(filename):
    return static_file(filename, root='/path/to/your/static/files')

The static_file() function is a helper to serve files in a safe and convenient way (see Static Files). This example is limited to files directly within the /path/to/your/static/files directory because the <filename> wildcard won’t match a path with a slash in it. To serve files in subdirectories, change the wildcard to use the path filter:

@route('/static/<filepath:path>')
def server_static(filepath):
    return static_file(filepath, root='/path/to/your/static/files')

Be careful when specifying a relative root-path such as root='./static/files'. The working directory (./) and the project directory are not always the same.

Error Pages¶

If anything goes wrong, Bottle displays an informative but fairly boring error page. You can override the default for a specific HTTP status code with the error() decorator:

@error(404)
def error404(error):
    return 'Nothing here, sorry'

From now on, 404 File not Found errors will display a custom error page to the user. The only parameter passed to the error-handler is an instance of HTTPError. Apart from that, an error-handler is quite similar to a regular request callback. You can read from request, write to response and return any supported data-type except for HTTPError instances.

Error handlers are used only if your application returns or raises an HTTPError exception (abort() does just that). Changing Request.status or returning HTTPResponse won’t trigger the error handler.

Static Files¶

You can directly return file objects, but static_file() is the recommended way to serve static files. It automatically guesses a mime-type, adds a Last-Modified header, restricts paths to a root directory for security reasons and generates appropriate error responses (401 on permission errors, 404 on missing files). It even supports the If-Modified-Since header and eventually generates a 304 Not modified response. You can pass a custom mimetype to disable mimetype guessing.

from bottle import static_file
@route('/images/<filename:re:.*\.png>#')
def send_image(filename):
    return static_file(filename, root='/path/to/image/files', mimetype='image/png')

@route('/static/<filename:path>')
def send_static(filename):
    return static_file(filename, root='/path/to/static/files')

You can raise the return value of static_file() as an exception if you really need to.

Forced Download

Most browsers try to open downloaded files if the MIME type is known and assigned to an application (e.g. PDF files). If this is not what you want, you can force a download-dialog and even suggest a filename to the user:

@route('/download/<filename:path>')
def download(filename):
    return static_file(filename, root='/path/to/static/files', download=filename)

If the download parameter is just True, the original filename is used.

HTTP Errors and Redirects¶

The abort() function is a shortcut for generating HTTP error pages.

from bottle import route, abort
@route('/restricted')
def restricted():
    abort(401, "Sorry, access denied.")

To redirect a client to a different URL, you can send a 303 See Other response with the Location header set to the new URL. redirect() does that for you:

from bottle import redirect
@route('/wrong/url')
def wrong():
    redirect("/right/url")

You may provide a different HTTP status code as a second parameter.

Other Exceptions

All exceptions other than HTTPResponse or HTTPError will result in a 500 Internal Server Error response, so they won’t crash your WSGI server. You can turn off this behavior to handle exceptions in your middleware by setting bottle.app().catchall to False.

The Response Object¶

Response meta-data such as the HTTP status code, response header and cookies are stored in an object called response up to the point where they are transmitted to the browser. You can manipulate these meta-data directly or use the predefined helper methods to do so. The full API and feature list is described in the API section (see Response), but the most common use cases and features are covered here, too.

Status Code

The HTTP status code controls the behavior of the browser and defaults to 200 OK. In most scenarios you won’t need to set the Response.status attribute manually, but use the abort() helper or return an HTTPResponse instance with the appropriate status code. Any integer is allowed but only the codes defined by the HTTP specification will have an effect other than confusing the browser and breaking standards.

Response Header

Response headers such as Cache-Control or Location are defined via Response.set_header(). This method takes two parameters, a header name and a value. The name part is case-insensitive:

@route('/wiki/<page>')
def wiki(page):
    response.set_header('Content-Language', 'en')
    ...

Most headers are exclusive, meaning that only one header per name is send to the client. Some special headers however are allowed to appear more than once in a response. To add an additional header, use Response.add_header() instead of Response.set_header():

response.set_header('Set-Cookie', 'name=value')
response.add_header('Set-Cookie', 'name2=value2')

Please not that this is just an example. If you want to work with cookies, read ahead.

Cookies¶

A cookie is a named piece of text stored in the user’s browser cache. You can access previously defined cookies via Request.get_cookie() and set new cookies with Response.set_cookie():

@route('/hello')
def hello_again(self):
    if request.get_cookie("visited"):
        return "Welcome back! Nice to see you again"
    else:
        response.set_cookie("visited", "yes")
        return "Hello there! Nice to meet you"

The Response.set_cookie() method accepts a number of additional keyword arguments that control the cookies lifetime and behavior. Some of the most common settings are described here:

• max_age: Maximum age in seconds. (default: None)

• expires: A datetime object or UNIX timestamp. (default: None)

• domain: The domain that is allowed to read the cookie. (default: current domain)

• path: Limit the cookie to a given path (default: /)

• secure: Limit the cookie to HTTPS connections (default: off).

• httponly: Prevent client-side javascript to read this cookie (default: off, requires Python 2.6 or newer).

If neither expires nor max_age is set, the cookie expires at the end of the browser session or as soon as the browser window is closed. There are some other gotchas you should consider when using cookies:

• Cookies are limited to 4kb of text in most browsers.

• Some users configure their browsers to not accept cookies at all. Most search-engines ignore cookies, too. Make sure that your application still works without cookies.

• Cookies are stored at client side and not encrypted in any way. Whatever you store in a cookie, the user can read it. Worth than that, an attacker might be able to steal a user’s cookies through XSS vulnerabilities on your side. Some viruses are known to read the browser cookies, too. Do not store confidential information in cookies, ever.

• Cookies are easily forged by malicious clients. Do not trust cookies.

Signed Cookies

As mentioned above, cookies are easily forged by malicious clients. Bottle can cryptographically sign your cookies to prevent this kind of manipulation. All you have to do is to provide a signature key via the secret keyword argument whenever you read or set a cookie and keep that key a secret. As a result, Request.get_cookie() will return None if the cookie is not signed or the signature keys don’t match:

@route('/login')
def login():
    username = request.forms.get('username')
    password = request.forms.get('password')
    if check_user_credentials(username, password):
        response.set_cookie("account", username, secret='some-secret-key')
        return "Welcome %s! You are now logged in." % username
    else:
        return "Login failed."

@route('/restricted')
def restricted_area(self):
    username = request.get_cookie("account", secret='some-secret-key')
    if username:
        return "Hello %s. Welcome back." % username
    else:
        return "You are not logged in. Access denied."

In addition, Bottle automatically pickles and unpickles any data stored to signed cookies. This allows you to store any pickle-able object (not only strings) to cookies, as long as the pickled data does not exceed the 4kb limit.

Cookies¶

Cookies are stored in BaseRequest.cookies as a FormsDict. The BaseRequest.get_cookie() method allows access to signed cookies as described in a separate section. This example shows a simple cookie-based view counter:

from bottle import route, request, response
@route('/counter')
def counter():
    count = int( request.cookies.get('counter', '0') )
    count += 1
    response.set_cookie('counter', str(count))
    return 'You visited this page %d times' % count

HTTP Headers¶

All HTTP headers sent by the client (e.g. Referer, Agent or Accept-Language) are stored in a WSGIHeaderDict and accessible through BaseRequest.headers. A WSGIHeaderDict is basically a dictionary with case-insensitive keys:

from bottle import route, request
@route('/is_ajax')
def is_ajax():
    if request.header.get('X-Requested-With') == 'XMLHttpRequest':
        return 'This is an AJAX request'
    else:
        return 'This is a normal request'

Query Variables¶

The query string (as in /forum?id=1&page=5) is commonly used to transmit a small number of key/value pairs to the server. You can use the BaseRequest.query (a FormsDict) to access these values and the BaseRequest.query_string attribute to get the whole string.

from bottle import route, request, response
@route('/forum')
def display_forum():
    forum_id = request.query.id
    page = request.query.page or '1'
    return 'Forum ID: %s (page %s)' % (forum_id, page)

POST Form Data and File Uploads¶

The request body of POST and PUT requests may contain form data encoded in various formats. The BaseRequest.forms dictionary contains parsed textual form fields, BaseRequest.files stores file uploads and BaseRequest.POST combines both dictionaries into one. All three are FormsDict instances and created on demand. File uploads are saved as special cgi.FieldStorage objects along with some meta-data. Finally, you can access the raw body data as a file-like object via BaseRequest.body.

Here is an example for a simple file upload form:

<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="text" name="name" />
  <input type="file" name="data" />
</form>

from bottle import route, request
@route('/upload', method='POST')
def do_upload():
    name = request.forms.name
    data = request.files.data
    if name and data and data.file:
        raw = data.file.read() # This is dangerous for big files
        filename = data.filename
        return "Hello %s! You uploaded %s (%d bytes)." % (name, filename, len(raw))
    return "You missed a field."

WSGI Environment¶

Each BaseRequest instance wraps a WSGI environment dictionary. The original is stored in BaseRequest.environ, but the request object itself behaves like a dictionary, too. Most of the interesting data is exposed through special methods or attributes, but if you want to access WSGI environ variables directly, you can do so:

@route('/my_ip')
def show_ip():
    ip = request.environ.get('REMOTE_ADDR')
    # or ip = request.get('REMOTE_ADDR')
    # or ip = request['REMOTE_ADDR']
    return "Your IP is: %s" % ip

Application-wide Installation¶

Plugins can be installed application-wide or just to some specific routes that need additional functionality. Most plugins can safely be installed to all routes and are smart enough to not add overhead to callbacks that do not need their functionality.

Let us take the ‘sqlite’ plugin for example. It only affects route callbacks that need a database connection. Other routes are left alone. Because of this, we can install the plugin application-wide with no additional overhead.

To install a plugin, just call install() with the plugin as first argument:

from bottle_sqlite import SQLitePlugin
install(SQLitePlugin(dbfile='/tmp/test.db'))

The plugin is not applied to the route callbacks yet. This is delayed to make sure no routes are missed. You can install plugins first and add routes later, if you want to. The order of installed plugins is significant, though. If a plugin requires a database connection, you need to install the database plugin first.

Uninstall Plugins

You can use a name, class or instance to uninstall() a previously installed plugin:

sqlite_plugin = SQLitePlugin(dbfile='/tmp/test.db')
install(sqlite_plugin)

uninstall(sqlite_plugin) # uninstall a specific plugin
uninstall(SQLitePlugin)  # uninstall all plugins of that type
uninstall('sqlite')      # uninstall all plugins with that name
uninstall(True)          # uninstall all plugins at once

Plugins can be installed and removed at any time, even at runtime while serving requests. This enables some neat tricks (installing slow debugging or profiling plugins only when needed) but should not be overused. Each time the list of plugins changes, the route cache is flushed and all plugins are re-applied.

Route-specific Installation¶

The apply parameter of the route() decorator comes in handy if you want to install plugins to only a small number of routes:

sqlite_plugin = SQLitePlugin(dbfile='/tmp/test.db')

@route('/create', apply=[sqlite_plugin])
def create(db):
    db.execute('INSERT INTO ...')

Blacklisting Plugins¶

You may want to explicitly disable a plugin for a number of routes. The route() decorator has a skip parameter for this purpose:

sqlite_plugin = SQLitePlugin(dbfile='/tmp/test.db')
install(sqlite_plugin)

@route('/open/<db>', skip=[sqlite_plugin])
def open_db(db):
    # The 'db' keyword argument is not touched by the plugin this time.
    if db in ('test', 'test2'):
        # The plugin handle can be used for runtime configuration, too.
        sqlite_plugin.dbfile = '/tmp/%s.db' % db
        return "Database File switched to: /tmp/%s.db" % db
    abort(404, "No such database.")

The skip parameter accepts a single value or a list of values. You can use a name, class or instance to identify the plugin that is to be skipped. Set skip=True to skip all plugins at once.

Plugins and Sub-Applications¶

Most plugins are specific to the application they were installed to. Consequently, they should not affect sub-applications mounted with Bottle.mount(). Here is an example:

root = Bottle()
root.mount(apps.blog, '/blog')

@root.route('/contact', template='contact')
def contact():
    return {'email': 'contact@example.com'}

root.install(plugins.WTForms())

Whenever you mount an application, Bottle creates a proxy-route on the main-application that relays all requests to the sub-application. Plugins are disabled for this kind of proxy-routes by default. As a result, our (fictional) WTForms plugin affects the /contact route, but does not affect the routes of the /blog sub-application.

This behavior is intended as a sane default, but can be overridden. The following example re-activates all plugins for a specific proxy-route:

root.mount(apps.blog, '/blog', skip=None)

But there is a snag: The plugin sees the whole sub-application as a single route, namely the proxy-route mentioned above. In order to affect each individual route of the sub-application, you have to install the plugin to the application explicitly.

Default Application¶

Bottle maintains a global stack of Bottle instances and uses the top of the stack as a default for some of the module-level functions and decorators. The route() decorator, for example, is a shortcut for calling Bottle.route() on the default application:

@route('/')
def hello():
    return 'Hello World'

This is very convenient for small applications and saves you some typing, but also means that, as soon as your module is imported, routes are installed to the global application. To avoid this kind of import side-effects, Bottle offers a second, more explicit way to build applications:

app = Bottle()

@app.route('/')
def hello():
    return 'Hello World'

Separating the application object improves re-usability a lot, too. Other developers can safely import the app object from your module and use Bottle.mount() to merge applications together.

As an alternative, you can make use of the application stack to isolate your routes while still using the convenient shortcuts:

default_app.push()

@route('/')
def hello():
    return 'Hello World'

app = default_app.pop()

Both app() and default_app() are instance of AppStack and implement a stack-like API. You can push and pop applications from and to the stack as needed. This also helps if you want to import a third party module that does not offer a separate application object:

default_app.push()

import some.module

app = default_app.pop()

Debug Mode¶

During early development, the debug mode can be very helpful.

bottle.debug(True)

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 to not use the debug mode on a production server.

Auto Reloading¶

During development, you have to restart the server a lot to test your recent changes. 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.

from bottle import run
run(reloader=True)

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 is terminated and re-spawned by the main process. Changes in template files will not trigger a reload. Please use debug mode to deactivate template caching.

The reloading depends on the ability to stop the child process. If you are running on Windows or any other operating system not supporting signal.SIGINT (which raises KeyboardInterrupt in Python), signal.SIGTERM is used to kill the child. Note that exit handlers and finally clauses, etc., are not executed after a SIGTERM.

Multi-Threaded Server¶

The easiest way to increase performance is to install a multi-threaded or asynchronous WSGI server like paste or cherrypy and tell Bottle to start it instead of the default single-threaded one:

bottle.run(server='paste') # Example

Bottle ships with a lot of ready-to-use adapters for the most common WSGI servers and automates the setup process. Here is an incomplete list:

The full list is available through server_names.

If there is no adapter for your favorite server or if you need more control over the server setup, you may want to start the server manually. Refer to the server documentation on how to mount WSGI applications. Here is an example for paste:

from paste import httpserver
httpserver.serve(bottle.default_app(), host='0.0.0.0', port=80)

Multiple Server Processes¶

A single Python process can only utilise one CPU at a time, even if there are more CPU cores available. The trick is to balance the load between multiple independent Python processes to utilize all of your CPU cores.

Instead of a single Bottle application server, you start one instance of your server for each CPU core available using different local port (localhost:8080, 8081, 8082, …). Then a high performance load balancer acts as a reverse proxy and forwards each new requests to a random Bottle processes, spreading the load between all available back end server instances. This way you can use all of your CPU cores and even spread out the load between different physical servers.

One of the fastest load balancers available is Pound but most common web servers have a proxy-module that can do the work just fine.

Apache mod_wsgi¶

Instead of running your own HTTP server from within Bottle, you can attach Bottle applications to an Apache server using mod_wsgi and Bottle’s WSGI interface.

All you need is an app.wsgi file that provides an application object. This object is used by mod_wsgi to start your application and should be a WSGI-compatible Python callable.

File /var/www/yourapp/app.wsgi:

# Change working directory so relative paths (and template lookup) work again
os.chdir(os.path.dirname(__file__))

import bottle
# ... build or import your bottle application here ...
# Do NOT use bottle.run() with mod_wsgi
application = bottle.default_app()

The Apache configuration may look like this:

<VirtualHost *>
    ServerName example.com

    WSGIDaemonProcess yourapp user=www-data group=www-data processes=1 threads=5
    WSGIScriptAlias / /var/www/yourapp/app.wsgi

    <Directory /var/www/yourapp>
        WSGIProcessGroup yourapp
        WSGIApplicationGroup %{GLOBAL}
        Order deny,allow
        Allow from all
    </Directory>
</VirtualHost>

Google AppEngine¶

The gae adapter completely automates the Google App Engine deployment. It even ensures that a main() function is present in your __main__ module to enable App Caching (which drastically improves performance):

import bottle
# ... build or import your bottle application here ...
bottle.run(server='gae')

It is always a good idea to let GAE serve static files directly. Here is example app.yaml:

application: myapp
version: 1
runtime: python
api_version: 1

handlers:
- url: /static
  static_dir: static

- url: /.*
  script: myapp.py

Good old CGI¶

CGI is slow as hell, but it works:

import bottle
# ... build or import your bottle application here ...
bottle.run(server=bottle.CGIServer)