发布说明

本项目大致遵循语义化版本控制（major.minor.patch），但有一个例外：只要更改是为了匹配文档、规范或预期行为，次要版本中允许进行更改。换句话说：错误修复不视为向后不兼容的更改，即使它们技术上将某些内容从不正确变为正确，并且可能破坏依赖于不正确、未定义或未文档化行为的应用程序。

只要主版本仍为0.x，次要版本中也允许引入破坏性API更改，但我们会尽最大努力提供备用方案，并在至少一个次要版本周期内发出弃用警告。

如何升级

  • 升级到当前次要版本的最新补丁版本。（例如，从0.12.3到0.12.25）

  • 阅读下一个次要版本的发布说明，运行测试并修复所有弃用警告。

  • 升级到下一个次要版本（例如，从0.12.25到0.13.2），再次运行测试，修复所有警告并继续。

对旧版本的支持

错误和安全问题通常在最近两个主版本（称为稳定版和旧稳定版）的最新次要版本中得到修复。每发布一个新主版本，稳定版变为旧稳定版，而之前的旧旧稳定版将不再接收定期更新。LTS 版本（如 0.12）是一个例外。它们将继续在尽力而为的基础上接收更新。

版本 0.14（开发中）

移除的 API

  • 放弃对 Python 2 的支持（生命周期结束：2020-01-01），并移除了仅在 Python 2/3 双重代码库中有意义的变通方法或助手。

  • 放弃对 Python 3.8 的支持（生命周期结束：2024-10-07）。

  • 移除RouteReset异常及其相关逻辑。

  • 移除bottle.py控制台脚本入口点，改为新的bottle脚本。您仍然可以直接执行bottle.py或通过python -m bottle执行。唯一的改变是，由 pip 或类似工具安装到（虚拟）环境的 bin/Scripts 文件夹中的命令现在名为bottle，以避免循环导入错误。

更改

  • 表单值、查询参数、路径元素和 Cookie 现在始终以utf8编码解码，使用参数为errors=’surrogateescape’。这对于几乎所有现代 Web 应用程序来说是正确的方法，但仍允许应用程序在需要时恢复原始字节序列。这也意味着bottle.FormsDict不再按需（通过属性访问）将 PEP-3333 的latin1字符串重新编码为utf8。FormsDict.getunicode()和FormsDict.decode()方法已弃用且不执行任何操作，因为所有值都已经转码为utf8。

新功能

  • 当 JSON 无效时引发的bottle.HTTPError现在会在exception字段中包含底层异常。

版本 0.13

警告

此版本包含破坏性更改，请阅读以下说明

放弃了对已达到生命周期结束的 Python 版本的支持。

Bottle 在 0.12 版本及之前支持了范围荒谬的 Python 版本（2.5 到 3.12），而维持对像 2.5 这样古老的 Python 版本的支持需要大量的变通方法和妥协，但实际上并没有什么必要。如果您需要对旧 Python 版本的支持，您可以保留在 bottle 0.12 版本。更新后的测试和支持的 Python 版本列表如下：

  • Python 2 >= 2.7.3

  • Python 3 >= 3.8

对 Python 2.5 的支持自 0.12 版本起已被标记为弃用。我们决定更进一步，即使 Bottle 中从未明确弃用 2.6 和 3.1 到 3.7 版本，也移除了对它们的支持。这意味着此版本在 Python <2.7.3 或 <3.8 的环境中是不向后兼容的。仍在这些旧 Python 版本上使用 Bottle 的发行版或系统维护者不应升级到 Bottle 0.13，而应坚持使用 0.12。

稳定的 API

  • 类的文档中记载的 API (ConfigDict) 现在被认为是稳定的，可以使用了。

弃用的 API

  • 对 Python 2 的支持现已弃用，并将在下一个版本中移除。这包括仅在 Python 2/3 双重代码库中有意义的助手和变通方法（例如tonat()或py3k标志）。

  • 与 Bottle 一起安装的命令行可执行文件将从bottle.py重命名为bottle。您仍然可以直接作为脚本执行 bottle（例如./bottle.py或python3 bottle.py），或作为模块执行（通过python3 -m bottle）。只有您的打包工具（例如pip）安装到您的（虚拟）环境的bin文件夹中的可执行文件会改变。

  • 旧的路由语法（/hello/:name）已弃用，取而代之的是更具可读性和灵活性的/hello/<name>语法。

  • Bottle.mount()现在识别 Bottle 实例，并将对与新挂载行为不兼容的参数发出警告。旧的行为（将应用程序挂载为 WSGI callable）仍然有效，并会自动用作备用方案。

  • 未文档化的local_property()助手现已弃用。

  • 用于 Google App Engine 的服务器适配器不再有用，并已被标记为弃用。

  • Bottle 使用 pickle 将任意对象存储到签名 Cookie 中。只要签名密钥保持秘密，这是安全的。不幸的是，人们倾向于随时将包含签名密钥的代码推送到 GitHub，因此我们决定从 Bottle 中移除 pickle 支持。如果值不是字符串，签名 Cookie 现在会发出弃用警告，对非字符串值的支持将在 0.14 中移除。全局函数cookie_encode()、cookie_decode()和is_cookie_encoded()现已弃用。如果您正在使用此功能，请考虑在将对象存储到 Cookie 中之前使用 JSON 进行序列化，或者切换到服务器端存储数据的会话系统而不是客户端。

移除的 API（自 0.12 起弃用）

  • 使用旧 API（api=1或没有 api 属性）的插件将不再工作。

  • Bottle.mount()的参数顺序在 0.10 中更改。旧的顺序现在将导致错误而不是警告。

  • ConfigDict类在 0.11 中引入，并在 0.12 期间进行了更改。这些更改现已最终确定。

    • 由于开销高且可用性有限，属性访问和赋值已被移除。

    • 命名空间子实例创建已被移除。config["a"]["b"]相对于config["a.b"]开销高且益处不大。

    • ConfigDict实例不再是 callable。这曾是ConfigDict.update()的快捷方式。

    • ConfigDict构造函数不再接受任何参数。请改用load_*方法。

  • Bottle 0.12 更改了 Simple Template Engine 的某些方面。这些更改现已最终确定，旧语法将不再有效。

    • 神奇的{{rebase()}}调用已被base变量替换。示例：{{base}}

    • 在 STPL 模板中，rebase和include关键字在 0.12 中被函数替换。

    • 不再识别 PEP-263 编码字符串。模板始终是 utf-8。

  • 在没有通知的情况下移除了 'geventSocketIO' 服务器适配器。反正它也不起作用。

更改

这些更改在更新时可能需要特别注意。

  • 签名 Cookie 现在默认使用更强的 HMAC 算法。这会导致旧 Cookie 在更新后显示为无效。请在调用Request.get_cookie和Response.set_cookie时显式传递digestmod=hashlib.md5以获得旧的行为。

  • Bottle 现在自带其 multipart 表单数据解析器（借用自multipart），不再依赖于在 Python 3.13 中移除的cgi.FieldStorage。这可能会改变解析损坏的（非标准）表单提交的方式。新的解析器比旧的更严格和准确。

  • 使用pip或类似工具安装 bottle 时，现在会在您的（虚拟）环境的bin文件夹中安装一个额外的命令行可执行文件，名为bottle。这将在后续版本中取代现已弃用的bottle.py可执行文件。详见上文。

其他改进

  • Bottle实例现在是上下文管理器。如果在 with 语句中使用，默认应用程序会变为特定实例，并且可以使用许多实例方法的快捷方式。

  • 添加了对PATCH请求和Bottle.patch()装饰器的支持。

  • 添加了aiohttp和uvloop服务器适配器。

  • 添加了从 JSON 或 INI 文件加载配置的命令行参数。

  • Bottle.mount()现在识别Bottle的实例，并以比其他 WSGI 应用程序显著更低的开销进行挂载。

  • Request.json属性现在接受application/json-rpc请求。

  • static_file()增加了对ETag头的支持。它将生成 ETag 并识别If-None-Match头。

  • static_file()现在会正确猜测*.gz和其他压缩文件（例如application/gzip）的 MIME 类型，并且不设置Content-Encoding头。

  • Jinja2 模板将生成比以前更好的错误消息。

版本 0.12

  • 新的 SimpleTemplate 解析器实现

    • 支持多行代码块（<% … %>）。

    • 关键字include和rebase现在是函数，可以接受变量模板名称。

  • 新的Request.route属性返回最初匹配请求的Route对象。

  • 移除了Request.MAX_PARAMS限制。CPython 的 dict() 实现中的哈希冲突错误在一年前就已修复。如果您仍然在生产环境中使用 Python 2.5，请考虑升级或至少确保您从发行商那里获得了安全修复。

  • 新的ConfigDict API（参见Configuration）

更多信息可以在这篇开发博客文章中找到。

版本 0.11

  • 原生支持 Python 2.x 和 3.x 语法。不再需要运行 2to3。

  • static_file()中支持部分下载（Range头）。

  • 新的ResourceManager接口帮助定位捆绑在应用程序中的文件。

  • 添加了waitress的服务器适配器。

  • 新的Bottle.merge()方法用于将一个应用程序的所有路由合并到另一个应用程序中。

  • 新的Request.app属性用于获取处理请求的应用程序对象。

  • 添加了FormsDict.decode()以获取完全 unicode 的版本（WTForms 需要）。

  • MultiDict及其子类现在可以 pickle。

API 更改

  • Response.status是一个读写属性，可以赋值数字状态码或带有原因短语的状态字符串（200 OK）。返回值现在是字符串，以更好地匹配现有 API（WebOb, werkzeug）。为了绝对明确，您可以使用只读属性Response.status_code和Response.status_line。

API 弃用

  • SimpleTALTemplate现已弃用。似乎没有需求。

版本 0.10

  • 插件 API v2

    • 要使用新 API，请将Plugin.api设置为2。

    • Plugin.apply()接收一个Route对象作为第二个参数，而不是上下文字典。新对象提供了一些额外信息，并且将来可能会扩展。

    • 插件名称现在被视为唯一的。在给定路由上，同名插件中最顶层的插件会被安装，所有其他同名插件将被静默忽略。

  • 请求/响应对象

  • 模板

    • 向 SimpleTemplate 默认命名空间添加了三个处理未定义变量的新函数：stpl.defined()、stpl.get()和stpl.setdefault()。

    • SimpleTemplate 的默认转义函数现在额外转义单引号和双引号。

  • 路由

    • 新的路由语法（例如/object/<id:int>）和路由通配符过滤器的支持。

    • 四种新的通配符过滤器：int、float、path和re。

  • 其他更改

    • 添加了命令行接口来加载应用程序和启动服务器。

    • 引入了ConfigDict，它使得访问配置更容易（属性访问和自动扩展命名空间）。

    • 添加了对Bottle.mount()支持原始 WSGI 应用程序。

    • Bottle.mount()参数顺序已更改。

    • Bottle.route()现在接受callback参数的导入字符串。

    • 放弃了 Gunicorn 0.8 的支持。当前支持的版本是 0.13。

    • 为 Gunicorn 服务器添加了自定义选项。

    • 最终放弃了对类型过滤器的支持。如果需要，请用自定义插件替换。

版本 0.9

有什么新功能？

性能改进

  • Router现在针对wsgi.run_once环境进行特殊处理，以加速 CGI。

  • 模块加载时间减少了约 30%，并优化了模板解析器。详情请参阅8ccb2d、f72a7c和b14b9a。

  • 支持 Google App Engine 上的“应用缓存”。参见af93ec。

  • 一些很少使用或已弃用的功能现在作为插件存在，如果未使用该功能，则避免了开销。

API 更改

此版本大多数向后兼容，但某些 API 现在被标记为已弃用，并将在下一版本中移除。最值得注意的包括：

  • static路由参数已弃用。您可以使用反斜杠转义通配符。

  • 基于类型的输出过滤器已弃用。它们可以很容易地用插件替换。

版本 0.8

API 更改

这些更改可能会破坏与之前版本的兼容性。

  • 内置的键/值数据库不再可用。自 0.6.4 版本起已标记为弃用。

  • 路由语法和行为已更改。

    • 正则表达式必须用#封装。在 0.6 版本中，允许不在正则表达式中的所有非字母数字字符。

    • 不在路由通配符中的正则表达式会自动转义。您不再需要转义点或其他正则表达式控制字符。在 0.6 版本中，整个 URL 被解释为正则表达式。您可以使用匿名通配符（/index:#(\.html)?#）来实现类似的行为。

  • BreakTheBottle异常已移除。请改用HTTPResponse。

  • SimpleTemplate引擎会自动转义{{bad_html}}表达式中的 HTML 特殊字符。使用新的{{!good_html}}语法以获得旧的行为（不转义）。

  • SimpleTemplate引擎返回 unicode 字符串而不是字节字符串列表。

  • bottle.optimize()和自动路由优化已过时。

  • 一些函数和属性已重命名

  • 默认的redirect()代码从 307 更改为 303。

  • 移除了对@default的支持。请改用@error(404)。

新功能

这是一份不完整的新功能和改进功能的列表。