/usr/share/doc/python-flask-doc/html/blueprints.html is in python-flask-doc 0.10.1-2build2.
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 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 | <!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>Modular Applications with Blueprints — Flask 0.10.1 documentation</title>
<link rel="stylesheet" href="_static/flasky.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.10.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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="top" title="Flask 0.10.1 documentation" href="index.html" />
<link rel="next" title="Flask Extensions" href="extensions.html" />
<link rel="prev" title="The Request Context" href="reqcontext.html" />
<link rel="apple-touch-icon" href="_static/touch-icon.png" />
<link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="extensions.html" title="Flask Extensions"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="reqcontext.html" title="The Request Context"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Flask 0.10.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="modular-applications-with-blueprints">
<span id="blueprints"></span><h1>Modular Applications with Blueprints<a class="headerlink" href="#modular-applications-with-blueprints" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.7.</span></p>
</div>
<p>Flask uses a concept of <em>blueprints</em> for making application components and
supporting common patterns within an application or across applications.
Blueprints can greatly simplify how large applications work and provide a
central means for Flask extensions to register operations on applications.
A <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt> object works similarly to a <tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt>
application object, but it is not actually an application. Rather it is a
<em>blueprint</em> of how to construct or extend an application.</p>
<div class="section" id="why-blueprints">
<h2>Why Blueprints?<a class="headerlink" href="#why-blueprints" title="Permalink to this headline">¶</a></h2>
<p>Blueprints in Flask are intended for these cases:</p>
<ul class="simple">
<li>Factor an application into a set of blueprints. This is ideal for
larger applications; a project could instantiate an application object,
initialize several extensions, and register a collection of blueprints.</li>
<li>Register a blueprint on an application at a URL prefix and/or subdomain.
Parameters in the URL prefix/subdomain become common view arguments
(with defaults) across all view functions in the blueprint.</li>
<li>Register a blueprint multiple times on an application with different URL
rules.</li>
<li>Provide template filters, static files, templates, and other utilities
through blueprints. A blueprint does not have to implement applications
or view functions.</li>
<li>Register a blueprint on an application for any of these cases when
initializing a Flask extension.</li>
</ul>
<p>A blueprint in Flask is not a pluggable app because it is not actually an
application – it’s a set of operations which can be registered on an
application, even multiple times. Why not have multiple application
objects? You can do that (see <a class="reference internal" href="patterns/appdispatch.html#app-dispatch"><em>Application Dispatching</em></a>), but your applications
will have separate configs and will be managed at the WSGI layer.</p>
<p>Blueprints instead provide separation at the Flask level, share
application config, and can change an application object as necessary with
being registered. The downside is that you cannot unregister a blueprint
once an application was created without having to destroy the whole
application object.</p>
</div>
<div class="section" id="the-concept-of-blueprints">
<h2>The Concept of Blueprints<a class="headerlink" href="#the-concept-of-blueprints" title="Permalink to this headline">¶</a></h2>
<p>The basic concept of blueprints is that they record operations to execute
when registered on an application. Flask associates view functions with
blueprints when dispatching requests and generating URLs from one endpoint
to another.</p>
</div>
<div class="section" id="my-first-blueprint">
<h2>My First Blueprint<a class="headerlink" href="#my-first-blueprint" title="Permalink to this headline">¶</a></h2>
<p>This is what a very basic blueprint looks like. In this case we want to
implement a blueprint that does simple rendering of static templates:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Blueprint</span><span class="p">,</span> <span class="n">render_template</span><span class="p">,</span> <span class="n">abort</span>
<span class="kn">from</span> <span class="nn">jinja2</span> <span class="kn">import</span> <span class="n">TemplateNotFound</span>
<span class="n">simple_page</span> <span class="o">=</span> <span class="n">Blueprint</span><span class="p">(</span><span class="s">'simple_page'</span><span class="p">,</span> <span class="n">__name__</span><span class="p">,</span>
<span class="n">template_folder</span><span class="o">=</span><span class="s">'templates'</span><span class="p">)</span>
<span class="nd">@simple_page.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="p">{</span><span class="s">'page'</span><span class="p">:</span> <span class="s">'index'</span><span class="p">})</span>
<span class="nd">@simple_page.route</span><span class="p">(</span><span class="s">'/<page>'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">show</span><span class="p">(</span><span class="n">page</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">return</span> <span class="n">render_template</span><span class="p">(</span><span class="s">'pages/</span><span class="si">%s</span><span class="s">.html'</span> <span class="o">%</span> <span class="n">page</span><span class="p">)</span>
<span class="k">except</span> <span class="n">TemplateNotFound</span><span class="p">:</span>
<span class="n">abort</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span>
</pre></div>
</div>
<p>When you bind a function with the help of the <tt class="docutils literal"><span class="pre">@simple_page.route</span></tt>
decorator the blueprint will record the intention of registering the
function <cite>show</cite> on the application when it’s later registered.
Additionally it will prefix the endpoint of the function with the
name of the blueprint which was given to the <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt>
constructor (in this case also <tt class="docutils literal"><span class="pre">simple_page</span></tt>).</p>
</div>
<div class="section" id="registering-blueprints">
<h2>Registering Blueprints<a class="headerlink" href="#registering-blueprints" title="Permalink to this headline">¶</a></h2>
<p>So how do you register that blueprint? Like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Flask</span>
<span class="kn">from</span> <span class="nn">yourapplication.simple_page</span> <span class="kn">import</span> <span class="n">simple_page</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">register_blueprint</span><span class="p">(</span><span class="n">simple_page</span><span class="p">)</span>
</pre></div>
</div>
<p>If you check the rules registered on the application, you will find
these:</p>
<div class="highlight-python"><div class="highlight"><pre>[<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
<Rule '/<page>' (HEAD, OPTIONS, GET) -> simple_page.show>,
<Rule '/' (HEAD, OPTIONS, GET) -> simple_page.show>]
</pre></div>
</div>
<p>The first one is obviously from the application ifself for the static
files. The other two are for the <cite>show</cite> function of the <tt class="docutils literal"><span class="pre">simple_page</span></tt>
blueprint. As you can see, they are also prefixed with the name of the
blueprint and separated by a dot (<tt class="docutils literal"><span class="pre">.</span></tt>).</p>
<p>Blueprints however can also be mounted at different locations:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">register_blueprint</span><span class="p">(</span><span class="n">simple_page</span><span class="p">,</span> <span class="n">url_prefix</span><span class="o">=</span><span class="s">'/pages'</span><span class="p">)</span>
</pre></div>
</div>
<p>And sure enough, these are the generated rules:</p>
<div class="highlight-python"><div class="highlight"><pre>[<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
<Rule '/pages/<page>' (HEAD, OPTIONS, GET) -> simple_page.show>,
<Rule '/pages/' (HEAD, OPTIONS, GET) -> simple_page.show>]
</pre></div>
</div>
<p>On top of that you can register blueprints multiple times though not every
blueprint might respond properly to that. In fact it depends on how the
blueprint is implemented if it can be mounted more than once.</p>
</div>
<div class="section" id="blueprint-resources">
<h2>Blueprint Resources<a class="headerlink" href="#blueprint-resources" title="Permalink to this headline">¶</a></h2>
<p>Blueprints can provide resources as well. Sometimes you might want to
introduce a blueprint only for the resources it provides.</p>
<div class="section" id="blueprint-resource-folder">
<h3>Blueprint Resource Folder<a class="headerlink" href="#blueprint-resource-folder" title="Permalink to this headline">¶</a></h3>
<p>Like for regular applications, blueprints are considered to be contained
in a folder. While multiple blueprints can originate from the same folder,
it does not have to be the case and it’s usually not recommended.</p>
<p>The folder is inferred from the second argument to <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt> which
is usually <cite>__name__</cite>. This argument specifies what logical Python
module or package corresponds to the blueprint. If it points to an actual
Python package that package (which is a folder on the filesystem) is the
resource folder. If it’s a module, the package the module is contained in
will be the resource folder. You can access the
<tt class="xref py py-attr docutils literal"><span class="pre">Blueprint.root_path</span></tt> property to see what the resource folder is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">simple_page</span><span class="o">.</span><span class="n">root_path</span>
<span class="go">'/Users/username/TestProject/yourapplication'</span>
</pre></div>
</div>
<p>To quickly open sources from this folder you can use the
<tt class="xref py py-meth docutils literal"><span class="pre">open_resource()</span></tt> function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">simple_page</span><span class="o">.</span><span class="n">open_resource</span><span class="p">(</span><span class="s">'static/style.css'</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
<span class="n">code</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="static-files">
<h3>Static Files<a class="headerlink" href="#static-files" title="Permalink to this headline">¶</a></h3>
<p>A blueprint can expose a folder with static files by providing a path to a
folder on the filesystem via the <cite>static_folder</cite> keyword argument. It can
either be an absolute path or one relative to the folder of the
blueprint:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">admin</span> <span class="o">=</span> <span class="n">Blueprint</span><span class="p">(</span><span class="s">'admin'</span><span class="p">,</span> <span class="n">__name__</span><span class="p">,</span> <span class="n">static_folder</span><span class="o">=</span><span class="s">'static'</span><span class="p">)</span>
</pre></div>
</div>
<p>By default the rightmost part of the path is where it is exposed on the
web. Because the folder is called <tt class="docutils literal"><span class="pre">static</span></tt> here it will be available at
the location of the blueprint + <tt class="docutils literal"><span class="pre">/static</span></tt>. Say the blueprint is
registered for <tt class="docutils literal"><span class="pre">/admin</span></tt> the static folder will be at <tt class="docutils literal"><span class="pre">/admin/static</span></tt>.</p>
<p>The endpoint is named <cite>blueprint_name.static</cite> so you can generate URLs to
it like you would do to the static folder of the application:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">'admin.static'</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s">'style.css'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="templates">
<h3>Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h3>
<p>If you want the blueprint to expose templates you can do that by providing
the <cite>template_folder</cite> parameter to the <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt> constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">admin</span> <span class="o">=</span> <span class="n">Blueprint</span><span class="p">(</span><span class="s">'admin'</span><span class="p">,</span> <span class="n">__name__</span><span class="p">,</span> <span class="n">template_folder</span><span class="o">=</span><span class="s">'templates'</span><span class="p">)</span>
</pre></div>
</div>
<p>As for static files, the path can be absolute or relative to the blueprint
resource folder. The template folder is added to the searchpath of
templates but with a lower priority than the actual application’s template
folder. That way you can easily override templates that a blueprint
provides in the actual application.</p>
<p>So if you have a blueprint in the folder <tt class="docutils literal"><span class="pre">yourapplication/admin</span></tt> and you
want to render the template <tt class="docutils literal"><span class="pre">'admin/index.html'</span></tt> and you have provided
<tt class="docutils literal"><span class="pre">templates</span></tt> as a <cite>template_folder</cite> you will have to create a file like
this: <tt class="docutils literal"><span class="pre">yourapplication/admin/templates/admin/index.html</span></tt>.</p>
</div>
</div>
<div class="section" id="building-urls">
<h2>Building URLs<a class="headerlink" href="#building-urls" title="Permalink to this headline">¶</a></h2>
<p>If you want to link from one page to another you can use the
<tt class="xref py py-func docutils literal"><span class="pre">url_for()</span></tt> function just like you normally would do just that you
prefix the URL endpoint with the name of the blueprint and a dot (<tt class="docutils literal"><span class="pre">.</span></tt>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">'admin.index'</span><span class="p">)</span>
</pre></div>
</div>
<p>Additionally if you are in a view function of a blueprint or a rendered
template and you want to link to another endpoint of the same blueprint,
you can use relative redirects by prefixing the endpoint with a dot only:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">'.index'</span><span class="p">)</span>
</pre></div>
</div>
<p>This will link to <tt class="docutils literal"><span class="pre">admin.index</span></tt> for instance in case the current request
was dispatched to any other admin blueprint endpoint.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<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="#">Modular Applications with Blueprints</a><ul>
<li><a class="reference internal" href="#why-blueprints">Why Blueprints?</a></li>
<li><a class="reference internal" href="#the-concept-of-blueprints">The Concept of Blueprints</a></li>
<li><a class="reference internal" href="#my-first-blueprint">My First Blueprint</a></li>
<li><a class="reference internal" href="#registering-blueprints">Registering Blueprints</a></li>
<li><a class="reference internal" href="#blueprint-resources">Blueprint Resources</a><ul>
<li><a class="reference internal" href="#blueprint-resource-folder">Blueprint Resource Folder</a></li>
<li><a class="reference internal" href="#static-files">Static Files</a></li>
<li><a class="reference internal" href="#templates">Templates</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-urls">Building URLs</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="reqcontext.html" title="previous chapter">The Request Context</a></li>
<li>Next: <a href="extensions.html" title="next chapter">Flask Extensions</a></li>
</ul></li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/blueprints.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2013, Armin Ronacher.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
|