Navigation

One of the design ideas behind Flask is that there are at least two
different “states” in which code is executed:

1. The application setup state, in which the application implicitly is
on the module level.

This state 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:

the programmer can modify the application object safely.

no request handling happened so far

you have to have a reference to the application object in order to
modify it, there is no magic proxy that can give you a reference to
the application object you’re currently creating or modifying.

2. In contrast, in the request handling state, a couple of other rules
exist:

while a request is active, the context local objects
(flask.request and others) point to the current request.

any code can get hold of these objects at any time.

3. There is also a third state somewhere in between ‘module-level’ and
‘request-handling’:

Sometimes you are dealing with an application in a way that is similar to
how you interact with applications during request handling, but without
there being an active request. Consider, for instance, that you’re
sitting in an interactive Python shell and interacting with the
application, or a command line application.

The main reason for the application’s context existence is that in the
past a bunch of functionality was attached to the request context for lack
of a better solution. Since one of the pillars of Flask’s design is that
you can have more than one application in the same Python process.

So how does the code find the “right” application? In the past we
recommended passing applications around explicitly, but that caused issues
with libraries that were not designed with that in mind.

A common workaround for that problem was to use the
current_app proxy later on, which was bound to the current
request’s application reference. Since creating such a request context is
an unnecessarily expensive operation in case there is no request around,
the application context was introduced.

There are two ways to make an application context. The first one is
implicit: whenever a request context is pushed, an application context
will be created alongside if this is necessary. As a result, you can
ignore the existence of the application context unless you need it.

The application context is created and destroyed as necessary. It never
moves between threads and it will not be shared between requests. As such
it is the perfect place to store database connection information and other
things. The internal stack object is called flask._app_ctx_stack.
Extensions are free to store additional information on the topmost level,
assuming they pick a sufficiently unique name and should put their
information there, instead of on the flask.g object which is reserved
for user code.

The context is typically used to cache resources that need to be created
on a per-request or usage case. For instance, database connections are
destined to go there. When storing things on the application context
unique names should be chosen as this is a place that is shared between
Flask applications and extensions.

The most common usage is to split resource management into two parts:

an implicit resource caching on the context.

a context teardown based resource deallocation.

Generally there would be a get_X() function that creates resource
X if it does not exist yet and otherwise returns the same resource,
and a teardown_X() function that is registered as teardown handler.