From 115d31ddbfac0773794f115eada88a75d651a0f2 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Fri, 27 May 2011 20:29:03 +0200 Subject: [PATCH] More documentation updates --- CHANGES | 5 ++++- docs/upgrading.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++++ flask/app.py | 2 ++ 3 files changed, 53 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index e10744ca..d8d12733 100644 --- a/CHANGES +++ b/CHANGES @@ -38,13 +38,16 @@ Release date to be announced, codename to be selected - Added `create_jinja_loader` to override the loader creation process. - Implemented a silent flag for `config.from_pyfile`. - Added `teardown_request` decorator, for functions that should run at the end - of a request regardless of whether an exception occurred. + of a request regardless of whether an exception occurred. Also the behavior + for `after_request` was changed. It's now no longer executed when an exception + is raised. See :ref:`upgrading-to-new-teardown-handling` - Implemented :func:`flask.has_request_context` - Added :func:`safe_join` - The automatic JSON request data unpacking now looks at the charset mimetype parameter. - Don't modify the session on :func:`flask.get_flashed_messages` if there are no messages in the session. +- `before_request` handlers are now able to abort requests with errors. Version 0.6.1 ------------- diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 17523290..7d6e0f0a 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -22,6 +22,11 @@ installation, make sure to pass it the ``-U`` parameter:: Version 0.7 ----------- +The following backwards incompatible changes exist from 0.6 to 0.7 + +Bug in Request Locals +````````````````````` + Due to a bug in earlier implementations the request local proxies now raise a :exc:`RuntimeError` instead of an :exc:`AttributeError` when they are unbound. If you caught these exceptions with :exc:`AttributeError` @@ -44,6 +49,48 @@ New code:: return send_file(my_file_object, add_etags=False) +.. _upgrading-to-new-teardown-handling: + +Upgrading to new Teardown Handling +`````````````````````````````````` + +We streamlined the behavior of the callbacks for request handling. For +things that modify the response the :meth:`~flask.Flask.after_request` +decorators continue to work as expected, but for things that absolutely +must happen at the end of request we introduced the new +:meth:`~flask.Flask.teardown_request` decorator. Unfortunately that +change also made after-request work differently under error conditions. +It's not consistently skipped if exceptions happen whereas previously it +might have been called twice to ensure it is executed at the end of the +request. + +If you have database connection code that looks like this:: + + @app.after_request + def after_request(response): + g.db.close() + return response + +You are now encouraged to use this instead:: + + @app.teardown_request + def after_request(exception): + g.db.close() + +On the upside this change greatly improves the internal code flow and +makes it easier to customize the dispatching and error handling. This +makes it now a lot easier to write unit tests as you can prevent closing +down of database connections for a while. You can take advantage of the +fact that the teardown callbacks are called when the response context is +removed from the stack so a test can query the database after request +handling:: + + with app.test_client() as client: + resp = client.get('/') + # g.db is still bound if there is such a thing + + # and here it's gone + Version 0.6 ----------- diff --git a/flask/app.py b/flask/app.py index 99d7a266..c1bcc340 100644 --- a/flask/app.py +++ b/flask/app.py @@ -831,6 +831,8 @@ class Flask(_PackageBoundObject): """Dispatches the request and on top of that performs request pre and postprocessing as well as HTTP exception catching and error handling. + + .. versionadded:: 0.7 """ try: request_started.send(self)