Understanding Flask's context concept

Overview

Flask is designed to handle more than one application in the same Python process. One application can invoke another application without breaking.

Contexts makes it possible to separate application environments from each other. To make this possible it has to know the active context so it can bind the current application and the WSGI environment to that context.

If your app will have more than one application or if you want to do unit testing then it is important to understand how contexts work.

States of execution

Flask goes into different states when executing code:

• The application setup state
  • it starts when the Flask object is instantiated and ends when the first request comes in
  • the application implicitly is on the module level
  • in this state:
    • application object can be modified only by having a reference to it
    • there is no request handling yet
• during request handling
  • a request is active
  • in this state:
    • the context local objects (flask.request and others) point to the current request.
  • these objects can be accessed without an explicit reference at any time. -flask.current_app is a proxy that points to the application handling the request
    • it is provided by the application context
• during request handling with no request active
  • interacting with applications from CLI.

Application Context Purpose

Certain objects in Flask are special global objects, they are proxies to objects that are local to a specific context. (e.g.: the global request object)

Before having application contexts, the way to attach functionality to each application, was to use the current_app proxy, but this is available only when handling a request and creating such request was an expensive operation.

Application Context goal is to avoid having to create a request context when there is no request around, that means, to make it possible to attach functionality in every state of execution in an elegant way and without incurring in unnecessary operations.

How to access them

Application Contexts can be created in two ways:

1. implicit:
   • An application context is automatically created when a request context is pushed if necessary.
2. explicit:
   • Using app_context method to bind the application only.
     • e.g.: with app.app_context():

Useful for

Application contexts are never shared between requests, that makes a good fit to:

• store things like the database connection information
• a place for extensions to save additional data
• to cache resources that need to be created on a per-request or usage case
  • The most common usage is to split resource management into two parts:
    1. an implicit resource caching on the context. def get_X():
    2. a context teardown based resource de-allocation. def teardown_X():

References

• http://flask.pocoo.org/docs/0.12/quickstart/#context-locals
• http://flask.pocoo.org/docs/0.12/api/#flask.request
• http://flask.pocoo.org/docs/0.12/api/#flask.Flask.test_request_context
• http://flask.pocoo.org/docs/0.12/appcontext/
• http://flask.pocoo.org/docs/0.12/api/#flask.current_app
• What is the purpose of Flask’s context stacks? at Stack Overflow

*[e.g.]: exempli gratia