API Reference¶
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.
Global functions¶
The module defines several functions, constants, and an exception.
- app()¶
- default_app()¶
Return the current Structuring Applications. This is actually a callable instances of
AppStack
.
- debug(mode=True)[source]¶
Change the debug level. There is only one debug level supported at the moment.
- install(self, plugin)¶
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(self, plugin)¶
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 orTrue
to remove all plugins. Return the list of removed plugins.
- run(app=None, server='wsgiref', host='127.0.0.1', port=8080, interval=1, reloader=False, quiet=False, plugins=None, debug=None, config=None, **kargs)[source]¶
Start a server instance. This method blocks until the server terminates.
- Parameters:
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 aServerAdapter
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.
Global decorators¶
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.
- route(path, method='GET', callback=None, **options)¶
- get(...)¶
- post(...)¶
- put(...)¶
- delete(...)¶
- patch(...)¶
Decorator to install a route to the current default application. See
Bottle.route()
for details.
- error(...)¶
Decorator to install an error handler to the current default application. See
Bottle.error()
for details.
- hook(self, name)¶
Return a decorator that attaches a callback to a hook. See
add_hook()
for details.
Request Context¶
The global request
and response
instances are only valid from within an request handler function and represent the current HTTP request or response.
- request = <LocalRequest: GET http://127.0.0.1/>¶
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).
- response = Content-Type: text/html; charset=UTF-8 ¶
A thread-safe instance of
LocalResponse
. It is used to change the HTTP response for the current request.
Helper Functions¶
- redirect(url, code=None)[source]¶
Aborts execution and causes a 303 or 302 redirect, depending on the HTTP protocol version.
- static_file(filename, root, mimetype=True, download=False, charset='UTF-8', etag=None, headers=None)[source]¶
Open a file in a safe way and return an instance of
HTTPResponse
that can be sent back to the client.- Parameters:
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 pre-computed ETag header. If set to
False
, ETag handling is disabled. (default: auto-generate ETag header)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 theroot
directory and leaking sensitive information to an attacker.Read-protected files or files outside of the
root
directory are answered with403 Access Denied
. Missing files result in a404 Not Found
response. Conditional requests (If-Modified-Since
,If-None-Match
) are answered with304 Not Modified
whenever possible.HEAD
andRange
requests (used by download managers to check or continue partial downloads) are also handled automatically.
Exceptions¶
- exception HTTPResponse[source]¶
A subclass of
Response
that can be raised or returned from request handlers to short-curcuit request processing and override changes made to the globalrequest
object. This bypasses error handlers, even if the status code indicates an error. Return or raiseHTTPError
to trigger error handlers.- __init__(body='', status=None, headers=None, **more_headers)[source]¶
Create a new response object.
- Parameters:
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.
Additional keyword arguments are added to the list of headers. Underscores in the header name are replaced with dashes.
- exception HTTPError[source]¶
A subclass of
HTTPResponse
that triggers error handlers.- __init__(status=None, body=None, exception=None, traceback=None, **more_headers)[source]¶
Create a new response object.
- Parameters:
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.
Additional keyword arguments are added to the list of headers. Underscores in the header name are replaced with dashes.
The Bottle
Class¶
- class Bottle[source]¶
Each Bottle object represents a single, distinct web application and consists of routes, callbacks, plugins, resources and configuration. Instances are callable WSGI applications.
- Parameters:
catchall – If true (default), handle all exceptions. Turn off to let debugging middleware handle exceptions.
- config¶
A
ConfigDict
for app specific configuration.
- resources¶
A
ResourceManager
for application files
- add_hook(name, func)[source]¶
Attach a callback to a hook. Three hooks are currently implemented:
- before_request
Executed once before each request. The request context is available, but no routing has happened yet.
- after_request
Executed once after each request regardless of its outcome.
- app_reset
Called whenever
Bottle.reset()
is called.
- hook(name)[source]¶
Return a decorator that attaches a callback to a hook. See
add_hook()
for details.
- mount(prefix, app, **options)[source]¶
Mount an application (
Bottle
or plain WSGI) to a specific URL prefix. Example:parent_app.mount('/prefix/', child_app)
- Parameters:
prefix – path prefix or mount-point.
app – an instance of
Bottle
or a WSGI application.
Plugins from the parent application are not applied to the routes of the mounted child application. If you need plugins in the child application, install them separately.
While it is possible to use path wildcards within the prefix path (
Bottle
childs only), it is highly discouraged.The prefix path must end with a slash. If you want to access the root of the child application via /prefix in addition to /prefix/, consider adding a route with a 307 redirect to the parent application.
- merge(routes)[source]¶
Merge the routes of another
Bottle
application or a list ofRoute
objects into this application. The routes keep their ‘owner’, meaning that theRoute.app
attribute is not changed.
- install(plugin)[source]¶
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(plugin)[source]¶
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 orTrue
to remove all plugins. Return the list of removed plugins.
- reset(route=None)[source]¶
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.
- match(environ)[source]¶
Search for a matching route and return a (
Route
, urlargs) tuple. The second value is a dictionary with parameters extracted from the URL. RaiseHTTPError
(404/405) on a non-match.
- route(path=None, method='GET', callback=None, name=None, apply=None, skip=None, **config)[source]¶
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. SeeRouter
for syntax details.- Parameters:
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)
equalsroute(...)(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()
).
- delete(path=None, method='DELETE', **options)[source]¶
Equals
route()
with aDELETE
method parameter.
- error(code=500, callback=None)[source]¶
Register an output handler for a HTTP error code. Can be used as a decorator or called directly
def error_handler_500(error): return 'error_handler_500' app.error(code=500, callback=error_handler_500) @app.error(404) def error_handler_404(error): return 'error_handler_404'
The Request
Object¶
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.
- Request¶
alias of
BaseRequest
- class BaseRequest[source]¶
A wrapper for WSGI environment dictionaries that adds a lot of convenient access methods and properties. Most of them are read-only.
Adding new attributes to a request actually adds them to the environ dictionary (as ‘bottle.request.ext.<name>’). This is the recommended way to store and access request-specific data.
- environ¶
The wrapped WSGI environ dictionary. This is the only real attribute. All other attributes actually are read-only properties.
- property path¶
The value of
PATH_INFO
with exactly one prefixed slash (to fix broken clients and avoid the “empty path” edge case).
- property method¶
The
REQUEST_METHOD
value as an uppercase string.
- headers[source]¶
A
WSGIHeaderDict
that provides case-insensitive access to HTTP request headers.
- get_header(name, default=None)[source]¶
Return the value of a request header, or a given default value.
- cookies[source]¶
Cookies parsed into a
FormsDict
. Signed cookies are NOT decoded. Useget_cookie()
if you expect signed cookies.
- get_cookie(key, default=None, secret=None, digestmod=<built-in function openssl_sha256>)[source]¶
Return the content of a cookie. To read a Signed Cookie, the secret must match the one used to create the cookie (see
Response.set_cookie
). If anything goes wrong (missing cookie or wrong signature), return a default value.
- query[source]¶
The
query_string
parsed into aFormsDict
. These values are sometimes called “URL arguments” or “GET parameters”, but not to be confused with “URL wildcards” as they are provided by theRouter
.
- forms[source]¶
Form values parsed from an url-encoded or multipart/form-data encoded POST or PUT request body. The result is returned as a
FormsDict
. All keys and values are strings. File uploads are stored separately infiles
.
- params[source]¶
A
FormsDict
with the combined values ofquery
andforms
. File uploads are stored infiles
.
- files[source]¶
File uploads parsed from multipart/form-data encoded POST or PUT request body. The values are instances of
FileUpload
.
- json[source]¶
If the
Content-Type
header isapplication/json
orapplication/json-rpc
, this property holds the parsed content of the request body. Only requests smaller thanMEMFILE_MAX
are processed to avoid memory exhaustion. Invalid JSON raises a 400 error response.
- property body¶
The HTTP request body as a seek-able file-like object. Depending on
MEMFILE_MAX
, this is either a temporary file or aio.BytesIO
instance. Accessing this property for the first time reads and replaces thewsgi.input
environ variable. Subsequent accesses just do a seek(0) on the file object.
- property chunked¶
True if Chunked transfer encoding was.
- POST[source]¶
The values of
forms
andfiles
combined into a singleFormsDict
. Values are either strings (form values) or instances ofFileUpload
.
- property url¶
The full request URI including hostname and scheme. If your app lives behind a reverse proxy or load balancer and you get confusing results, make sure that the
X-Forwarded-Host
header is set correctly.
- urlparts[source]¶
The
url
string as anurlparse.SplitResult
tuple. The tuple contains (scheme, host, path, query_string and fragment), but the fragment is always empty because it is not visible to the server.
- property fullpath¶
Request path including
script_name
(if present).
- property script_name¶
The initial portion of the URL’s path that was removed by a higher level (server or routing middleware) before the application was called. This script path is returned with leading and tailing slashes.
- path_shift(shift=1)[source]¶
- Shift path segments from
path
toscript_name
and vice versa.
- Parameters:
shift – The number of path segments to shift. May be negative to change the shift direction. (default: 1)
- Shift path segments from
- property content_length¶
The request body length as an integer. The client is responsible to set this header. Otherwise, the real length of the body is unknown and -1 is returned. In this case,
body
will be empty.
- property content_type¶
The Content-Type header as a lowercase-string (default: empty).
- property is_xhr¶
True if the request was triggered by a XMLHttpRequest. This only works with JavaScript libraries that support the X-Requested-With header (most of the popular libraries do).
- property auth¶
HTTP authentication data as a (user, password) tuple. This implementation currently supports basic (not digest) authentication only. If the authentication happened at a higher level (e.g. in the front web-server or a middleware), the password field is None, but the user field is looked up from the
REMOTE_USER
environ variable. On any errors, None is returned.
- property remote_route¶
A list of all IPs that were involved in this request, starting with the client IP and followed by zero or more proxies. This does only work if all proxies support the
`X-Forwarded-For
header. Note that this information can be forged by malicious clients.
- property remote_addr¶
The client IP as a string. Note that this information can be forged by malicious clients.
- class LocalRequest[source]¶
A thread-local subclass of
BaseRequest
with a different set of attributes for each thread. There is usually only one global instance of this class (request
). If accessed during a request/response cycle, this instance always refers to the current request (even on a multithreaded server).- bind(environ=None)¶
Wrap a WSGI environ dictionary.
- environ¶
The wrapped WSGI environ dictionary. This is the only real attribute. All other attributes actually are read-only properties.
The Response
Object¶
The Response
class stores the HTTP status code as well as headers and cookies that are to be sent to the client. Similar to bottle.request
there is a thread-local bottle.response
instance that can be used to adjust the current response. Moreover, you can instantiate Response
and return it from your request handler. In this case, the custom instance overrules the headers and cookies defined in the global one.
- Response¶
alias of
BaseResponse
- class BaseResponse[source]¶
Storage class for a response body as well as headers and cookies.
This class does support dict-like case-insensitive item-access to headers, but is NOT a dict. Most notably, iterating over a response yields parts of the body and not the headers.
- __init__(body='', status=None, headers=None, **more_headers)[source]¶
Create a new response object.
- Parameters:
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.
Additional keyword arguments are added to the list of headers. Underscores in the header name are replaced with dashes.
- property status_line¶
The HTTP status line as a string (e.g.
404 Not Found
).
- property status_code¶
The HTTP status code as an integer (e.g. 404).
- property status¶
A writeable property to change the HTTP response status. It accepts either a numeric code (100-999) or a string with a custom reason phrase (e.g. “404 Brain not found”). Both
status_line
andstatus_code
are updated accordingly. The return value is always a status string.
- property headers¶
An instance of
HeaderDict
, a case-insensitive dict-like view on the response headers.
- get_header(name, default=None)[source]¶
Return the value of a previously defined header. If there is no header with that name, return a default value.
- set_header(name, value)[source]¶
Create a new response header, replacing any previously defined headers with the same name.
- iter_headers()[source]¶
Yield (header, value) tuples, skipping headers that are not allowed with the current response status code.
- property headerlist¶
WSGI conform list of (header, value) tuples.
- content_type¶
Current value of the ‘Content-Type’ header.
- content_length¶
Current value of the ‘Content-Length’ header.
- expires¶
Current value of the ‘Expires’ header.
- property charset¶
Return the charset specified in the content-type header (default: utf8).
- set_cookie(name, value, secret=None, digestmod=<built-in function openssl_sha256>, **options)[source]¶
Create a new cookie or replace an old one. If the secret parameter is set, create a Signed Cookie (described below).
- Parameters:
name – the name of the cookie.
value – the value of the cookie.
secret – a signature key required for signed cookies.
Additionally, this method accepts all RFC 2109 attributes that are supported by
cookie.Morsel
, including:- Parameters:
maxage – 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 – limits the cookie to a given path (default: current path)
secure – limit the cookie to HTTPS connections (default: off).
httponly – prevents client-side javascript to read this cookie (default: off, requires Python 2.6 or newer).
samesite – Control or disable third-party use for this cookie. Possible values: lax, strict or none (default).
If neither expires nor maxage is set (default), the cookie will expire at the end of the browser session (as soon as the browser window is closed).
Signed cookies may store any pickle-able object and are cryptographically signed to prevent manipulation. Keep in mind that cookies are limited to 4kb in most browsers.
Warning: Pickle is a potentially dangerous format. If an attacker gains access to the secret key, he could forge cookies that execute code on server side if unpickled. Using pickle is discouraged and support for it will be removed in later versions of bottle.
Warning: Signed cookies are not encrypted (the client can still see the content) and not copy-protected (the client can restore an old cookie). The main intention is to make pickling and unpickling save, not to store secret information at client side.
- class LocalResponse[source]¶
A thread-local subclass of
BaseResponse
with a different set of attributes for each thread. There is usually only one global instance of this class (response
). Its attributes are used to build the HTTP response at the end of the request/response cycle.- bind(body='', status=None, headers=None, **more_headers)¶
Create a new response object.
- Parameters:
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.
Additional keyword arguments are added to the list of headers. Underscores in the header name are replaced with dashes.
- property body¶
Thread-local property
Data Structures¶
- class AppStack[source]¶
A stack-like list. Calling it returns the head of the stack.
- pop()¶
Return the current default application and remove it from the stack.
- class ConfigDict[source]¶
A dict-like configuration storage with additional support for namespaces, validators, meta-data and overlays.
This dict-like class is heavily optimized for read access. Read-only methods and item access should be as fast as a native dict.
- load_module(name, squash=True)[source]¶
Load values from a Python module.
Import a python module by name and add all upper-case module-level variables to this config dict.
- Parameters:
name – Module name to import and load.
squash – If true (default), nested dicts are assumed to represent namespaces and flattened (see
load_dict()
).
- load_config(filename, **options)[source]¶
Load values from
*.ini
style config files using configparser.INI style sections (e.g.
[section]
) are used as namespace for all keys within that section. Both section and key names may contain dots as namespace separators and are converted to lower-case.The special sections
[bottle]
and[ROOT]
refer to the root namespace and the[DEFAULT]
section defines default values for all other sections.- Parameters:
filename – The path of a config file, or a list of paths.
options – All keyword parameters are passed to the underlying
configparser.ConfigParser
constructor call.
- load_dict(source, namespace='')[source]¶
Load values from a dictionary structure. Nesting can be used to represent namespaces.
>>> c = ConfigDict() >>> c.load_dict({'some': {'namespace': {'key': 'value'} } }) {'some.namespace.key': 'value'}
- update(*a, **ka)[source]¶
If the first parameter is a string, all keys are prefixed with this namespace. Apart from that it works just as the usual dict.update().
>>> c = ConfigDict() >>> c.update('some.namespace', key='value')
- setdefault(key, value=None)[source]¶
Insert key with a value of default if key is not in the dictionary.
Return the value for key if key is in the dictionary, else default.
- class MultiDict[source]¶
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.
- get(key, default=None, index=-1, type=None)[source]¶
Return the most recent value for a key.
- Parameters:
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.
- getone(key, default=None, index=-1, type=None)¶
Aliases for WTForms to mimic other multi-dict APIs (Django)
- getlist(key)¶
Return a (possibly empty) list of values for a key.
- class WSGIHeaderDict[source]¶
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.)
- cgikeys = ('CONTENT_TYPE', 'CONTENT_LENGTH')¶
List of keys that do not have a
HTTP_
prefix.
- class HeaderDict[source]¶
A case-insensitive version of
MultiDict
that defaults to replace the old value instead of appending it.- get(key, default=None, index=-1)[source]¶
Return the most recent value for a key.
- Parameters:
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.
- class FormsDict[source]¶
This
MultiDict
subclass is used to store request form data. Additionally to the normal dict-like item access methods (which return unmodified data as native strings), this container also supports attribute-like access to its values. Attributes are automatically de- or recoded to matchinput_encoding
(default: ‘utf8’). Missing attributes default to an empty string.- input_encoding = 'utf8'¶
Encoding used for attribute values.
- recode_unicode = True¶
If true (default), unicode strings are first encoded with latin1 and then decoded to match
input_encoding
.
- decode(encoding=None)[source]¶
Returns a copy with all keys and values de- or recoded to match
input_encoding
. Some libraries (e.g. WTForms) want a unicode dictionary.
- class FileUpload[source]¶
- __init__(fileobj, name, filename, headers=None)[source]¶
Wrapper for a single file uploaded via
multipart/form-data
.
- file¶
Open file(-like) object (BytesIO buffer or temporary file)
- name¶
Name of the upload form field
- raw_filename¶
Raw filename as sent by the client (may contain unsafe characters)
- headers¶
A
HeaderDict
with additional headers (e.g. content-type)
- content_type¶
Current value of the ‘Content-Type’ header.
- content_length¶
Current value of the ‘Content-Length’ header.
- filename()[source]¶
Name of the file on the client file system, but normalized to ensure file system compatibility. An empty filename is returned as ‘empty’.
Only ASCII letters, digits, dashes, underscores and dots are allowed in the final filename. Accents are removed, if possible. Whitespace is replaced by a single dash. Leading or tailing dots or dashes are removed. The filename is limited to 255 characters.
- save(destination, overwrite=False, chunk_size=65536)[source]¶
Save file to disk or copy its content to an open file(-like) object. If destination is a directory,
filename
is added to the path. Existing files are not overwritten by default (IOError).- Parameters:
destination – File path, directory or file(-like) object.
overwrite – If True, replace existing files. (default: False)
chunk_size – Bytes to read at a time. (default: 64kb)
Request routing¶
- class Router[source]¶
A Router is an ordered collection of route->target pairs. It is used to efficiently match WSGI requests against a number of routes and return the first target that satisfies the request. The target may be anything, usually a string, ID or callable object. A route consists of a path-rule and a HTTP method.
The path-rule is either a static path (e.g. /contact) or a dynamic path that contains wildcards (e.g. /wiki/<page>). The wildcard syntax and details on the matching order are described in docs:routing.
- strict_order¶
If true, static routes are no longer checked first.
- add_filter(name, func)[source]¶
Add a filter. The provided function is called with the configuration string as parameter and must return a (regexp, to_python, to_url) tuple. The first element is a string, the last two are callables or None.
- class Route[source]¶
This class wraps a route callback along with route specific metadata and configuration and applies Plugins on demand. It is also responsible for turning an URL path rule into a regular expression usable by the Router.
- app¶
The application this route is installed to.
- rule¶
The path-rule string (e.g.
/wiki/<page>
).
- method¶
The HTTP method as a string (e.g.
GET
).
- callback¶
The original callback with no plugins applied. Useful for introspection.
- name¶
The name of the route (if specified) or
None
.
- plugins¶
A list of route-specific plugins (see
Bottle.route()
).
- skiplist¶
A list of plugins to not apply to this route (see
Bottle.route()
).
- config¶
Additional keyword arguments passed to the
Bottle.route()
decorator are stored in this dictionary. Used for route-specific plugin configuration and meta-data.
- call()[source]¶
The route callback with all plugins applied. This property is created on demand and then cached to speed up subsequent requests.
- reset()[source]¶
Forget any cached values. The next time
call
is accessed, all plugins are re-applied.
- get_undecorated_callback()[source]¶
Return the callback. If the callback is a decorated function, try to recover the original function.
Templating¶
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.
- class BaseTemplate[source]¶
Base class and minimal API for template adapters
- __init__(source=None, name=None, lookup=None, encoding='utf8', **settings)[source]¶
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.
- classmethod search(name, lookup=None)[source]¶
Search name in all directories specified in lookup. First without, then with common extensions. Return first hit.
- classmethod global_config(key, *args)[source]¶
This reads or sets the global settings stored in class.settings.
- prepare(**options)[source]¶
Run preparations (parsing, caching, …). It should be possible to call this again to refresh a template or to update settings.
- render(*args, **kwargs)[source]¶
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).
- view(tpl_name, **defaults)[source]¶
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.
- template(*args, **kwargs)[source]¶
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).
- TEMPLATE_PATH = ['./', './views/']¶
Built-in mutable sequence.
If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
Global search path for templates.
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
HTTP utilities¶
- parse_auth(header)[source]¶
Parse rfc2617 HTTP authentication header string (basic) and return (user,pass) tuple or None
- cookie_encode(data, key, digestmod=None)[source]¶
Encode and sign a pickle-able object. Return a (byte) string
- cookie_decode(data, key, digestmod=None)[source]¶
Verify and decode an encoded string. Return an object or None.
- path_shift(script_name, path_info, shift=1)[source]¶
Shift path fragments from PATH_INFO to SCRIPT_NAME and vice versa.
- Returns:
The modified paths.
- Parameters:
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)
- HTTP_CODES¶
A dict to map HTTP status codes (e.g. 404) to phrases (e.g. ‘Not Found’)
Misc utilities¶
- class DictProperty[source]¶
Property that maps to a key in a local dict-like attribute.
- __new__(**kwargs)¶
- class cached_property[source]¶
A property that is only computed once per instance and then replaces itself with an ordinary attribute. Deleting the attribute resets the property.
- __new__(**kwargs)¶
- yieldroutes(func)[source]¶
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>'
- load(target, **namespace)[source]¶
Import a module or fetch an object from a module.
package.module
returns module as a module object.pack.mod:name
returns the module variable name from pack.mod.pack.mod:func()
calls pack.mod.func() and returns the result.
The last form accepts not only function calls, but any type of expression. Keyword arguments passed to this function are available as local variables. Example:
import_string('re:compile(x)', x='[a-z]')