The Request Context

This is similar to the The Application Context, which keeps track of theapplication-level data independent of a request. A correspondingapplication context is pushed when a request context is pushed.

When the application handles a request, it creates aRequest object based on the environment it received from theWSGI server. Because a worker (thread, process, or coroutine dependingon the server) handles only one request at a time, the request data canbe considered global to that worker during that request. Flask uses theterm context local for this.

Flask automatically pushes a request context when handling a request.View functions, error handlers, and other functions that run during arequest will have access to the proxy, which points tothe request object for the current request.

Lifetime of the Context

When a Flask application begins handling a request, it pushes a requestcontext, which also pushes an . When the request endsit pops the request context then the application context.

The context is unique to each thread (or other worker type).request cannot be passed to another thread, the other threadwill have a different context stack and will not know about the requestthe parent thread was pointing to.

Context locals are implemented in Werkzeug. See for more information on how this works internally.

If you try to access request, or anything that uses it, outsidea request context, you’ll get this error message:

This should typically only happen when testing code that expects anactive request. One option is to use the to simulate a full request. Oryou can use test_request_context() in a with block, andeverything that runs in the block will have access to ,populated with your test data.

If you see that error somewhere else in your code not related totesting, it most likely indicates that you should move that code into aview function.

For information on how to use the request context from the interactivePython shell, see Working with the Shell.

How the Context Works

The Flask.wsgi_app() method is called to handle each request. Itmanages the contexts during the request. Internally, the request andapplication contexts work as stacks, and_app_ctx_stack. When contexts are pushed onto the stack, theproxies that depend on them are available and point at information fromthe top context on the stack.

When the request starts, a is created andpushed, which creates and pushes an AppContext first ifa context for that application is not already the top context. Whilethese contexts are pushed, the , g,, and session proxies are available to theoriginal thread handling the request.

After the request is dispatched and a response is generated and sent,the request context is popped, which then pops the application context.Immediately before they are popped, the and teardown_appcontext() functions are are executed. Theseexecute even if an unhandled exception occurred during dispatch.

Flask dispatches a request in multiple stages which can affect therequest, response, and how errors are handled. The contexts are activeduring all of these stages.

A can add handlers for these events that are specificto the blueprint. The handlers for a blueprint will run if the blueprintowns the route that matches the request.

• Before each request, before_request() functions arecalled. If one of these functions return a value, the otherfunctions are skipped. The return value is treated as the responseand the view function is not called.

• If the functions did not return aresponse, the view function for the matched route is called andreturns a response.

• After the response is returned, the contexts are popped, which callsthe teardown_request() and functions. These functions arecalled even if an unhandled exception was raised at any point above.

If an exception is raised before the teardown functions, Flask tries tomatch it with an errorhandler() function to handle theexception and return a response. If no error handler is found, or thehandler itself raises an exception, Flask returns a generic500 Internal Server Error response. The teardown functions are stillcalled, and are passed the exception object.

If debug mode is enabled, unhandled exceptions are not converted to a500 response and instead are propagated to the WSGI server. Thisallows the development server to present the interactive debugger withthe traceback.

The teardown callbacks are independent of the request dispatch, and areinstead called by the contexts when they are popped. The functions arecalled even if there is an unhandled exception during dispatch, and formanually pushed contexts. This means there is no guarantee that anyother parts of the request dispatch have run first. Be sure to writethese functions in a way that does not depend on other callbacks andwill not fail.

During testing, it can be useful to defer popping the contexts after therequest ends, so that their data can be accessed in the test function.Using the as a block to preserve thecontexts until the with block exits.

Signals

If is true, the following signals aresent:

• request_finished is sent after the functions are called.

• got_request_exception is sent when an exception begins tobe handled, but before an is looked up orcalled.

• request_tearing_down is sent after the functions are called.

Context Preservation on Error

At the end of a request, the request context is popped and all dataassociated with it is destroyed. If an error occurs during development,it is useful to delay destroying the data for debugging purposes.

When the development server is running in development mode (theFLASK_ENV environment variable is set to 'development'), theerror and data will be preserved and shown in the interactive debugger.

This behavior can be controlled with the config. As described above, itdefaults to True in the development environment.

Do not enable PRESERVE_CONTEXT_ON_EXCEPTION in production, as itwill cause your application to leak memory on exceptions.

Some of the objects provided by Flask are proxies to other objects. Theproxies are accessed in the same way for each worker thread, butpoint to the unique object bound to each worker behind the scenes asdescribed on this page.

Most of the time you don’t have to care about that, but there are someexceptions where it is good to know that this object is an actual proxy:

• If the specific object reference is important, for example forsending or passing data to a background thread.

If you need to access the underlying object that is proxied, use the_get_current_object() method: