API 参考

Bottle 以其易于阅读和遵循的源代码而自豪，因此大多数关于 API 或内部工作原理的问题都可以通过检查源代码来快速回答。您的 IDE 应该能提供与本页相同的信息，因为其中大部分内容都是自动从 docstrings 和方法签名生成的。如果您是 Bottle 的新手，可能会发现 User’s Guide 更适合作为起点。

全局函数

该模块定义了几个函数、常量和一个异常。

app()

default_app()

返回当前的 Structuring Applications。这实际上是 AppStack 的一个可调用实例。

debug(mode=True)

更改调试级别。目前只支持一个调试级别。

install(self, plugin)

将插件添加到插件列表，并准备将其应用于此应用程序的所有路由。插件可以是一个简单的装饰器，也可以是实现了 Plugin API 的对象。

uninstall(self, plugin)

卸载插件。传递一个实例来删除特定插件，传递一个类型对象来删除所有匹配该类型的插件，传递一个字符串来删除所有具有匹配 name 属性的插件，或传递 True 来删除所有插件。返回被删除插件的列表。

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)

启动一个服务器实例。此方法会阻塞直到服务器终止。

参数：

• app – load_app() 支持的 WSGI 应用程序或目标字符串。(默认: default_app())

• server – 要使用的服务器适配器。有效名称请参阅 server_names 键，或传递 ServerAdapter 子类。(默认: wsgiref)

• host – 服务器绑定的地址。传递 0.0.0.0 以监听包括外部接口在内的所有接口。(默认: 127.0.0.1)

• port – 服务器绑定的端口。小于 1024 的值需要 root 权限。(默认: 8080)

• reloader – 启动自动重新加载服务器？(默认: False)

• interval – 自动重新加载器间隔，单位为秒 (默认: 1)

• quiet – 禁止输出到标准输出和标准错误？(默认: False)

• options – 传递给服务器适配器的选项。

全局装饰器

Bottle 维护一个 Bottle 实例栈 (参见 app() 和 AppStack)，并使用栈顶作为 Structuring Applications，用于一些模块级函数和装饰器。所有这些在 Bottle 类上都有对应的方法。

route(path, method='GET', callback=None, **options)

get(...)

post(...)

put(...)¶

delete(...)

patch(...)

用于在当前默认应用程序中安装路由的装饰器。详情请参阅 Bottle.route()。

error(...)

用于在当前默认应用程序中安装错误处理程序的装饰器。详情请参阅 Bottle.error()。

hook(self, name)

返回一个将回调附加到钩子上的装饰器。详情请参阅 add_hook()。

请求上下文

全局的 request 和 response 实例只在请求处理函数内部有效，表示当前的 HTTP 请求或响应。

request = <LocalRequest: GET http://127.0.0.1/>

LocalRequest 的一个线程安全实例。如果在请求回调函数内部访问，此实例始终指向当前请求（即使在多线程服务器上也是如此）。

response = Content-Type: text/html; charset=UTF-8

LocalResponse 的一个线程安全实例。用于更改当前请求的 HTTP 响应。

辅助函数

abort(code=500, text='Unknown Error.')

中止执行并引发 HTTP 错误。

redirect(url, code=None)

中止执行并根据 HTTP 协议版本引发 303 或 302 重定向。

static_file(filename, root, mimetype=True, download=False, charset='UTF-8', etag=None, headers=None)

以安全的方式打开文件并返回可发送给客户端的 HTTPResponse 实例。

参数：

• filename – 要发送的文件名或路径，相对于 root。

• root – 文件查找的根路径。应为绝对目录路径。

• mimetype – 提供 content-type 头部 (默认: 从文件扩展名猜测)

• download – 如果为 True，则要求浏览器打开 Save as… 对话框，而不是使用关联程序打开文件。您可以指定一个字符串作为自定义文件名。如果未指定，则使用原始文件名 (默认: False)。

• charset – text/* mime 类型文件的字符集。(默认: UTF-8)

• etag – 提供预先计算的 ETag 头部。如果设置为 False，则禁用 ETag 处理。(默认: 自动生成 ETag 头部)

• headers – 要添加到响应中的附加头部字典。

虽然检查用户输入始终是个好主意，但此函数提供额外的保护，防止恶意 filename 参数突破 root 目录并向攻击者泄露敏感信息。

受保护的文件或 root 目录外部的文件将响应 403 Access Denied。缺失的文件将导致 404 Not Found 响应。条件请求 (If-Modified-Since, If-None-Match) 会尽可能响应 304 Not Modified。 HEAD 和 Range 请求 (下载管理器用于检查或继续部分下载) 也会自动处理。

异常

exception BottleException

Bottle 使用的异常基类。

exception HTTPResponse

Response 的子类，可以从请求处理程序中引发或返回，以中断请求处理并覆盖对全局 request 对象所做的更改。即使状态码表示错误，这也会绕过错误处理程序。返回或引发 HTTPError 以触发错误处理程序。

__init__(body='', status=None, headers=None, **more_headers)

创建一个新的响应对象。

参数：

• body – 作为支持类型之一的响应正文。

• status – HTTP 状态码（例如 200）或包含原因短语的状态行（例如 ‘200 OK’）。

• headers – 字典或名称-值对列表。

其他关键字参数将添加到头部列表中。头部名称中的下划线会被替换为短划线。

apply(other)

将此响应的状态复制到另一个 Response 对象。

exception HTTPError

HTTPResponse 的子类，用于触发错误处理程序。

__init__(status=None, body=None, exception=None, traceback=None, **more_headers)

创建一个新的响应对象。

参数：

• body – 作为支持类型之一的响应正文。

• status – HTTP 状态码（例如 200）或包含原因短语的状态行（例如 ‘200 OK’）。

• headers – 字典或名称-值对列表。

其他关键字参数将添加到头部列表中。头部名称中的下划线会被替换为短划线。

Bottle 类

class Bottle

每个 Bottle 对象代表一个独立的 Web 应用程序，包含路由、回调、插件、资源和配置。实例是可调用的 WSGI 应用程序。

参数：

catchall – 如果为 true（默认），处理所有异常。关闭则让调试中间件处理异常。

__init__(**kwargs)

config

用于应用程序特定配置的 ConfigDict。

resources

应用程序文件的 ResourceManager

catchall

如果为 true，大多数异常将被捕获并作为 HTTPError 返回

add_hook(name, func)

将回调附加到钩子。目前实现了三个钩子

before_request

在每个请求之前执行一次。请求上下文可用，但尚未进行路由。

after_request

在每个请求之后执行一次，无论其结果如何。

app_reset

每当调用 Bottle.reset() 时调用。

remove_hook(name, func)

从钩子中移除回调。

trigger_hook(_Bottle__name, *args, **kwargs)

触发钩子并返回结果列表。

hook(name)

返回一个将回调附加到钩子上的装饰器。详情请参阅 add_hook()。

mount(prefix, app, **options)

将应用程序 (Bottle 或普通 WSGI) 挂载到特定的 URL 前缀。示例

parent_app.mount('/prefix/', child_app)

参数：

• prefix – 路径前缀或挂载点。

• app – Bottle 实例或 WSGI 应用程序。

父应用程序的插件不会应用于挂载的子应用程序的路由。如果子应用程序需要插件，请单独安装。

虽然可以在前缀路径中使用路径通配符（仅限 Bottle 子应用程序），但强烈不建议这样做。

前缀路径必须以斜杠结尾。如果您想通过 /prefix 以及 /prefix/ 访问子应用程序的根目录，请考虑在父应用程序中添加一个包含 307 重定向的路由。

merge(routes)

将另一个 Bottle 应用程序的路由或 Route 对象列表合并到此应用程序。这些路由保留其‘所有者’，这意味着 Route.app 属性不会更改。

install(plugin)

将插件添加到插件列表，并准备将其应用于此应用程序的所有路由。插件可以是一个简单的装饰器，也可以是实现了 Plugin API 的对象。

uninstall(plugin)

卸载插件。传递一个实例来删除特定插件，传递一个类型对象来删除所有匹配该类型的插件，传递一个字符串来删除所有具有匹配 name 属性的插件，或传递 True 来删除所有插件。返回被删除插件的列表。

reset(route=None)

重置所有路由（强制重新应用插件）并清除所有缓存。如果给定 ID 或路由对象，则只影响该特定路由。

close()

关闭应用程序和所有已安装的插件。

run(**kwargs)

使用相同的参数调用 run()。

match(environ)

搜索匹配的路由并返回 (Route, urlargs) 元组。第二个值是从 URL 中提取的参数字典。不匹配时引发 HTTPError (404/405)。

get_url(routename, **kargs)

返回匹配命名路由的字符串

add_route(route)

添加路由对象，但不更改 Route.app 属性。

route(path=None, method='GET', callback=None, name=None, apply=None, skip=None, **config)

将函数绑定到请求 URL 的装饰器。示例

@app.route('/hello/<name>')
def hello(name):
    return 'Hello %s' % name

<name> 部分是通配符。语法详情请参阅 Router。

参数：

• path – 要监听的请求路径或路径列表。如果未指定路径，则自动从函数签名生成。

• method – 要监听的 HTTP 方法（GET, POST, PUT, …）或方法列表。(默认: GET)

• callback – 避免装饰器语法的可选快捷方式。route(..., callback=func) 等同于 route(...)(func)

• name – 此路由的名称。(默认: None)

• apply – 装饰器、插件或插件列表。除了已安装的插件外，这些也会应用于路由回调。

• skip – 插件、插件类或名称的列表。匹配的插件不会安装到此路由。True 跳过所有插件。

任何附加关键字参数都将作为路由特定配置存储并传递给插件（参见 Plugin.apply()）。

get(path=None, method='GET', **options)

等同于 route()。

post(path=None, method='POST', **options)

等同于 method 参数为 POST 的 route()。

put(path=None, method='PUT', **options)

等同于 method 参数为 PUT 的 route()。

delete(path=None, method='DELETE', **options)

等同于 method 参数为 DELETE 的 route()。

patch(path=None, method='PATCH', **options)

等同于 method 参数为 PATCH 的 route()。

error(code=500, callback=None)

注册 HTTP 错误码的输出处理程序。可用作装饰器或直接调用

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'

wsgi(environ, start_response)

Bottle WSGI 接口。

Request 对象

Request 类封装了 WSGI 环境，并提供了有用的方法来解析和访问表单数据、cookies、文件上传和其他元数据。大多数属性是只读的。

Request

BaseRequest 的别名

class BaseRequest

WSGI 环境字典的包装器，添加了许多方便的访问方法和属性。大多数是只读的。

向请求添加新属性实际上是将其添加到 environ 字典中（作为 ‘bottle.request.ext.’）。这是存储和访问请求特定数据的推荐方法。

MEMFILE_MAX = 102400

body 内存缓冲区的最大大小，单位为字节。

__init__(environ=None)

包装一个 WSGI environ 字典。

environ

包装的 WSGI environ 字典。这是唯一真正的属性。所有其他属性实际上都是只读属性。

app

处理此请求的 Bottle 应用程序。

route

匹配此请求的 Bottle Route 对象。

url_args

从 URL 中提取的参数。

property path

PATH_INFO 的值，恰好带有一个前导斜杠（用于修复损坏的客户端并避免“空路径”边缘情况）。

property method

REQUEST_METHOD 值，为大写字符串。

headers

一个 WSGIHeaderDict，提供对 HTTP 请求头部的忽略大小写访问。

get_header(name, default=None)

返回请求头部的值，或给定的默认值。

cookies

解析到 FormsDict 中的 Cookies。签名 cookies 未解码。如果期望签名 cookies，请使用 get_cookie()。

get_cookie(key, default=None, secret=None, digestmod=<built-in function openssl_sha256>)

返回 cookie 的内容。要读取签名 Cookie，secret 必须与创建 cookie 时使用的密钥匹配（参见 Response.set_cookie）。如果出现任何问题（cookie 缺失或签名错误），则返回默认值。

query

解析到 FormsDict 中的 query_string。这些值有时被称为“URL 参数”或“GET 参数”，但不要与 Router 提供的“URL 通配符”混淆。

forms

从 url-encoded 或 multipart/form-data 编码的 POST 或 PUT 请求正文中解析的表单值。结果作为 FormsDict 返回。所有键和值都是字符串。文件上传单独存储在 files 中。

params

包含 query 和 forms 组合值的 FormsDict。文件上传存储在 files 中。

files

从 multipart/form-data 编码的 POST 或 PUT 请求正文中解析的文件上传。这些值是 FileUpload 的实例。

json

如果 Content-Type 头部是 application/json 或 application/json-rpc，此属性保存请求正文的解析内容。只有小于 MEMFILE_MAX 的请求才会被处理，以避免内存耗尽。无效的 JSON 会引发 400 错误响应。

property body

HTTP 请求正文，作为可查找的文件类对象。取决于 MEMFILE_MAX，这可能是一个临时文件或 io.BytesIO 实例。首次访问此属性会读取并替换 wsgi.input environ 变量。后续访问只是对此文件对象执行 seek(0)。

property chunked

如果使用了 Chunked transfer encoding，则为 True。

GET

query 的别名。

POST

将 forms 和 files 的值合并到一个 FormsDict 中。值可以是字符串（表单值）或 FileUpload 的实例。

property url

完整的请求 URI，包括主机名和方案。如果您的应用程序位于反向代理或负载均衡器之后，并且结果令人困惑，请确保 X-Forwarded-Host 头部已正确设置。

urlparts

url 字符串，作为 urlparse.SplitResult 元组。该元组包含 (scheme, host, path, query_string 和 fragment)，但由于 fragment 对服务器不可见，因此总是为空。

property fullpath

请求路径，包括 script_name（如果存在）。

property query_string

URL 的原始 query 部分（? 和 # 之间的所有内容），为字符串。

property script_name

URL 路径中在调用应用程序之前被更高层（服务器或路由中间件）移除的初始部分。此脚本路径返回时带有前导和尾随斜杠。

path_shift(shift=1)

将路径段从 path 转移到 script_name，并

反之亦然。

参数：

shift – 要转移的路径段数量。可以为负数以改变转移方向。(默认: 1)

property content_length

请求正文长度，为整数。客户端负责设置此头部。否则，正文的实际长度未知，返回 -1。在这种情况下，body 将为空。

property content_type

Content-Type 头部，为小写字符串（默认: 空）。

property is_xhr

如果请求由 XMLHttpRequest 触发，则为 True。这只适用于支持 X-Requested-With 头部（大多数流行的库都支持）的 JavaScript 库。

property is_ajax

is_xhr 的别名。“Ajax”不是正确的术语。

property auth

HTTP 认证数据，为 (user, password) 元组。此实现目前只支持基本认证（非摘要认证）。如果认证发生在更高层（例如前端 web 服务器或中间件），则 password 字段为 None，但 user 字段会从 REMOTE_USER environ 变量中查找。发生任何错误时，返回 None。

property remote_route

参与此请求的所有 IP 列表，始于客户端 IP，后跟零个或多个代理。这仅在所有代理都支持 `X-Forwarded-For 头部时才有效。请注意，此信息可能被恶意客户端伪造。

property remote_addr

客户端 IP，为字符串。请注意，此信息可能被恶意客户端伪造。

copy()

返回一个新的 Request，其中 environ 是浅拷贝。

__setattr__(name, value)

定义绑定请求环境本地的新属性。

class LocalRequest

BaseRequest 的一个线程局部子类，每个线程具有不同的属性集。通常只有一个此类的全局实例 (request)。如果在请求/响应周期中访问，此实例始终指向当前请求（即使在多线程服务器上也是如此）。

bind(environ=None)

包装一个 WSGI environ 字典。

environ

包装的 WSGI environ 字典。这是唯一真正的属性。所有其他属性实际上都是只读属性。

Response 对象

Response 类存储 HTTP 状态码以及要发送给客户端的头部和 cookies。与 bottle.request 类似，存在一个线程局部 bottle.response 实例，可用于调整当前响应。此外，您可以实例化 Response 并从请求处理程序中返回。在这种情况下，自定义实例将覆盖全局实例中定义的头部和 cookies。

Response

BaseResponse 的别名

class BaseResponse

用于存储响应正文以及头部和 cookies 的类。

此类支持类似字典的忽略大小写项访问头部，但不是字典。最值得注意的是，遍历响应会产生正文的部分内容，而不是头部。

__init__(body='', status=None, headers=None, **more_headers)

创建一个新的响应对象。

参数：

• body – 作为支持类型之一的响应正文。

• status – HTTP 状态码（例如 200）或包含原因短语的状态行（例如 ‘200 OK’）。

• headers – 字典或名称-值对列表。

其他关键字参数将添加到头部列表中。头部名称中的下划线会被替换为短划线。

copy(cls=None)

返回自身的副本。

property status_line

HTTP 状态行，为字符串（例如 404 Not Found）。

property status_code

HTTP 状态码，为整数（例如 404）。

property status

一个可写属性，用于更改 HTTP 响应状态。它接受数字代码 (100-999) 或带有自定义原因短语的字符串（例如“404 Brain not found”）。status_line 和 status_code 都会相应更新。返回值始终是状态字符串。

property headers

HeaderDict 的一个实例，它是对响应头部的忽略大小写类似字典的视图。

get_header(name, default=None)

返回之前定义的头部的值。如果不存在该名称的头部，则返回默认值。

set_header(name, value)

创建一个新的响应头，替换任何之前定义的同名头。

add_header(name, value)

添加一个额外的响应头，不删除重复项。

iter_headers()

生成 (header, value) 元组，跳过当前响应状态码不允许的头。

property headerlist

符合 WSGI 规范的 (header, value) 元组列表。

content_type

‘Content-Type’ 头部当前值。

content_length

‘Content-Length’ 头部当前值。

expires

‘Expires’ 头部当前值。

property charset

返回 content-type 头中指定的字符集（默认：utf8）。

set_cookie(name, value, secret=None, digestmod=<built-in function openssl_sha256>, **options)

创建一个新 cookie 或替换旧 cookie。如果设置了 secret 参数，则创建一个 Signed Cookie（详情见下）。

参数：

• name – cookie 的名称。

• value – cookie 的值。

• secret – 签名 cookie 所需的签名密钥。

此外，此方法接受 cookie.Morsel 支持的所有 RFC 2109 属性，包括

参数：

• maxage – 最大生存期（秒）。（默认：None）

• expires – 一个 datetime 对象或 UNIX 时间戳。（默认：None）

• domain – 允许读取 cookie 的域名。（默认：当前域名）

• path – 将 cookie 限制在给定路径下（默认：当前路径）

• secure – 将 cookie 限制为 HTTPS 连接（默认：off）。

• httponly – 阻止客户端 JavaScript 读取此 cookie（默认：off，需要 Python 2.6 或更高版本）。

• samesite – 控制或禁用此 cookie 的第三方使用。可能的值：lax、strict 或 none（默认）。

如果未设置 expires 或 maxage（默认），则 cookie 将在浏览器会话结束时（浏览器窗口关闭时）过期。

签名 cookie 可以存储任何可 pickle 的对象，并经过加密签名以防止篡改。请记住，大多数浏览器中 cookie 的大小限制为 4kb。

警告：Pickle 是一种潜在危险的格式。如果攻击者获取了密钥，他可以伪造在服务器端反序列化时执行代码的 cookie。不推荐使用 pickle，并且在 Bottle 的后续版本中将移除对其的支持。

警告：签名 cookie 未加密（客户端仍然可以看到内容）且未受复制保护（客户端可以恢复旧的 cookie）。主要目的是确保 pickle 和 unpickle 的安全，而不是在客户端存储机密信息。

delete_cookie(key, **kwargs)

删除 cookie。请确保使用与创建 cookie 时相同的 domain 和 path 设置。

class LocalResponse

BaseResponse 的线程本地子类，每个线程有一组不同的属性。通常只有一个此类的全局实例（response）。其属性用于在请求/响应周期的末尾构建 HTTP 响应。

bind(body='', status=None, headers=None, **more_headers)

创建一个新的响应对象。

参数：

• body – 作为支持类型之一的响应正文。

• status – HTTP 状态码（例如 200）或包含原因短语的状态行（例如 ‘200 OK’）。

• headers – 字典或名称-值对列表。

其他关键字参数将添加到头部列表中。头部名称中的下划线会被替换为短划线。

property body

线程本地属性

数据结构

class AppStack

一个栈式列表。调用它会返回栈顶元素。

pop()

返回当前默认应用程序并将其从栈中移除。

push(value=None)

向栈中添加一个新的 Bottle 实例

new_app(value=None)

向栈中添加一个新的 Bottle 实例

class ConfigDict

一个类似 dict 的配置存储，额外支持命名空间、验证器、元数据和覆盖。

这个类似 dict 的类针对读取访问进行了高度优化。只读方法和项访问应该与原生 dict 一样快。

__init__()

load_module(name, squash=True)

从 Python 模块加载值。

按名称导入一个 python 模块，并将所有大写的模块级变量添加到此配置 dict 中。

参数：

• name – 要导入和加载的模块名称。

• squash – 如果为 True（默认），则假设嵌套的 dict 代表命名空间并将其展平（参见 load_dict()）。

load_config(filename, **options)

使用 configparser 从 *.ini 样式配置文件加载值。

INI 样式的小节（例如 [section]）用作该小节内所有键的命名空间。小节名称和键名称都可以包含点作为命名空间分隔符，并转换为小写。

特殊小节 [bottle] 和 [ROOT] 指的是根命名空间，而 [DEFAULT] 小节为所有其他小节定义默认值。

参数：

• filename – 配置文件的路径，或路径列表。

• options – 所有关键字参数都传递给底层的 configparser.ConfigParser 构造函数调用。

load_dict(source, namespace='')

从字典结构加载值。可以使用嵌套来表示命名空间。

>>> c = ConfigDict()
>>> c.load_dict({'some': {'namespace': {'key': 'value'} } })
{'some.namespace.key': 'value'}

update(*a, **ka)

如果第一个参数是字符串，所有键都将以此命名空间作为前缀。除此之外，它的工作方式与普通的 dict.update() 完全相同。

>>> c = ConfigDict()
>>> c.update('some.namespace', key='value')

setdefault(key, value=None)

如果键不在字典中，则插入键，值为默认值。

如果键在字典中，则返回键对应的值，否则返回默认值。

meta_get(key, metafield, default=None)

返回键的元字段值。

meta_set(key, metafield, value)

将键的元字段设置为新值。

元字段在覆盖树的所有成员之间共享。

meta_list(key)

返回为键定义的元字段名称的可迭代对象。

class MultiDict

这个 dict 为每个键存储多个值，但行为与普通 dict 完全相同，因为它只返回任何给定键的最新值。有特殊方法可以访问值的完整列表。

__init__(*a, **k)

keys() → a set-like object providing a view on D's keys

values() → an object providing a view on D's values

items() → a set-like object providing a view on D's items

iterkeys()

D.keys() -> 一个提供 D 的键视图的类似集合的对象

itervalues()

D.values() -> 一个提供 D 的值视图的对象

iteritems()

D.items() -> 一个提供 D 的项视图的类似集合的对象

get(key, default=None, index=-1, type=None)

返回键的最新值。

参数：

• default – 如果键不存在或类型转换失败时返回的默认值。

• index – 可用值列表的索引。

• type – 如果已定义，则使用此可调用对象将值转换为特定类型。异常会被抑制，结果将返回默认值。

append(key, value)

为此键的值列表添加一个新值。

replace(key, value)

用单个值替换值列表。

getall(key)

返回键的值列表（可能为空）。

getone(key, default=None, index=-1, type=None)

WTForms 的别名，用于模仿其他多值字典 API (Django)

getlist(key)

返回键的值列表（可能为空）。

class WSGIHeaderDict

这个类似 dict 的类封装了 WSGI environ dict，并提供了对 HTTP_* 字段的便捷访问。头名称不区分大小写，默认情况下会进行首字母大写处理。

cgikeys = ('CONTENT_TYPE', 'CONTENT_LENGTH')

没有 HTTP_ 前缀的键列表。

__init__(environ)

raw(key, default=None)

按原样返回头值（未进行 utf8 转换）。

keys() → a set-like object providing a view on D's keys

class HeaderDict

一个不区分大小写的 MultiDict 版本，默认行为是替换旧值而不是追加。

__init__(*a, **ka)

append(key, value)

为此键的值列表添加一个新值。

replace(key, value)

用单个值替换值列表。

getall(key)

返回键的值列表（可能为空）。

get(key, default=None, index=-1)

返回键的最新值。

参数：

• default – 如果键不存在或类型转换失败时返回的默认值。

• index – 可用值列表的索引。

• type – 如果已定义，则使用此可调用对象将值转换为特定类型。异常会被抑制，结果将返回默认值。

class FormsDict

这个 MultiDict 子类用于存储请求表单数据。除了普通的类似 dict 的项访问方法外，此容器还支持属性式访问其值。缺失属性默认为空字符串。

在 0.14 版本中改变: 所有键和值现在默认解码为 utf8，项和属性访问将返回相同的字符串。

decode(encoding=None)

（已弃用）从 0.13 版本开始，所有键和值都已正确解码。

getunicode(name, default=None, encoding=None)

（已弃用）将值作为 unicode 字符串返回，如果不存在则返回默认值。

class FileUpload

__init__(fileobj, name, filename, headers=None)

通过 multipart/form-data 上传单个文件的包装器。

file

打开文件（或类似文件）对象（BytesIO 缓冲区或临时文件）

name

上传表单字段的名称

raw_filename

客户端发送的原始文件名（可能包含不安全字符）

headers

一个包含额外头（例如 content-type）的 HeaderDict

content_type

‘Content-Type’ 头部当前值。

content_length

‘Content-Length’ 头部当前值。

get_header(name, default=None)

返回 multipart 部分内的头值。

filename()

客户端文件系统上的文件名，但已规范化以确保文件系统兼容性。空文件名返回为 'empty'。

最终文件名中只允许 ASCII 字母、数字、破折号、下划线和点。如果可能，会移除重音符号。空格会被单个破折号替换。开头的或结尾的点或破折号会被移除。文件名限制为 255 个字符。

save(destination, overwrite=False, chunk_size=65536)

将文件保存到磁盘或将其内容复制到打开的文件（或类似文件）对象。如果 destination 是一个目录，filename 会添加到路径中。默认情况下，现有文件不会被覆盖（会引发 IOError）。

参数：

• destination – 文件路径、目录或文件（或类似文件）对象。

• overwrite – 如果为 True，则替换现有文件。（默认：False）

• chunk_size – 每次读取的字节数。（默认：64kb）

请求路由

class Router

Router 是一个有序的路由->目标集合。它用于高效地将 WSGI 请求与多个路由匹配，并返回满足请求的第一个目标。目标可以是任何东西，通常是一个字符串、ID 或可调用对象。一个路由由一个路径规则和一个 HTTP 方法组成。

路径规则可以是静态路径（例如 /contact）或包含通配符的动态路径（例如 /wiki/<page>）。通配符语法和匹配顺序的详细信息在 docs:routing 中描述。

__init__(strict=False)

strict_order

如果为 True，则不再首先检查静态路由。

add_filter(name, func)

添加一个过滤器。提供的函数将以配置字符串作为参数调用，并且必须返回一个 (regexp, to_python, to_url) 元组。第一个元素是字符串，后两个是可调用对象或 None。

add(rule, method, target, name=None)

添加新规则或替换现有规则的目标。

build(_name, *anons, **query)

通过填充规则中的通配符来构建 URL。

match(environ)

返回一个 (target, url_args) 元组或引发 HTTPError(400/404/405)。

class Route

此类别封装了路由回调以及路由特定的元数据和配置，并按需应用插件。它还负责将 URL 路径规则转换为 Router 可用的正则表达式。

__init__(app, rule, method, callback, name=None, plugins=None, skiplist=None, **config)

app

安装此路由的应用程序。

rule

路径规则字符串（例如 /wiki/<page>）。

method

HTTP 方法的字符串表示（例如 GET）。

callback

未应用任何插件的原始回调。对于内省很有用。

name

路由的名称（如果指定）或 None。

plugins

一个路由特定插件列表（参见 Bottle.route()）。

skiplist

不应用于此路由的插件列表（参见 Bottle.route()）。

config

传递给 Bottle.route() 装饰器的额外关键字参数存储在此字典中。用于路由特定的插件配置和元数据。

call()

应用了所有插件的路由回调。此属性按需创建，然后缓存以加速后续请求。

reset()

忘记任何缓存值。下次访问 call 时，将重新应用所有插件。

prepare()

立即执行所有按需工作（对于调试很有用）。

all_plugins()

生成影响此路由的所有插件。

get_undecorated_callback()

返回回调。如果回调是装饰函数，尝试恢复原始函数。

get_callback_args()

返回回调（很可能）接受作为关键字参数的参数名称列表。如果回调是装饰函数，在检查之前尝试恢复原始函数。

get_config(key, default=None)

查找配置字段并返回其值，首先检查 route.config，然后检查 route.app.config。

模板化

bottle 支持的所有模板引擎都实现了 BaseTemplate API。这样就可以在不改变应用程序代码的情况下切换和混合模板引擎。

class BaseTemplate

模板适配器的基类和最小 API

__init__(source=None, name=None, lookup=None, encoding='utf8', **settings)

创建一个新模板。如果 source 参数（str 或 buffer）缺失，则使用 name 参数猜测模板文件名。子类可以假定 self.source 和/或 self.filename 已设置。两者都是字符串。lookup、encoding 和 settings 参数作为实例变量存储。lookup 参数存储包含目录路径的列表。encoding 参数应用于解码字节字符串或文件。settings 参数包含一个用于引擎特定设置的 dict。

classmethod search(name, lookup=None)

在 lookup 中指定的所有目录中搜索 name。首先不带常见扩展名搜索，然后带常见扩展名搜索。返回第一个匹配项。

classmethod global_config(key, *args)

此方法读取或设置存储在 class.settings 中的全局设置。

prepare(**options)

运行准备工作（解析、缓存等）。应该可以再次调用此方法以刷新模板或更新设置。

render(*args, **kwargs)

使用指定的局部变量渲染模板，并返回单个字节字符串或 unicode 字符串。如果是字节字符串，编码必须与 self.encoding 匹配。此方法必须是线程安全的！局部变量可以通过字典 (args) 或直接作为关键字参数 (kwargs) 提供。

view(tpl_name, **defaults)

装饰器：为处理函数渲染模板。处理函数可以这样控制其行为

• 返回一个模板变量字典来填充模板

• 返回字典以外的内容时，view 装饰器将不处理模板，而是按原样返回处理函数的结果。这包括返回 HTTPResponse(dict) 以获取（例如）使用 autojson 或其他 castfilters 的 JSON。

template(*args, **kwargs)

将渲染后的模板作为字符串迭代器获取。你可以将名称、文件名或模板字符串作为第一个参数。模板渲染参数可以通过字典或直接作为关键字参数传递。

TEMPLATE_PATH = ['./', './views/']

内置可变序列。

如果没有给出参数，构造函数会创建一个新的空列表。如果指定了参数，则参数必须是可迭代对象。

模板的全局搜索路径。

你可以为你喜欢的模板引擎编写自己的适配器，或使用预定义的适配器之一。目前有四种完全支持的模板引擎

类	URL	装饰器	渲染函数
SimpleTemplate	SimpleTemplate	view()	template()
MakoTemplate	http://www.makotemplates.org	mako_view()	mako_template()
CheetahTemplate	http://www.cheetahtemplate.org/	cheetah_view()	cheetah_template()
Jinja2Template	https://jinja.flask.org.cn/	jinja2_view()	jinja2_template()

要将 MakoTemplate 用作默认模板引擎，只需导入其专用的装饰器和渲染函数即可

from bottle import mako_view as view, mako_template as template

HTTP 工具

parse_date(ims)

解析 rfc1123、rfc850 和 asctime 时间戳并返回 UTC epoch。

parse_auth(header)

解析 rfc2617 HTTP 认证头字符串 (basic) 并返回 (user,pass) 元组或 None。

cookie_encode(data, key, digestmod=None)

编码并签名一个可 pickle 的对象。返回一个（字节）字符串。

cookie_decode(data, key, digestmod=None)

验证并解码编码后的字符串。返回一个对象或 None。

cookie_is_encoded(data)

如果参数看起来像一个编码的 cookie，则返回 True。

path_shift(script_name, path_info, shift=1)

将路径片段从 PATH_INFO 转移到 SCRIPT_NAME，反之亦然。

返回：

修改后的路径。

参数：

• script_name – SCRIPT_NAME 路径。

• path_info – PATH_INFO 路径。（注意：原文此处有误，应为 path_info）

• shift – 要转移的路径片段数量。可以是负数以改变转移方向。（默认：1）

HTTP_CODES

一个将 HTTP 状态码（例如 404）映射到短语（例如 ‘Not Found’）的字典。

杂项工具

class DictProperty

映射到本地类似 dict 属性中键的属性。

__init__(attr, key=None, read_only=False)

__new__(**kwargs)

class cached_property

一个属性，每个实例只计算一次，然后用普通属性替换自身。删除该属性会重置该属性。

__init__(func)

__new__(**kwargs)

class lazy_attribute

一个将自己缓存到类对象的属性。

__init__(func)

__new__(**kwargs)

yieldroutes(func)

为与 func 参数的签名 (name, args) 匹配的路由返回一个生成器。如果函数接受可选关键字参数，这可能会生成多个路由。输出通过示例可以最好地描述

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)

导入模块或从模块中获取对象。

• package.module 返回 module 作为模块对象。

• pack.mod:name 返回 pack.mod 中的模块变量 name。

• pack.mod:func() 调用 pack.mod.func() 并返回结果。

最后一种形式不仅接受函数调用，还接受任何类型的表达式。传递给此函数的关键字参数可作为局部变量使用。示例：import_string('re:compile(x)', x='[a-z]')

load_app(target)

从模块加载 Bottle 应用程序，并确保导入不会影响当前的默认应用程序，而是返回一个独立的应用程序对象。目标参数请参阅 load()。