API Reference — Bottle 0.14-dev documentation

Bottle prides itself on having source code that is easy to read and follow, so most questions about APIs or inner workings can be answered quickly by inspecting sources. Your IDE should give you the same information you’ll find on this page, as most of it is auto-generates from docstrings and method signatures anyway. If you are new to bottle, you may find the User’s Guide more helpful as a starting point.
The module defines several functions, constants, and an exception.
Return the current Structuring Applications. This is actually a callable instances of AppStack.
Change the debug level. There is only one debug level supported at the moment.
Add a plugin to the list of plugins and prepare it for being applied to all routes of this application. A plugin may be a simple decorator or an object that implements the Plugin API.
Uninstall plugins. Pass an instance to remove a specific plugin, a type object to remove all plugins that match that type, a string to remove all plugins with a matching name attribute or True to remove all plugins. Return the list of removed plugins.
Start a server instance. This method blocks until the server terminates.
app – WSGI application or target string supported by load_app(). (default: default_app())
server – Server adapter to use. See server_names keys for valid names or pass a ServerAdapter subclass. (default: wsgiref)
host – Server address to bind to. Pass 0.0.0.0 to listens on all interfaces including the external one. (default: 127.0.0.1)
port – Server port to bind to. Values below 1024 require root privileges. (default: 8080)
reloader – Start auto-reloading server? (default: False)
interval – Auto-reloader interval in seconds (default: 1)
quiet – Suppress output to stdout and stderr? (default: False)
options – Options passed to the server adapter.
Bottle maintains a stack of Bottle instances (see app() and AppStack) and uses the top of the stack as a Structuring Applications for some of the module-level functions and decorators. All of those have a corresponding method on the Bottle class.
Decorator to install a route to the current default application. See Bottle.route() for details.
Decorator to install an error handler to the current default application. See Bottle.error() for details.
Return a decorator that attaches a callback to a hook. See add_hook() for details.
The global request and response instances are only valid from within an request handler function and represent the current HTTP request or response.
A thread-safe instance of LocalRequest. If accessed from within a request callback, this instance always refers to the current request (even on a multi-threaded server).
A thread-safe instance of LocalResponse. It is used to change the HTTP response for the current request.
Aborts execution and causes a HTTP error.
Aborts execution and causes a 303 or 302 redirect, depending on the HTTP protocol version.
Open a file in a safe way and return an instance of HTTPResponse that can be sent back to the client.
filename – Name or path of the file to send, relative to root.
root – Root path for file lookups. Should be an absolute directory path.
mimetype – Provide the content-type header (default: guess from file extension)
download – If True, ask the browser to open a Save as… dialog instead of opening the file with the associated program. You can specify a custom filename as a string. If not specified, the original filename is used (default: False).
charset – The charset for files with a text/* mime-type. (default: UTF-8)
etag – Provide a valid (quoted, non-weak) ETag header value. If set to False, ETag handling is disabled. (default: auto-generate ETag from file metadata)
headers – Additional headers dict to add to the response.
While checking user input is always a good idea, this function provides additional protection against malicious filename parameters from breaking out of the root directory and leaking sensitive information to an attacker.
Read-protected files or files outside of the root directory are answered with 403 Access Denied. Missing files result in a 404 Not Found response. Conditional requests (If-Modified-Since, If-None-Match) are answered with 304 Not Modified whenever possible. HEAD and Range requests (used by download managers to check or continue partial downloads) are also handled automatically.
A base class for exceptions used by bottle.
A subclass of Response that can be raised or returned from request handlers to short-curcuit request processing and override changes made to the global request object. This bypasses error handlers, even if the status code indicates an error. Return or raise HTTPError to trigger error handlers.
Create a new response object.
body – The response body as one of the supported types.
status – Either an HTTP status code (e.g. 200) or a status line including the reason phrase (e.g. ‘200 OK’).
headers – A dictionary or a list of name-value pairs.