docs/changelog.rst
.. highlight:: python .. currentmodule:: bottle
This project loosly follows Semantic Versioning (major.minor.patch), with
the exception that changes are allowed in minor releases as long as the change
is necessary to match documentation, specification or expectation.
In other words: Bugfixes do not count as backward incompatible changes, even if
they technically change something from incorrect to correct and may break
applications that rely on incorrect, undefined or undocumented behavior.
As long as the major version is still 0.x, breaking API changes are also
allowed in minor releases, but we try our best to provide fallbacks and emit
deprecation warnings for at least one minor release circle.
.. rubric:: How to upgrade
0.12.3 to 0.12.25)0.12.25 to 0.13.2), run test
again, fix all warnings and continue... rubric:: Support for old releases
Bugs and security issues are usually fixed in the latest minor release of the two most recent major releases (named stable and old-stable). With each new major release, stable becomes old-stable and the old old-stable will no longer receive regular updates. LTS releases (e.g. 0.12) are an exception. Those will continue to receive updates on a best-effort basis.
.. rubric:: Deprecated APIs or behavior
Route.get_undecorated_callback() was able to look into closure cells to guess the original function wrapped by a decorator, but this is too aggressive in some cases and may return the wrong function. To avoid this, we will depend on proper use of @functools.wraps(orig) or functools.update_wrapper(wrapper, orig) in decorators in the future... rubric:: Removed APIs
RouteReset exception and associated logic.bottle.py console script entrypoint in favour of the new bottle script. You can still execute bottle.py directly or via python -m bottle. The only change is that the command installed by pip or similar tools into the bin/Scripts folder of the (virtual) environment is now called bottle to avoid circular import errors... rubric:: Changes
utf8 with errors='surrogateescape'. This is the correct approach for almost all modern web applications, but still allows applications to recover the original byte sequence if needed. This also means that bottle.FormsDict no longer re-encodes PEP-3333 latin1 strings to utf8 on demand (via attribute access). The FormsDict.getunicode() and FormsDict.decode() methods are deprecated and do nothing, as all values are already transcoded to utf8... rubric:: New features
bottle.HTTPError raised on invalid JSON now include the underlying exception in the exception field... warning:: This release contains breaking changers, please read the notes below
.. rubric:: Dropped support for Python versions that reached their end-of-life.
Bottle up to 0.12 supported an absurd range of Python versions (2.5 to 3.12) and keeping support for Python versions as ancient as 2.5 required a ton of workarounds and compromises, but served no real purpose. If you need support for older Python versions, you can stay on bottle 0.12. The updated list of tested and supported python releases is as follows:
Support for Python 2.5 was marked as deprecated since 0.12. We decided to go a step further and also remove support for 2.6 and 3.1 to 3.7 even if it was never deprecated explicitly in bottle. This means that this release is not backwards compatible in Python <2.7.3 or <3.8 environments. Maintainers for distributions or systems that still use these old python versions should not update to Bottle 0.13 and stick with 0.12 instead.
.. rubric:: Stabilized APIs
ConfigDict class is now considered stable and ready to use... rubric:: Deprecated APIs
tonat() or the py3k flag).bottle.py to just bottle. You can still execute bottle directly as a script (e.g. ./bottle.py or python3 bottle.py) or as a module (via python3 -m bottle). Just the executable installed by your packaging tool (e.g. pip) into the bin folder of your (virtual) environment will change./hello/:name) is deprecated in favor of the more readable and flexible /hello/<name> syntax.Bottle.mount now recognizes Bottle instance and will warn about parameters that are not compatible with the new mounting behavior. The old behavior (mount applications as WSGI callable) still works and is used as a fallback automatically.local_property helper is now deprecated.cookie_encode, :func:cookie_decode and :func:is_cookie_encoded are now also deprecated. If you are using this feature, think about using json to serialize your objects before storing them into cookies, or switch to a session system that stores data server-side instead of client-side... rubric:: Removed APIs (deprecated since 0.12)
Plugins with the old API (api=1 or no api attribute) will no longer work.
Parameter order of :meth:Bottle.mount changed in 0.10. The old order will now result in an error instead of a warning.
The :class:ConfigDict class was introduced in 0.11 and changed during 0.12. These changes are now final.
config["a"]["b"] has a high overhead and little benefit over config["a.b"].ConfigDict instances are no longer callable. This was a shortcut for :meth:ConfigDict.update.ConfigDict constructor no longer accepts any parameters. Use the load_* methods instead.Bottle 0.12 changed some aspects of the Simple Template Engine. These changes are now final and the old syntax will now longer work.
{{rebase()}} call was replaced by a base variable. Example: {{base}}rebase and include keywords were replaced with functions in 0.12.The 'geventSocketIO' server adapter was removed without notice. It did not work anyway.
.. rubric:: Changes
These changes might require special care when updating.
digestmod=hashlib.md5 to :meth:Request.get_cookie <BaseRequest.get_cookie> and :meth:Response.set_cookie <BaseResponse.set_cookie> to get the old behavior.multipart <https://pypi.org/project/multipart/>_) and no longer relies on cgi.FieldStorage, which was removed in Python 3.13. This may change the way broken (non-standard) form submissions are parsed. The new parser is more strict and correct than ohe old one.pip or similar tools will now install an additional command line executable named bottle into the bin folder of your (virtual) environment. This will replace the now deprecated bottle.py executable in a later release. See above... rubric:: Other Improvements
Bottle instances are now context managers. If used in a with-statement, the default application changes to the specific instance and the shortcuts for many instance methods can be used.PATCH requests and the :meth:Bottle.patch decorator.aiohttp <https://aiohttp.readthedocs.io/en/stable/>_ and uvloop <https://github.com/MagicStack/uvloop>_ server adapters.Bottle.mount now recognizes instances of :class:Bottle and mounts them with significantly less overhead than other WSGI applications.Request.json <BaseRequest.json> property now accepts application/json-rpc requests.static_file gained support for ETag headers. It will generate ETags and recognizes If-None-Match headers.static_file will now guess the mime type of *.gz and other compressed files correctly (e.g. application/gzip) and NOT set the Content-Encoding header.New SimpleTemplate parser implementation
<% ... %>).include and rebase are functions now and can accept variable template names.The new :attr:Request.route <BaseRequest.route> property returns the :class:Route that originally matched the request.
Removed the Request.MAX_PARAMS limit. The hash collision bug in CPythons dict() implementation was fixed over a year ago. If you are still using Python 2.5 in production, consider upgrading or at least make sure that you get security fixed from your distributor.
New :class:ConfigDict API (see :doc:configuration)
More information can be found in this development blog post <https://blog.bottlepy.org/2013/07/19/preview-bottle-012.html>_.
Range header) in :func:static_file.ResourceManager interface helps locating files bundled with an application.waitress <https://docs.pylonsproject.org/projects/waitress/en/latest/>_.Bottle.merge method to install all routes from one application into another.Request.app <BaseRequest.app> property to get the application object that handles a request.FormsDict.decode() to get an all-unicode version (needed by WTForms).MultiDict and subclasses are now pickle-able... rubric:: API Changes
Response.status <BaseResponse.status> is a read-write property that can be assigned either a numeric status code or a status string with a reason phrase (200 OK). The return value is now a string to better match existing APIs (WebOb, werkzeug). To be absolutely clear, you can use the read-only properties :attr:Response.status_code <BaseResponse.status_code> and :attr:Response.status_line <BaseResponse.status_line>... rubric:: API Deprecations
SimpleTALTemplate is now deprecating. There seems to be no demand.Plugin API v2
Plugin.api to 2.Plugin.apply receives a :class:Route object instead of a context dictionary as second parameter. The new object offers some additional information and may be extended in the future.The Request/Response Objects
Request.json <BaseRequest.json>, :attr:Request.remote_route <BaseRequest.remote_route>, :attr:Request.remote_addr <BaseRequest.remote_addr>, :attr:Request.query <BaseRequest.query> and :attr:Request.script_name <BaseRequest.script_name>.Response.status_line <BaseResponse.status_line> and :attr:Response.status_code <BaseResponse.status_code> attributes. In future releases, :attr:Response.status <BaseResponse.status> will return a string (e.g. 200 OK) instead of an integer to match the API of other common frameworks. To make the transition as smooth as possible, you should use the verbose attributes from now on.MultiDict with a specialized :class:FormsDict in many places. The new dict implementation allows attribute access and handles unicode form values transparently.Templates
stpl.defined, :func:stpl.get and :func:stpl.setdefault.Routing
/object/<id:int>) and support for route wildcard filters.int, float, path and re.Other changes
ConfigDict that makes accessing configuration a lot easier (attribute access and auto-expanding namespaces).Bottle.mount.Bottle.mount parameter order changed.Bottle.route now accepts an import string for the callback parameter... rubric:: Whats new?
plugins/index and :doc:plugins/dev for details.route decorator got a lot of new features. See :meth:Bottle.route for details.gevent <https://www.gevent.org/>, meinheld <https://meinheld.org/> and bjoern <https://github.com/jonashaag/bjoern>_.Request.urlparts <BaseRequest.urlparts> property... rubric:: Performance improvements
Router now special-cases wsgi.run_once environments to speed up CGI.8ccb2d </commit/8ccb2d>, f72a7c </commit/f72a7c> and b14b9a </commit/b14b9a>_ for details.af93ec </commit/af93ec>_... rubric:: API changes
This release is mostly backward compatible, but some APIs are marked deprecated now and will be removed for the next release. Most noteworthy:
static route parameter is deprecated. You can escape wild-cards with a backslash... rubric:: API changes
These changes may break compatibility with previous versions.
The built-in Key/Value database is not available anymore. It is marked deprecated since 0.6.4
The Route syntax and behaviour changed.
#. In 0.6 all non-alphanumeric characters not present in the regular expression were allowed./index:#(\.html)?#) to achieve a similar behaviour.The BreakTheBottle exception is gone. Use :class:HTTPResponse instead.
The :class:SimpleTemplate engine escapes HTML special characters in {{bad_html}} expressions automatically. Use the new {{!good_html}} syntax to get old behaviour (no escaping).
The :class:SimpleTemplate engine returns unicode strings instead of lists of byte strings.
bottle.optimize() and the automatic route optimization is obsolete.
Some functions and attributes were renamed:
Request._environ <BaseRequest._environ> is now :attr:Request.environ <BaseRequest.environ>Response.header <BaseResponse.header> is now :attr:Response.headers <BaseResponse.headers>default_app is obsolete. Use :func:app instead.The default :func:redirect code changed from 307 to 303.
Removed support for @default. Use @error(404) instead.
.. rubric:: New features
This is an incomplete list of new features and improved functionality.
Request object got new properties: :attr:Request.body <BaseRequest.body>, :attr:Request.auth <BaseRequest.auth>, :attr:Request.url <BaseRequest.url>, :attr:Request.header <BaseRequest.header>, :attr:Request.forms <BaseRequest.forms>, :attr:Request.files <BaseRequest.files>.Response.set_cookie <BaseResponse.set_cookie> and :meth:Request.get_cookie <BaseRequest.get_cookie> methods are now able to encode and decode python objects. This is called a secure cookie because the encoded values are signed and protected from changes on client side. All pickle-able data structures are allowed.Router class drastically improves performance for setups with lots of dynamic routes and supports named routes (named route + dict = URL string).HTTPError and :exc:HTTPResponse instances or other exception objects instead of raising them.static_file equals :func:send_file but returns a :exc:HTTPResponse or :exc:HTTPError instead of raising it. :func:send_file is deprecated.get, :func:post, :func:put and :func:delete decorators.SimpleTemplate engine got full unicode support.