Skip to content
Newer
Older
100644 88 lines (66 sloc) 3.65 KB
d26af4f @mitsuhiko Fixed some smaller things in the docs
authored
1 .. _app-context:
9bed20c @mitsuhiko Added documentation for appcontext and teardown handlers
authored
2
3 The Application Context
4 =======================
5
6 .. versionadded:: 0.9
7
8 One of the design ideas behind Flask is that there are two different
9 “states” in which code is executed. The application setup state in which
10 the application implicitly is on the module level. It starts when the
11 :class:`Flask` object is instantiated, and it implicitly ends when the
12 first request comes in. While the application is in this state a few
13 assumptions are true:
14
15 - the programmer can modify the application object safely.
16 - no request handling happened so far
17 - you have to have a reference to the application object in order to
18 modify it, there is no magic proxy that can give you a reference to
19 the application object you're currently creating or modifying.
20
21 On the contrast, during request handling, a couple of other rules exist:
22
23 - while a request is active, the context local objects
24 (:data:`flask.request` and others) point to the current request.
25 - any code can get hold of these objects at any time.
26
27 There is a third state which is sitting in between a little bit.
28 Sometimes you are dealing with an application in a way that is similar to
29 how you interact with applications during request handling just that there
30 is no request active. Consider for instance that you're sitting in an
31 interactive Python shell and interacting with the application, or a
32 command line application.
33
34 The application context is what powers the :data:`~flask.current_app`
35 context local.
36
37 Purpose of the Application Context
38 ----------------------------------
39
40 The main reason for the application's context existance is that in the
41 past a bunch of functionality was attached to the request context in lack
42 of a better solution. Since one of the pillar's of Flask's design is that
43 you can have more than one application in the same Python process.
44
45 So how does the code find the “right” application? In the past we
46 recommended passing applications around explicitly, but that caused issues
3800c73 @yaph Try to correct confusing sentence in doc and fixed word duplication.
yaph authored
47 with libraries that were not designed with that in mind.
9bed20c @mitsuhiko Added documentation for appcontext and teardown handlers
authored
48
49 A common workaround for that problem was to use the
50 :data:`~flask.current_app` proxy later on, which was bound to the current
51 request's application reference. Since however creating such a request
52 context is an unnecessarily expensive operation in case there is no
53 request around, the application context was introduced.
54
55 Creating an Application Context
56 -------------------------------
57
58 To make an application context there are two ways. The first one is the
59 implicit one: whenever a request context is pushed, an application context
60 will be created alongside if this is necessary. As a result of that, you
61 can ignore the existance of the application context unless you need it.
62
63 The second way is the explicit way using the
64 :meth:`~flask.Flask.app_context` method::
65
66 from flask import Flask, current_app
67
68 app = Flask(__name__)
69 with app.app_context():
70 # within this block, current_app points to app.
71 print current_app.name
72
73 The application context is also used by the :func:`~flask.url_for`
74 function in case a ``SERVER_NAME`` was configured. This allows you to
75 generate URLs even in the absence of a request.
76
77 Locality of the Context
78 -----------------------
79
80 The application context is created and destroyed as necessary. It never
81 moves between threads and it will not be shared between requests. As such
82 it is the perfect place to store database connection information and other
83 things. The internal stack object is called :data:`flask._app_ctx_stack`.
84 Extensions are free to store additional information on the topmost level,
85 assuming they pick a sufficiently unique name.
86
87 For more information about that, see :ref:`extension-dev`.
Something went wrong with that request. Please try again.