Bottle Documentation

Bottle is a fast, simple, and lightweight WSGI micro web-framework for Python. Key features include:

• Routing: Mapping requests to function calls with support for clean and dynamic URLs.
• Templates: A fast built-in template engine with support for external engines like mako, jinja2, and cheetah.
• Utilities: Easy access to HTTP features such as form data, file uploads, cookies, and headers.
• Server: Includes a built-in development server and adapters for WSGI-capable servers like gunicorn, paste, or cheroot.

You can create a basic web application by using the route decorator to map URLs to functions, the template function to render HTML, and the run function to start the built-in development server.

from bottle import route, run, template

@route('/hello/<name>')
def index(name):
    return template('<b>Hello {{name}}</b>!', name=name)

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

In standard asynchronous frameworks, you use callbacks to write to a socket. In Bottle (WSGI), you must return an iterable. To bridge this, use gevent.queue.Queue as your body iterable.

1. Create a gevent.queue.Queue().
2. Pass the queue's .put method as a callback to your async worker.
3. Signal the end of the stream by putting StopIteration into the queue.
4. Return the queue object from your route handler.

@route('/fetch')
def fetch():
    body = gevent.queue.Queue()
    worker = SomeAsyncWorker()
    worker.on_data(body.put)
    worker.on_finish(lambda: body.put(StopIteration))
    worker.start()
    return body

To install Bottle following Python best practices, create a virtual environment (venv), activate it, and use pip to install the bottle package. Bottle has no dependencies other than Python itself.

Note on Python Versions: This tutorial assumes Python 3.10 or newer. If using Python 3.8 or 3.9, you must replace match statements with if-elif-else cascades. If using Python 2.7, you must replace f-strings with standard string formatting methods.

python -m venv bottle_venv
cd bottle_venv
#for Linux & MacOS
source bin/activate
#for Windows
.\Scripts\activate
pip3 install bottle

The Bottle documentation uses Transifex for translation workflows. If you have modified the documentation, you can push new messages to Transifex using make push. To update your local translation files with the latest changes from the platform, use make pull.

Note: Both make push and make pull require a Transifex manager account. For actual translation work, you can use a standard Transifex user account at https://www.transifex.com/bottle.

Plugins can be configured in two primary ways:

1. Constructor Parameters: Pass configuration directly when instantiating the plugin (e.g., database connection strings).
2. Bottle.config: Newer plugins can read values from the Bottle.config dictionary. This allows for easier deployment overrides and runtime changes.

Note: Plugin authors can also inspect route parameters (including custom ones) to change behavior dynamically (e.g., a database plugin starting a transaction if a route accepts a db keyword).

Bottle uses a major.minor.patch versioning scheme that does not strictly follow SemVer. Understanding these rules helps you manage updates:

• Major Release (x.0): Significant milestones that change core design and break backward compatibility. Application code changes are likely required.
• Minor Release (x.y): New APIs or backward-incompatible behavior changes. Usually designed to be backward compatible for at least one minor release, but you may see deprecation warnings.
• Patches (x.y.z): Bug-fixes and security patches that do not change APIs or behavior. These are safe to update immediately.
• Pre-Release Versions: Marked with rc (e.g., 0.13.4rc1). These are API-stable but intended for testing, not production.

You can obtain the Bottle source code via Git or by downloading source archives. For active development, cloning the repository is recommended.

git clone git://github.com/bottlepy/bottle.git
# or
git clone https://github.com/bottlepy/bottle.git

When a form is submitted via POST, the data is stored in request.forms. Ensure your HTML form uses method="post".

from bottle import route, request

@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 Bottle, /example and /example/ are distinct routes. To treat them identically, you can use one of three methods:

1. Multiple Decorators: Add both @route('/path') and @route('/path/') to the function.
2. WSGI Middleware: Use a middleware to strip trailing slashes from PATH_INFO before it reaches Bottle.
3. before_request Hook: Use a Bottle hook to modify the request path.

# Option 1: Multiple decorators
@route('/test')
@route('/test/')
def test(): return 'Slash? no?'

# Option 2: WSGI Middleware
class StripPathMiddleware(object):
  def __init__(self, app):
    self.app = app
  def __call__(self, e, h):
    e['PATH_INFO'] = e['PATH_INFO'].rstrip('/')
    return self.app(e,h)

# Option 3: before_request hook
@hook('before_request')
def strip_path():
    request['PATH_INFO'] = request['PATH_INFO'].rstrip('/')