This document describes the behavior in Flask 0.7 which is mostly in line with the old behavior but has some small, subtle differences.
One of the design ideas behind Flask is that there are two different “states” in which code is executed. The application setup state in which the application implicitly is on the module level. It starts when the Flask object is instantiated, and it implicitly ends when the first request comes in. While the application is in this state a few assumptions are true:
On the contrast, during request handling, a couple of other rules exist:
The magic that makes this works is internally referred in Flask as the “request context”.
Say you have a utility function that returns the URL the user should be redirected to. Imagine it would always redirect to the URL’s next parameter or the HTTP referrer or the index page:
from flask import request, url_for def redirect_url(): return request.args.get('next') or \ request.referrer or \ url_for('index')
As you can see, it accesses the request object. If you try to run this from a plain Python shell, this is the exception you will see:
>>> redirect_url() Traceback (most recent call last): File "<stdin>", line 1, in <module> AttributeError: 'NoneType' object has no attribute 'request'
That makes a lot of sense because we currently do not have a request we could access. So we have to make a request and bind it to the current context. The test_request_context method can create us a RequestContext:
>>> ctx = app.test_request_context('/?next=http://example.com/')
This context can be used in two ways. Either with the with statement or by calling the push() and pop() methods:
From that point onwards you can work with the request object:
>>> redirect_url() u'http://example.com/'
Until you call pop:
Because the request context is internally maintained as a stack you can push and pop multiple times. This is very handy to implement things like internal redirects.
For more information of how to utilize the request context from the interactive Python shell, head over to the Working with the Shell chapter.
If you look into how the Flask WSGI application internally works, you will find a piece of code that looks very much like this:
def wsgi_app(self, environ): with self.request_context(environ): try: response = self.full_dispatch_request() except Exception, e: response = self.make_response(self.handle_exception(e)) return response(environ, start_response)
The method request_context() returns a new RequestContext object and uses it in combination with the with statement to bind the context. Everything that is called from the same thread from this point onwards until the end of the with statement will have access to the request globals (flask.request and others).
The request context internally works like a stack: The topmost level on the stack is the current active request. push() adds the context to the stack on the very top, pop() removes it from the stack again. On popping the application’s teardown_request() functions are also executed.
What happens if an error occurs in Flask during request processing? This particular behavior changed in 0.7 because we wanted to make it easier to understand what is actually happening. The new behavior is quite simple:
Now what happens on errors? In production mode if an exception is not caught, the 500 internal server handler is called. In development mode however the exception is not further processed and bubbles up to the WSGI server. That way things like the interactive debugger can provide helpful debug information.
An important change in 0.7 is that the internal server error is now no longer post processed by the after request callbacks and after request callbacks are no longer guaranteed to be executed. This way the internal dispatching code looks cleaner and is easier to customize and understand.
The new teardown functions are supposed to be used as a replacement for things that absolutely need to happen at the end of request.
The teardown callbacks are special callbacks in that they are executed at at different point. Strictly speaking they are independent of the actual request handling as they are bound to the lifecycle of the RequestContext object. When the request context is popped, the teardown_request() functions are called.
This is important to know if the life of the request context is prolonged by using the test client in a with statement of when using the request context from the command line:
with app.test_client() as client: resp = client.get('/foo') # the teardown functions are still not called at that point # even though the response ended and you have the response # object in your hand # only when the code reaches this point the teardown functions # are called. Alternatively the same thing happens if another # request was triggered from the test client
It’s easy to see the behavior from the command line:
>>> app = Flask(__name__) >>> @app.teardown_request ... def teardown_request(exception=None): ... print 'this runs after request' ... >>> ctx = app.test_request_context() >>> ctx.push() >>> ctx.pop() this runs after request >>>
Some of the objects provided by Flask are proxies to other objects. The reason behind this is that these proxies are shared between threads and they have to dispatch to the actual object bound to a thread behind the scenes as necessary.
Most of the time you don’t have to care about that, but there are some exceptions where it is good to know that this object is an actual proxy:
If you need to get access to the underlying object that is proxied, you can use the _get_current_object() method:
app = current_app._get_current_object() my_signal.send(app)
If an error occurs or not, at the end of the request the request context is popped and all data associated with it is destroyed. During development however that can be problematic as you might want to have the information around for a longer time in case an exception occurred. In Flask 0.6 and earlier in debug mode, if an exception occurred, the request context was not popped so that the interactive debugger can still provide you with important information.
Starting with Flask 0.7 you have finer control over that behavior by setting the PRESERVE_CONTEXT_ON_EXCEPTION configuration variable. By default it’s linked to the setting of DEBUG. If the application is in debug mode the context is preserved, in production mode it’s not.
Do not force activate PRESERVE_CONTEXT_ON_EXCEPTION in production mode as it will cause your application to leak memory on exceptions. However it can be useful during development to get the same error preserving behavior as in development mode when attempting to debug an error that only occurs under production settings.