This is a mostly auto-generated API. If you are new to bottle, you might find the narrative Documentation more helpful.
The module defines several functions, constants, and an exception.
Change the debug level. There is only one debug level supported at the moment.
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.
Load a bottle application from a module and make sure that the import
does not affect the current default application, but returns a separate
application object. See load() for the target parameter.
A thread-safe instance of LocalRequest. If accessed from within a
request callback, this instance always refers to the current request
(even on a multithreaded server).
A thread-safe instance of LocalResponse. It is used to change the
HTTP response for the current request.
A dict to map HTTP status codes (e.g. 404) to phrases (e.g. ‘Not Found’)
Return the current Default Application. Actually, these are callable instances of AppStack and implement a stack-like API.
A stack-like list. Calling it returns the head of the stack.
Return the current default application and remove it from the stack.
Bottle maintains a stack of Bottle instances (see app() and AppStack) and uses the top of the stack as a default application for some of the module-level functions and decorators.
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.
Parse rfc2617 HTTP authentication header string (basic) and return (user,pass) tuple or None
Encode and sign a pickle-able object. Return a (byte) string
Verify and decode an encoded string. Return an object or None.
Return a generator for routes that match the signature (name, args) of the func parameter. This may yield more than one route if the function takes optional keyword arguments. The output is best described by example:
a() -> '/a'
b(x, y) -> '/b/<x>/<y>'
c(x, y=5) -> '/c/<x>' and '/c/<x>/<y>'
d(x=5, y=6) -> '/d' and '/d/<x>' and '/d/<x>/<y>'
Shift path fragments from PATH_INFO to SCRIPT_NAME and vice versa.
The modified paths.
script_name – The SCRIPT_NAME path.
script_name – The PATH_INFO path.
shift – The number of path fragments to shift. May be negative to change the shift direction. (default: 1)
This dict stores multiple values per key, but behaves exactly like a normal dict in that it returns only the newest value for any given key. There are special methods available to access the full list of values.
Return the most recent value for a key.
default – The default value to be returned if the key is not present or the type conversion fails.
index – An index for the list of available values.
type – If defined, this callable is used to cast the value into a specific type. Exception are suppressed and result in the default value to be returned.
Return a (possibly empty) list of values for a key.
Aliases for WTForms to mimic other multi-dict APIs (Django)
A case-insensitive version of MultiDict that defaults to
replace the old value instead of appending it.
Return the most recent value for a key.
default – The default value to be returned if the key is not present or the type conversion fails.
index – An index for the list of available values.
type – If defined, this callable is used to cast the value into a specific type. Exception are suppressed and result in the default value to be returned.
This dict-like class wraps a WSGI environ dict and provides convenient access to HTTP_* fields. Keys and values are native strings (2.x bytes or 3.x unicode) and keys are case-insensitive. If the WSGI environment contains non-native string values, these are de- or encoded using a lossless ‘latin1’ character set.
The API will remain stable even on changes to the relevant PEPs. Currently PEP 333, 444 and 3333 are supported. (PEP 444 is the only one that uses non-native strings.)
List of keys that do not have a HTTP_ prefix.
Bottle Class¶Each Bottle object represents a single, distinct web application and consists of routes, callbacks, plugins, resources and configuration. Instances are callable WSGI applications.
catchall – If true (default), handle all exceptions. Turn off to let debugging middleware handle exceptions.
Attach a callback to a hook. Three hooks are currently implemented:
Executed once before each request. The request context is available, but no routing has happened yet.
Executed once after each request regardless of its outcome.
Called whenever Bottle.reset() is called.
A ConfigDict for app specific configuration.
Equals route() with a DELETE method parameter.
Return a decorator that attaches a callback to a hook. See
add_hook() for details.
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.
Search for a matching route and return a (Route , urlargs)
tuple. The second value is a dictionary with parameters extracted
from the URL. Raise HTTPError (404/405) on a non-match.
Merge the routes of another Bottle application or a list of
Route objects into this application. The routes keep their
‘owner’, meaning that the Route.app attribute is not
changed.
Mount an application (Bottle or plain WSGI) to a specific
URL prefix. Example:
root_app.mount('/admin/', admin_app)
prefix – path prefix or mount-point. If it ends in a slash, that slash is mandatory.
app – an instance of Bottle or a WSGI application.
All other parameters are passed to the underlying route() call.
Reset all routes (force plugins to be re-applied) and clear all caches. If an ID or route object is given, only that specific route is affected.
A ResourceManager for application files
A decorator to bind a function to a request URL. Example:
@app.route('/hello/:name')
def hello(name):
return 'Hello %s' % name
The :name part is a wildcard. See Router for syntax
details.
path – Request path or a list of paths to listen to. If no path is specified, it is automatically generated from the signature of the function.
method – HTTP method (GET, POST, PUT, …) or a list of methods to listen to. (default: GET)
callback – An optional shortcut to avoid the decorator
syntax. route(..., callback=func) equals route(...)(func)
name – The name for this route. (default: None)
apply – A decorator or plugin or a list of plugins. These are applied to the route callback in addition to installed plugins.
skip – A list of plugins, plugin classes or names. Matching
plugins are not installed to this route. True skips all.
Any additional keyword arguments are stored as route-specific
configuration and passed to plugins (see Plugin.apply()).
Request and Response objects¶The Request class wraps a WSGI environment and provides helpful methods to parse and access form data, cookies, file uploads and other metadata. Most of the attributes are read-only.
The Response class on the other hand stores header and cookie data that is to be sent to the client.
Note
You usually don’t instantiate Request or Response yourself, but use the module-level instances bottle.request and bottle.response only. These hold the context for the current request cycle and are updated on every request. Their attributes are thread-local, so it is safe to use the global instance in multi-threaded environments too.
alias of BaseRequest
alias of BaseResponse
All template engines supported by bottle implement the BaseTemplate API. This way it is possible to switch and mix template engines without changing the application code at all.
Base class and minimal API for template adapters
Create a new template. If the source parameter (str or buffer) is missing, the name argument is used to guess a template filename. Subclasses can assume that self.source and/or self.filename are set. Both are strings. The lookup, encoding and settings parameters are stored as instance variables. The lookup parameter stores a list containing directory paths. The encoding parameter should be used to decode byte strings or files. The settings parameter contains a dict for engine-specific settings.
This reads or sets the global settings stored in class.settings.
Run preparations (parsing, caching, …). It should be possible to call this again to refresh a template or to update settings.
Render the template with the specified local variables and return a single byte or unicode string. If it is a byte string, the encoding must match self.encoding. This method must be thread-safe! Local variables may be provided in dictionaries (args) or directly, as keywords (kwargs).
Decorator: renders a template for a handler. The handler can control its behavior like that:
return a dict of template vars to fill out the template
return something other than a dict and the view decorator will not process the template, but return the handler result as is. This includes returning a HTTPResponse(dict) to get, for instance, JSON with autojson or other castfilters.
Get a rendered template as a string iterator. You can use a name, a filename or a template string as first parameter. Template rendering arguments can be passed as dictionaries or directly (as keyword arguments).
You can write your own adapter for your favourite template engine or use one of the predefined adapters. Currently there are four fully supported template engines:
Class |
URL |
Decorator |
Render function |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
To use MakoTemplate as your default template engine, just import its specialised decorator and render function:
from bottle import mako_view as view, mako_template as template