Auto Reloading¶

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.

run(..., debug=True, 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 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.

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 can be 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 Request Routing for details.

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, DELETE or PATCH, add a method keyword argument to the route() decorator or use one of the five alternative decorators: get(), post(), put(), delete() or patch().

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 # or route

@get('/login') # or @route('/login')
def login():
    return '''
        <form action="/login" method="POST">
            Username: <input name="username" type="text" />
            Password: <input name="password" type="password" />
            <input value="Login" type="submit" />
        </form>
    '''

@post('/login') # or @route('/login', method='POST')
def do_login():
    username = request.forms.username
    password = request.forms.password
    if check_login(username, password):
        return "<p>Your login information 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 <BaseRequest.forms> is further described in the :ref:`tutorial-request 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.

The response Object¶

Response metadata such as the HTTP status code, response headers and cookies are stored in an object called response up to the point where they are transmitted to the browser. You can manipulate these metadata directly or use the predefined helper methods to do so. The full API and feature list is described in the API section (see BaseResponse), 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 codes other than the ones defined by the HTTP specification will only confuse the browser and break standards.

Response Headers

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 unique, 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', 'name=value2')

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

Redirects

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 route, redirect
@route('/wrong/url')
def wrong():
    redirect("/right/url")

Cookies¶

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

@route('/hello')
def hello_again():
    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.7 or newer).

• samesite: Disables third-party use for a cookie. Allowed attributes: lax and strict. In strict mode the cookie will never be sent. In lax mode the cookie is only sent with a top-level GET request.

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 4 KB 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 are not encrypted in any way. Whatever you store in a cookie, the user can read it. Worse 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. Thus, never store confidential information in cookies.

• 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 do_login():
    username = request.forms.get('username')
    password = request.forms.get('password')
    if check_login(username, password):
        response.set_cookie("account", username, secret='some-secret-key')
        return template("<p>Welcome {{name}}! You are now logged in.</p>", name=username)
    else:
        return "<p>Login failed.</p>"

@route('/restricted')
def restricted_area():
    username = request.get_cookie("account", secret='some-secret-key')
    if username:
        return template("Hello {{name}}. Welcome back.", name=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 4 KB limit.

HTTP Headers¶

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

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

Cookies¶

Cookies are small pieces of text stored in the clients browser and sent back to the server with each request. They are useful to keep some state around for more than one request (HTTP itself is stateless), but should not be used for security related stuff. They can be easily forged by the client.

All cookies sent by the client are available through Request.cookies (a FormsDict). 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

The Request.get_cookie method is a different way do access cookies. It supports decoding signed cookies as described in a separate section.

Query parameters, Forms and File uploads¶

Query and form data is parsed on demand and accessible via request properties and methods. Some of those properties combine values from different sources for easier access. Have a look at the following table for a quick overview.

Introducing FormsDict

Bottle uses a special type of dictionary to store those parameters. FormsDict behaves like a normal dictionary, but has some additional features to make your life easier.

First of all, FormsDict is a subclass of MultiDict and can store more than one value per key. Only the first value is returned by default, but MultiDict.getall() can be used to get a (possibly empty) list of all values for a specific key:

for choice in request.forms.getall('multiple_choice'):
    do_something(choice)

Attribute-like access is also supported, returning empty strings for missing values. This simplifies code a lot whend ealing with lots of optional attributes:

name = request.query.name    # may be an empty string

A word on unicode and character encodings

Unicode characters in the request path, query parameters or cookies are a bit tricky. HTTP is a very old byte-based protocol that predates unicode and lacks explicit encoding information. This is why WSGI servers have to fall back on ISO-8859-1 (aka latin1, a reversible input encoding) for those estrings. Modern browsers default to utf8, though. It’s a bit much to ask application developers to translate every single user input string to the correct encoding manually. Bottle makes this easy and just assumes utf8 for everything. All strings returned by Bottle APIs support the full range of unicode characters, as long as the webpage or HTTP client follows best practices and does not break with established standards.

Query Parameters¶

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 Request.query attribute (a FormsDict) to access these values and the Request.query_string attribute to get the whole string.

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

HTML <form> Handling¶

Let us start from the beginning. In HTML, a typical <form> looks something like this:

<form action="/login" method="post">
    Username: <input name="username" type="text" />
    Password: <input name="password" type="password" />
    <input value="Login" type="submit" />
</form>

The action attribute specifies the URL that will receive the form data. method defines the HTTP method to use (GET or POST). With method="get" the form values are appended to the URL and available through Request.query as described above. This is sometimes considered insecure and has other limitations, so we use method="post" here. If in doubt, use POST forms.

Form fields transmitted via POST are stored in Request.forms as a FormsDict. The server side code may look like this:

from bottle import route, request

@route('/login')
def login():
    return '''
        <form action="/login" method="post">
            Username: <input name="username" type="text" />
            Password: <input name="password" type="password" />
            <input value="Login" type="submit" />
        </form>
    '''

@route('/login', method='POST')
def do_login():
    username = request.forms.username
    password = request.forms.password
    if check_login(username, password):
        return "<p>Your login information was correct.</p>"
    else:
        return "<p>Login failed.</p>"

File Uploads¶

To support file uploads, we have to change the <form> tag a bit. First, we tell the browser to encode the form data in a different way by adding an enctype="multipart/form-data" attribute to the <form> tag. Then, we add <input type="file" /> tags to allow the user to select a file. Here is an example:

<form action="/upload" method="post" enctype="multipart/form-data">
  Category:      <input type="text" name="category" />
  Select a file: <input type="file" name="upload" />
  <input type="submit" value="Start upload" />
</form>

Bottle stores file uploads in Request.files as FileUpload instances, along with some metadata about the upload. Let us assume you just want to save the file to disk:

@route('/upload', method='POST')
def do_upload():
    category   = request.forms.category
    upload     = request.files.get('upload')
    name, ext = os.path.splitext(upload.filename)
    if ext not in ('.png','.jpg','.jpeg'):
        return 'File extension not allowed.'

    save_path = get_save_path_for_category(category)
    upload.save(save_path) # appends upload.filename automatically
    return 'OK'

FileUpload.filename contains the name of the file on the clients file system, but is cleaned up and normalized to prevent bugs caused by unsupported characters or path segments in the filename. If you need the unmodified name as sent by the client, have a look at FileUpload.raw_filename.

The FileUpload.save method is highly recommended if you want to store the file to disk. It prevents some common errors (e.g. it does not overwrite existing files unless you tell it to) and stores the file in a memory efficient way. You can access the file object directly via FileUpload.file. Just be careful.

JSON¶

For JavaScript and REST APIs it is very common to send application/json to the server instead of from data. The Request.json attribute contains the parsed data structure if available, or None for empty requests or those that did not contain application/json data. Parsing errors trigger an appropiate HTTPError.

Raw Request Data¶

You can access the raw body data as a file-like object via Request.body. This is a io.BytesIO buffer or a temporary file depending on the content length and Request.MEMFILE_MAX setting. In both cases the body is completely buffered before you can access the attribute. If you expect huge amounts of data and want to get direct unbuffered access to the stream, have a look at request['wsgi.input'].

WSGI Environment¶

Each BaseRequest instance wraps a WSGI environment dictionary which is stored in Request.environ. Most of the interesting information is also exposed through special methods or properties, but if you want to access the raw WSGI environ 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 template("Your IP is: {{ip}}", ip=ip)