/usr/share/doc/python-flask-doc/html/appcontext.html is in python-flask-doc 0.12.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The Application Context — Flask 0.12.2 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.12.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/flask-favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="The Request Context" href="reqcontext.html" />
<link rel="prev" title="Pluggable Views" href="views.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-application-context">
<span id="app-context"></span><h1>The Application Context<a class="headerlink" href="#the-application-context" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
<p>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
<code class="xref py py-class docutils literal"><span class="pre">Flask</span></code> 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:</p>
<ul class="simple">
<li>the programmer can modify the application object safely.</li>
<li>no request handling happened so far</li>
<li>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.</li>
</ul>
<p>In contrast, during request handling, a couple of other rules exist:</p>
<ul class="simple">
<li>while a request is active, the context local objects
(<a class="reference internal" href="api.html#flask.request" title="flask.request"><code class="xref py py-data docutils literal"><span class="pre">flask.request</span></code></a> and others) point to the current request.</li>
<li>any code can get hold of these objects at any time.</li>
</ul>
<p>There is a third state which is sitting in between a little bit.
Sometimes you are dealing with an application in a way that is similar to
how you interact with applications during request handling; just that there
is no request active. Consider, for instance, that you’re sitting in an
interactive Python shell and interacting with the application, or a
command line application.</p>
<p>The application context is what powers the <a class="reference internal" href="api.html#flask.current_app" title="flask.current_app"><code class="xref py py-data docutils literal"><span class="pre">current_app</span></code></a>
context local.</p>
<div class="section" id="purpose-of-the-application-context">
<h2>Purpose of the Application Context<a class="headerlink" href="#purpose-of-the-application-context" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>A common workaround for that problem was to use the
<a class="reference internal" href="api.html#flask.current_app" title="flask.current_app"><code class="xref py py-data docutils literal"><span class="pre">current_app</span></code></a> 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.</p>
</div>
<div class="section" id="creating-an-application-context">
<h2>Creating an Application Context<a class="headerlink" href="#creating-an-application-context" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>The second way is the explicit way using the
<a class="reference internal" href="api.html#flask.Flask.app_context" title="flask.Flask.app_context"><code class="xref py py-meth docutils literal"><span class="pre">app_context()</span></code></a> method:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">flask</span> <span class="k">import</span> <span class="n">Flask</span><span class="p">,</span> <span class="n">current_app</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
<span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">app_context</span><span class="p">():</span>
<span class="c1"># within this block, current_app points to app.</span>
<span class="nb">print</span> <span class="n">current_app</span><span class="o">.</span><span class="n">name</span>
</pre></div>
</div>
<p>The application context is also used by the <a class="reference internal" href="api.html#flask.url_for" title="flask.url_for"><code class="xref py py-func docutils literal"><span class="pre">url_for()</span></code></a>
function in case a <code class="docutils literal"><span class="pre">SERVER_NAME</span></code> was configured. This allows you to
generate URLs even in the absence of a request.</p>
<p>If no request context has been pushed and an application context has
not been explicitly set, a <code class="docutils literal"><span class="pre">RuntimeError</span></code> will be raised.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="ne">RuntimeError</span><span class="p">:</span> <span class="n">Working</span> <span class="n">outside</span> <span class="n">of</span> <span class="n">application</span> <span class="n">context</span><span class="o">.</span>
</pre></div>
</div>
</div>
<div class="section" id="locality-of-the-context">
<h2>Locality of the Context<a class="headerlink" href="#locality-of-the-context" title="Permalink to this headline">¶</a></h2>
<p>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 <a class="reference internal" href="api.html#flask._app_ctx_stack" title="flask._app_ctx_stack"><code class="xref py py-data docutils literal"><span class="pre">flask._app_ctx_stack</span></code></a>.
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 <a class="reference internal" href="api.html#flask.g" title="flask.g"><code class="xref py py-data docutils literal"><span class="pre">flask.g</span></code></a> object which is reserved
for user code.</p>
<p>For more information about that, see <a class="reference internal" href="extensiondev.html#extension-dev"><span class="std std-ref">Flask Extension Development</span></a>.</p>
</div>
<div class="section" id="context-usage">
<h2>Context Usage<a class="headerlink" href="#context-usage" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>The most common usage is to split resource management into two parts:</p>
<ol class="arabic simple">
<li>an implicit resource caching on the context.</li>
<li>a context teardown based resource deallocation.</li>
</ol>
<p>Generally there would be a <code class="docutils literal"><span class="pre">get_X()</span></code> function that creates resource
<code class="docutils literal"><span class="pre">X</span></code> if it does not exist yet and otherwise returns the same resource,
and a <code class="docutils literal"><span class="pre">teardown_X()</span></code> function that is registered as teardown handler.</p>
<p>This is an example that connects to a database:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sqlite3</span>
<span class="kn">from</span> <span class="nn">flask</span> <span class="k">import</span> <span class="n">g</span>
<span class="k">def</span> <span class="nf">get_db</span><span class="p">():</span>
<span class="n">db</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">g</span><span class="p">,</span> <span class="s1">'_database'</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
<span class="k">if</span> <span class="n">db</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="n">db</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">_database</span> <span class="o">=</span> <span class="n">connect_to_database</span><span class="p">()</span>
<span class="k">return</span> <span class="n">db</span>
<span class="nd">@app</span><span class="o">.</span><span class="n">teardown_appcontext</span>
<span class="k">def</span> <span class="nf">teardown_db</span><span class="p">(</span><span class="n">exception</span><span class="p">):</span>
<span class="n">db</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">g</span><span class="p">,</span> <span class="s1">'_database'</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
<span class="k">if</span> <span class="n">db</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
<span class="n">db</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The first time <code class="docutils literal"><span class="pre">get_db()</span></code> is called the connection will be established.
To make this implicit a <code class="xref py py-class docutils literal"><span class="pre">LocalProxy</span></code> can be used:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">werkzeug.local</span> <span class="k">import</span> <span class="n">LocalProxy</span>
<span class="n">db</span> <span class="o">=</span> <span class="n">LocalProxy</span><span class="p">(</span><span class="n">get_db</span><span class="p">)</span>
</pre></div>
</div>
<p>That way a user can directly access <code class="docutils literal"><span class="pre">db</span></code> which internally calls
<code class="docutils literal"><span class="pre">get_db()</span></code>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"><p class="logo"><a href="index.html">
<img class="logo" src="_static/flask.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The Application Context</a><ul>
<li><a class="reference internal" href="#purpose-of-the-application-context">Purpose of the Application Context</a></li>
<li><a class="reference internal" href="#creating-an-application-context">Creating an Application Context</a></li>
<li><a class="reference internal" href="#locality-of-the-context">Locality of the Context</a></li>
<li><a class="reference internal" href="#context-usage">Context Usage</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="views.html" title="previous chapter">Pluggable Views</a></li>
<li>Next: <a href="reqcontext.html" title="next chapter">The Request Context</a></li>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/appcontext.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2018 - 2018, Armin Ronacher.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.6</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="_sources/appcontext.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|