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
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
|
<!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>Quickstart — Flask 0.8 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.8',
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.8 documentation" href="index.html" />
<link rel="next" title="Tutorial" href="tutorial/index.html" />
<link rel="prev" title="Installation" href="installation.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="tutorial/index.html" title="Tutorial"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="installation.html" title="Installation"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Flask 0.8 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="quickstart">
<span id="id1"></span><h1>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h1>
<p>Eager to get started? This page gives a good introduction in how to get
started with Flask. This assumes you already have Flask installed. If
you do not, head over to the <a class="reference internal" href="installation.html#installation"><em>Installation</em></a> section.</p>
<div class="section" id="a-minimal-application">
<h2>A Minimal Application<a class="headerlink" href="#a-minimal-application" title="Permalink to this headline">¶</a></h2>
<p>A minimal Flask application looks something 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="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="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">hello_world</span><span class="p">():</span>
<span class="k">return</span> <span class="s">'Hello World!'</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>Just save it as <cite>hello.py</cite> or something similar and run it with your
Python interpreter. Make sure to not call your application <cite>flask.py</cite>
because this would conflict with Flask itself.</p>
<div class="highlight-python"><pre>$ python hello.py
* Running on http://127.0.0.1:5000/</pre>
</div>
<p>Head over to <a class="reference external" href="http://127.0.0.1:5000/">http://127.0.0.1:5000/</a>, you should
see your hello world greeting.</p>
<p>So what did that code do?</p>
<ol class="arabic simple">
<li>First we imported the <a class="reference internal" href="api.html#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a> class. An instance of this
class will be our WSGI application. The first argument is the name of
the application’s module. If you are using a single module (like here)
you should use <cite>__name__</cite> because depending on if it’s started as
application or imported as module the name will be different
(<tt class="docutils literal"><span class="pre">'__main__'</span></tt> versus the actual import name). For more information
on that, have a look at the <a class="reference internal" href="api.html#flask.Flask" title="flask.Flask"><tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt></a> documentation.</li>
<li>Next we create an instance of it. We pass it the name of the module /
package. This is needed so that Flask knows where it should look for
templates, static files and so on.</li>
<li>Then we use the <a class="reference internal" href="api.html#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> decorator to tell Flask
what URL should trigger our function.</li>
<li>The function then has a name which is also used to generate URLs to
that particular function, and returns the message we want to display in
the user’s browser.</li>
<li>Finally we use the <a class="reference internal" href="api.html#flask.Flask.run" title="flask.Flask.run"><tt class="xref py py-meth docutils literal"><span class="pre">run()</span></tt></a> function to run the
local server with our application. The <tt class="docutils literal"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__':</span></tt>
makes sure the server only runs if the script is executed directly from
the Python interpreter and not used as imported module.</li>
</ol>
<p>To stop the server, hit control-C.</p>
<div class="admonition-externally-visible-server admonition " id="public-server">
<p class="first admonition-title">Externally Visible Server</p>
<p>If you run the server you will notice that the server is only available
from your own computer, not from any other in the network. This is the
default because in debugging mode a user of the application can execute
arbitrary Python code on your computer. If you have <cite>debug</cite> disabled
or trust the users on your network, you can make the server publicly
available.</p>
<p>Just change the call of the <a class="reference internal" href="api.html#flask.Flask.run" title="flask.Flask.run"><tt class="xref py py-meth docutils literal"><span class="pre">run()</span></tt></a> method to look
like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">host</span><span class="o">=</span><span class="s">'0.0.0.0'</span><span class="p">)</span>
</pre></div>
</div>
<p class="last">This tells your operating system to listen on a public IP.</p>
</div>
</div>
<div class="section" id="debug-mode">
<h2>Debug Mode<a class="headerlink" href="#debug-mode" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="api.html#flask.Flask.run" title="flask.Flask.run"><tt class="xref py py-meth docutils literal"><span class="pre">run()</span></tt></a> method is nice to start a local
development server, but you would have to restart it manually after each
change you do to code. That is not very nice and Flask can do better. If
you enable the debug support the server will reload itself on code changes
and also provide you with a helpful debugger if things go wrong.</p>
<p>There are two ways to enable debugging. Either set that flag on the
application object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">debug</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>Or pass it to run:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">debug</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<p>Both will have exactly the same effect.</p>
<div class="admonition-attention admonition ">
<p class="first admonition-title">Attention</p>
<p class="last">Even though the interactive debugger does not work in forking environments
(which makes it nearly impossible to use on production servers), it still
allows the execution of arbitrary code. That makes it a major security
risk and therefore it <strong>must never be used on production machines</strong>.</p>
</div>
<p>Screenshot of the debugger in action:</p>
<img alt="screenshot of debugger in action" class="screenshot align-center" src="_images/debugger5.png" />
<div class="admonition-working-with-other-debuggers admonition ">
<p class="first admonition-title">Working With Other Debuggers</p>
<p class="last">Debuggers interfere with each other. If you are using another debugger
(e.g. PyDev or IntelliJ), you may need to set <tt class="docutils literal"><span class="pre">app.debug</span> <span class="pre">=</span> <span class="pre">False</span></tt>.</p>
</div>
</div>
<div class="section" id="routing">
<h2>Routing<a class="headerlink" href="#routing" title="Permalink to this headline">¶</a></h2>
<p>Modern web applications have beautiful URLs. This helps people remember
the URLs which is especially handy for applications that are used from
mobile devices with slower network connections. If the user can directly
go to the desired page without having to hit the index page it is more
likely they will like the page and come back next time.</p>
<p>As you have seen above, the <a class="reference internal" href="api.html#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> decorator is used
to bind a function to a URL. Here are some basic examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">():</span>
<span class="k">return</span> <span class="s">'Index Page'</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/hello'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">hello</span><span class="p">():</span>
<span class="k">return</span> <span class="s">'Hello World'</span>
</pre></div>
</div>
<p>But there is more to it! You can make certain parts of the URL dynamic
and attach multiple rules to a function.</p>
<div class="section" id="variable-rules">
<h3>Variable Rules<a class="headerlink" href="#variable-rules" title="Permalink to this headline">¶</a></h3>
<p>To add variable parts to a URL you can mark these special sections as
<tt class="docutils literal"><span class="pre"><variable_name></span></tt>. Such a part is then passed as keyword argument to
your function. Optionally a converter can be specified by specifying a
rule with <tt class="docutils literal"><span class="pre"><converter:variable_name></span></tt>. Here are some nice examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/user/<username>'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">show_user_profile</span><span class="p">(</span><span class="n">username</span><span class="p">):</span>
<span class="c"># show the user profile for that user</span>
<span class="k">pass</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/post/<int:post_id>'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">show_post</span><span class="p">(</span><span class="n">post_id</span><span class="p">):</span>
<span class="c"># show the post with the given id, the id is an integer</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>The following converters exist:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><cite>int</cite></td>
<td>accepts integers</td>
</tr>
<tr class="row-even"><td><cite>float</cite></td>
<td>like <cite>int</cite> but for floating point values</td>
</tr>
<tr class="row-odd"><td><cite>path</cite></td>
<td>like the default but also accepts slashes</td>
</tr>
</tbody>
</table>
<div class="admonition-unique-urls-redirection-behaviour admonition ">
<p class="first admonition-title">Unique URLs / Redirection Behaviour</p>
<p>Flask’s URL rules are based on Werkzeug’s routing module. The idea
behind that module is to ensure nice looking and also unique URLs based
on behaviour Apache and earlier servers coined.</p>
<p>Take these two rules:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/projects/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">projects</span><span class="p">():</span>
<span class="k">pass</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/about'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">about</span><span class="p">():</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>They look rather similar, the difference is the trailing slash in the
URL <em>definition</em>. In the first case, the canonical URL for the
<cite>projects</cite> endpoint has a trailing slash. It’s similar to a folder in
that sense. Accessing it without a trailing slash will cause Flask to
redirect to the canonical URL with the trailing slash.</p>
<p>However in the second case the URL is defined without a slash so it
behaves similar to a file and accessing the URL with a trailing slash
will be a 404 error.</p>
<p class="last">Why is this? This allows relative URLs to continue working if users
access the page when they forget a trailing slash. This behaviour is
also consistent with how Apache and other servers work. Also, the URLs
will stay unique which helps search engines not indexing the same page
twice.</p>
</div>
</div>
<div class="section" id="url-building">
<span id="id2"></span><h3>URL Building<a class="headerlink" href="#url-building" title="Permalink to this headline">¶</a></h3>
<p>If it can match URLs, can it also generate them? Of course it can. To
build a URL to a specific function you can use the <a class="reference internal" href="api.html#flask.url_for" title="flask.url_for"><tt class="xref py py-func docutils literal"><span class="pre">url_for()</span></tt></a>
function. It accepts the name of the function as first argument and a
number of keyword arguments, each corresponding to the variable part of
the URL rule. Unknown variable parts are appended to the URL as query
parameter. Here are some examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Flask</span><span class="p">,</span> <span class="n">url_for</span>
<span class="gp">>>> </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="gp">>>> </span><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">index</span><span class="p">():</span> <span class="k">pass</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/login'</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">login</span><span class="p">():</span> <span class="k">pass</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/user/<username>'</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">profile</span><span class="p">(</span><span class="n">username</span><span class="p">):</span> <span class="k">pass</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">test_request_context</span><span class="p">():</span>
<span class="gp">... </span> <span class="k">print</span> <span class="n">url_for</span><span class="p">(</span><span class="s">'index'</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">print</span> <span class="n">url_for</span><span class="p">(</span><span class="s">'login'</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">print</span> <span class="n">url_for</span><span class="p">(</span><span class="s">'login'</span><span class="p">,</span> <span class="nb">next</span><span class="o">=</span><span class="s">'/'</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">print</span> <span class="n">url_for</span><span class="p">(</span><span class="s">'profile'</span><span class="p">,</span> <span class="n">username</span><span class="o">=</span><span class="s">'John Doe'</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">/</span>
<span class="go">/login</span>
<span class="go">/login?next=/</span>
<span class="go">/user/John%20Doe</span>
</pre></div>
</div>
<p>(This also uses the <a class="reference internal" href="api.html#flask.Flask.test_request_context" title="flask.Flask.test_request_context"><tt class="xref py py-meth docutils literal"><span class="pre">test_request_context()</span></tt></a> method
explained below. It basically tells Flask to think we are handling a
request even though we are not, we are in an interactive Python shell.
Have a look at the explanation below. <a class="reference internal" href="#context-locals"><em>Context Locals</em></a>).</p>
<p>Why would you want to build URLs instead of hardcoding them in your
templates? There are three good reasons for this:</p>
<ol class="arabic simple">
<li>reversing is often more descriptive than hardcoding the URLs. Also and
more importantly you can change URLs in one go without having to change
the URLs all over the place.</li>
<li>URL building will handle escaping of special characters and Unicode
data transparently for you, you don’t have to deal with that.</li>
<li>If your application is placed outside the URL root (so say in
<tt class="docutils literal"><span class="pre">/myapplication</span></tt> instead of <tt class="docutils literal"><span class="pre">/</span></tt>), <a class="reference internal" href="api.html#flask.url_for" title="flask.url_for"><tt class="xref py py-func docutils literal"><span class="pre">url_for()</span></tt></a> will
handle that properly for you.</li>
</ol>
</div>
<div class="section" id="http-methods">
<h3>HTTP Methods<a class="headerlink" href="#http-methods" title="Permalink to this headline">¶</a></h3>
<p>HTTP (the protocol web applications are speaking) knows different methods
to access URLs. By default a route only answers to <cite>GET</cite> requests, but
that can be changed by providing the <cite>methods</cite> argument to the
<a class="reference internal" href="api.html#flask.Flask.route" title="flask.Flask.route"><tt class="xref py py-meth docutils literal"><span class="pre">route()</span></tt></a> decorator. Here are some examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/login'</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s">'GET'</span><span class="p">,</span> <span class="s">'POST'</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">login</span><span class="p">():</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span><span class="p">:</span>
<span class="n">do_the_login</span><span class="p">()</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">show_the_login_form</span><span class="p">()</span>
</pre></div>
</div>
<p>If <cite>GET</cite> is present, <cite>HEAD</cite> will be added automatically for you. You
don’t have to deal with that. It will also make sure that <cite>HEAD</cite> requests
are handled like the <a class="reference external" href="http://www.ietf.org/rfc/rfc2068.txt">HTTP RFC</a> (the document describing the HTTP
protocol) demands, so you can completely ignore that part of the HTTP
specification. Likewise as of Flask 0.6, <cite>OPTIONS</cite> is implemented for you
as well automatically.</p>
<p>You have no idea what an HTTP method is? Worry not, here is a quick
introduction to HTTP methods and why they matter:</p>
<p>The HTTP method (also often called “the verb”) tells the server what the
clients wants to <em>do</em> with the requested page. The following methods are
very common:</p>
<dl class="docutils">
<dt><cite>GET</cite></dt>
<dd>The browser tells the server to just <em>get</em> the information stored on
that page and send it. This is probably the most common method.</dd>
<dt><cite>HEAD</cite></dt>
<dd>The browser tells the server to get the information, but it is only
interested in the <em>headers</em>, not the content of the page. An
application is supposed to handle that as if a <cite>GET</cite> request was
received but to not deliver the actual content. In Flask you don’t
have to deal with that at all, the underlying Werkzeug library handles
that for you.</dd>
<dt><cite>POST</cite></dt>
<dd>The browser tells the server that it wants to <em>post</em> some new
information to that URL and that the server must ensure the data is
stored and only stored once. This is how HTML forms are usually
transmitting data to the server.</dd>
<dt><cite>PUT</cite></dt>
<dd>Similar to <cite>POST</cite> but the server might trigger the store procedure
multiple times by overwriting the old values more than once. Now you
might be asking why is this useful, but there are some good reasons
to do it this way. Consider that the connection gets lost during
transmission: in this situation a system between the browser and the
server might receive the request safely a second time without breaking
things. With <cite>POST</cite> that would not be possible because it must only
be triggered once.</dd>
<dt><cite>DELETE</cite></dt>
<dd>Remove the information at the given location.</dd>
<dt><cite>OPTIONS</cite></dt>
<dd>Provides a quick way for a client to figure out which methods are
supported by this URL. Starting with Flask 0.6, this is implemented
for you automatically.</dd>
</dl>
<p>Now the interesting part is that in HTML4 and XHTML1, the only methods a
form can submit to the server are <cite>GET</cite> and <cite>POST</cite>. But with JavaScript
and future HTML standards you can use the other methods as well. Furthermore
HTTP has become quite popular lately and browsers are no longer the only
clients that are using HTTP. For instance, many revision control system
use it.</p>
</div>
</div>
<div class="section" id="static-files">
<h2>Static Files<a class="headerlink" href="#static-files" title="Permalink to this headline">¶</a></h2>
<p>Dynamic web applications need static files as well. That’s usually where
the CSS and JavaScript files are coming from. Ideally your web server is
configured to serve them for you, but during development Flask can do that
as well. Just create a folder called <cite>static</cite> in your package or next to
your module and it will be available at <cite>/static</cite> on the application.</p>
<p>To generate URLs to that part of the URL, use the special <tt class="docutils literal"><span class="pre">'static'</span></tt> URL
name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">'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>
<p>The file has to be stored on the filesystem as <tt class="docutils literal"><span class="pre">static/style.css</span></tt>.</p>
</div>
<div class="section" id="rendering-templates">
<h2>Rendering Templates<a class="headerlink" href="#rendering-templates" title="Permalink to this headline">¶</a></h2>
<p>Generating HTML from within Python is not fun, and actually pretty
cumbersome because you have to do the HTML escaping on your own to keep
the application secure. Because of that Flask configures the <a class="reference external" href="http://jinja.pocoo.org/2/">Jinja2</a> template engine for you automatically.</p>
<p>To render a template you can use the <a class="reference internal" href="api.html#flask.render_template" title="flask.render_template"><tt class="xref py py-func docutils literal"><span class="pre">render_template()</span></tt></a>
method. All you have to do is to provide the name of the template and the
variables you want to pass to the template engine as keyword arguments.
Here’s a simple example of how to render a template:</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">render_template</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/hello/'</span><span class="p">)</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/hello/<name>'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="k">return</span> <span class="n">render_template</span><span class="p">(</span><span class="s">'hello.html'</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">name</span><span class="p">)</span>
</pre></div>
</div>
<p>Flask will look for templates in the <cite>templates</cite> folder. So if your
application is a module, that folder is next to that module, if it’s a
package it’s actually inside your package:</p>
<p><strong>Case 1</strong>: a module:</p>
<div class="highlight-python"><pre>/application.py
/templates
/hello.html</pre>
</div>
<p><strong>Case 2</strong>: a package:</p>
<div class="highlight-python"><pre>/application
/__init__.py
/templates
/hello.html</pre>
</div>
<p>For templates you can use the full power of Jinja2 templates. Head over
to the the official <a class="reference external" href="http://jinja.pocoo.org/2/documentation/templates">Jinja2 Template Documentation</a> for more information.</p>
<p>Here is an example template:</p>
<div class="highlight-html+jinja"><div class="highlight"><pre><span class="cp"><!doctype html></span>
<span class="nt"><title></span>Hello from Flask<span class="nt"></title></span>
<span class="cp">{%</span> <span class="k">if</span> <span class="nv">name</span> <span class="cp">%}</span>
<span class="nt"><h1></span>Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>!<span class="nt"></h1></span>
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
<span class="nt"><h1></span>Hello World!<span class="nt"></h1></span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Inside templates you also have access to the <a class="reference internal" href="api.html#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a>,
<a class="reference internal" href="api.html#flask.session" title="flask.session"><tt class="xref py py-class docutils literal"><span class="pre">session</span></tt></a> and <a class="reference internal" href="api.html#flask.g" title="flask.g"><tt class="xref py py-class docutils literal"><span class="pre">g</span></tt></a> <a class="footnote-reference" href="#id4" id="id3">[1]</a> objects
as well as the <a class="reference internal" href="api.html#flask.get_flashed_messages" title="flask.get_flashed_messages"><tt class="xref py py-func docutils literal"><span class="pre">get_flashed_messages()</span></tt></a> function.</p>
<p>Templates are especially useful if inheritance is used. If you want to
know how that works, head over to the <a class="reference internal" href="patterns/templateinheritance.html#template-inheritance"><em>Template Inheritance</em></a> pattern
documentation. Basically template inheritance makes it possible to keep
certain elements on each page (like header, navigation and footer).</p>
<p>Automatic escaping is enabled, so if name contains HTML it will be escaped
automatically. If you can trust a variable and you know that it will be
safe HTML (because for example it came from a module that converts wiki
markup to HTML) you can mark it as safe by using the
<tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt> class or by using the <tt class="docutils literal"><span class="pre">|safe</span></tt> filter in the
template. Head over to the Jinja 2 documentation for more examples.</p>
<p>Here is a basic introduction to how the <tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt> class works:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Markup</span>
<span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="s">'<strong>Hello </span><span class="si">%s</span><span class="s">!</strong>'</span><span class="p">)</span> <span class="o">%</span> <span class="s">'<blink>hacker</blink>'</span>
<span class="go">Markup(u'<strong>Hello &lt;blink&gt;hacker&lt;/blink&gt;!</strong>')</span>
<span class="gp">>>> </span><span class="n">Markup</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="s">'<blink>hacker</blink>'</span><span class="p">)</span>
<span class="go">Markup(u'&lt;blink&gt;hacker&lt;/blink&gt;')</span>
<span class="gp">>>> </span><span class="n">Markup</span><span class="p">(</span><span class="s">'<em>Marked up</em> &raquo; HTML'</span><span class="p">)</span><span class="o">.</span><span class="n">striptags</span><span class="p">()</span>
<span class="go">u'Marked up \xbb HTML'</span>
</pre></div>
</div>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.5.</span></p>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[1]</a></td><td>Unsure what that <a class="reference internal" href="api.html#flask.g" title="flask.g"><tt class="xref py py-class docutils literal"><span class="pre">g</span></tt></a> object is? It’s something in which
you can store information for your own needs, check the documentation of
that object (<a class="reference internal" href="api.html#flask.g" title="flask.g"><tt class="xref py py-class docutils literal"><span class="pre">g</span></tt></a>) and the <a class="reference internal" href="patterns/sqlite3.html#sqlite3"><em>Using SQLite 3 with Flask</em></a> for more
information.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="accessing-request-data">
<h2>Accessing Request Data<a class="headerlink" href="#accessing-request-data" title="Permalink to this headline">¶</a></h2>
<p>For web applications it’s crucial to react to the data a client sent to
the server. In Flask this information is provided by the global
<a class="reference internal" href="api.html#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a> object. If you have some experience with Python
you might be wondering how that object can be global and how Flask
manages to still be threadsafe. The answer are context locals:</p>
<div class="section" id="context-locals">
<span id="id5"></span><h3>Context Locals<a class="headerlink" href="#context-locals" title="Permalink to this headline">¶</a></h3>
<div class="admonition-insider-information admonition ">
<p class="first admonition-title">Insider Information</p>
<p class="last">If you want to understand how that works and how you can implement
tests with context locals, read this section, otherwise just skip it.</p>
</div>
<p>Certain objects in Flask are global objects, but not of the usual kind.
These objects are actually proxies to objects that are local to a specific
context. What a mouthful. But that is actually quite easy to understand.</p>
<p>Imagine the context being the handling thread. A request comes in and the
webserver decides to spawn a new thread (or something else, the
underlying object is capable of dealing with other concurrency systems
than threads as well). When Flask starts its internal request handling it
figures out that the current thread is the active context and binds the
current application and the WSGI environments to that context (thread).
It does that in an intelligent way that one application can invoke another
application without breaking.</p>
<p>So what does this mean to you? Basically you can completely ignore that
this is the case unless you are doing something like unittesting. You
will notice that code that depends on a request object will suddenly break
because there is no request object. The solution is creating a request
object yourself and binding it to the context. The easiest solution for
unittesting is by using the <a class="reference internal" href="api.html#flask.Flask.test_request_context" title="flask.Flask.test_request_context"><tt class="xref py py-meth docutils literal"><span class="pre">test_request_context()</span></tt></a>
context manager. In combination with the <cite>with</cite> statement it will bind a
test request so that you can interact with it. Here is an example:</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">request</span>
<span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">test_request_context</span><span class="p">(</span><span class="s">'/hello'</span><span class="p">,</span> <span class="n">method</span><span class="o">=</span><span class="s">'POST'</span><span class="p">):</span>
<span class="c"># now you can do something with the request until the</span>
<span class="c"># end of the with block, such as basic assertions:</span>
<span class="k">assert</span> <span class="n">request</span><span class="o">.</span><span class="n">path</span> <span class="o">==</span> <span class="s">'/hello'</span>
<span class="k">assert</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span>
</pre></div>
</div>
<p>The other possibility is passing a whole WSGI environment to the
<a class="reference internal" href="api.html#flask.Flask.request_context" title="flask.Flask.request_context"><tt class="xref py py-meth docutils literal"><span class="pre">request_context()</span></tt></a> method:</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">request</span>
<span class="k">with</span> <span class="n">app</span><span class="o">.</span><span class="n">request_context</span><span class="p">(</span><span class="n">environ</span><span class="p">):</span>
<span class="k">assert</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span>
</pre></div>
</div>
</div>
<div class="section" id="the-request-object">
<h3>The Request Object<a class="headerlink" href="#the-request-object" title="Permalink to this headline">¶</a></h3>
<p>The request object is documented in the API section and we will not cover
it here in detail (see <a class="reference internal" href="api.html#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a>). Here is a broad overview of
some of the most common operations. First of all you have to import it from
the <cite>flask</cite> module:</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">request</span>
</pre></div>
</div>
<p>The current request method is available by using the
<tt class="xref py py-attr docutils literal"><span class="pre">method</span></tt> attribute. To access form data (data
transmitted in a <cite>POST</cite> or <cite>PUT</cite> request) you can use the
<tt class="xref py py-attr docutils literal"><span class="pre">form</span></tt> attribute. Here is a full example of the two
attributes mentioned above:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.route</span><span class="p">(</span><span class="s">'/login'</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s">'POST'</span><span class="p">,</span> <span class="s">'GET'</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">login</span><span class="p">():</span>
<span class="n">error</span> <span class="o">=</span> <span class="bp">None</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span><span class="p">:</span>
<span class="k">if</span> <span class="n">valid_login</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">form</span><span class="p">[</span><span class="s">'username'</span><span class="p">],</span>
<span class="n">request</span><span class="o">.</span><span class="n">form</span><span class="p">[</span><span class="s">'password'</span><span class="p">]):</span>
<span class="k">return</span> <span class="n">log_the_user_in</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">form</span><span class="p">[</span><span class="s">'username'</span><span class="p">])</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">error</span> <span class="o">=</span> <span class="s">'Invalid username/password'</span>
<span class="c"># this is executed if the request method was GET or the</span>
<span class="c"># credentials were invalid</span>
</pre></div>
</div>
<p>What happens if the key does not exist in the <cite>form</cite> attribute? In that
case a special <a class="reference external" href="http://docs.python.org/dev/library/exceptions.html#KeyError" title="(in Python v3.3)"><tt class="xref py py-exc docutils literal"><span class="pre">KeyError</span></tt></a> is raised. You can catch it like a
standard <a class="reference external" href="http://docs.python.org/dev/library/exceptions.html#KeyError" title="(in Python v3.3)"><tt class="xref py py-exc docutils literal"><span class="pre">KeyError</span></tt></a> but if you don’t do that, a HTTP 400 Bad Request
error page is shown instead. So for many situations you don’t have to
deal with that problem.</p>
<p>To access parameters submitted in the URL (<tt class="docutils literal"><span class="pre">?key=value</span></tt>) you can use the
<tt class="xref py py-attr docutils literal"><span class="pre">args</span></tt> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">searchword</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">args</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'q'</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span>
</pre></div>
</div>
<p>We recommend accessing URL parameters with <cite>get</cite> or by catching the
<cite>KeyError</cite> because users might change the URL and presenting them a 400
bad request page in that case is not user friendly.</p>
<p>For a full list of methods and attributes of the request object, head over
to the <a class="reference internal" href="api.html#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">request</span></tt></a> documentation.</p>
</div>
<div class="section" id="file-uploads">
<h3>File Uploads<a class="headerlink" href="#file-uploads" title="Permalink to this headline">¶</a></h3>
<p>You can handle uploaded files with Flask easily. Just make sure not to
forget to set the <tt class="docutils literal"><span class="pre">enctype="multipart/form-data"</span></tt> attribute on your HTML
form, otherwise the browser will not transmit your files at all.</p>
<p>Uploaded files are stored in memory or at a temporary location on the
filesystem. You can access those files by looking at the
<tt class="xref py py-attr docutils literal"><span class="pre">files</span></tt> attribute on the request object. Each
uploaded file is stored in that dictionary. It behaves just like a
standard Python <tt class="xref py py-class docutils literal"><span class="pre">file</span></tt> object, but it also has a
<a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.FileStorage.save" title="(in Werkzeug v0.7)"><tt class="xref py py-meth docutils literal"><span class="pre">save()</span></tt></a> method that allows you to store that
file on the filesystem of the server. Here is a simple example showing how
that works:</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">request</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/upload'</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s">'GET'</span><span class="p">,</span> <span class="s">'POST'</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">upload_file</span><span class="p">():</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span><span class="p">:</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">files</span><span class="p">[</span><span class="s">'the_file'</span><span class="p">]</span>
<span class="n">f</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s">'/var/www/uploads/uploaded_file.txt'</span><span class="p">)</span>
<span class="o">...</span>
</pre></div>
</div>
<p>If you want to know how the file was named on the client before it was
uploaded to your application, you can access the
<a class="reference external" href="http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.FileStorage.filename" title="(in Werkzeug v0.7)"><tt class="xref py py-attr docutils literal"><span class="pre">filename</span></tt></a> attribute. However please keep in
mind that this value can be forged so never ever trust that value. If you
want to use the filename of the client to store the file on the server,
pass it through the <a class="reference external" href="http://werkzeug.pocoo.org/docs/utils/#werkzeug.utils.secure_filename" title="(in Werkzeug v0.7)"><tt class="xref py py-func docutils literal"><span class="pre">secure_filename()</span></tt></a> function that
Werkzeug provides for you:</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">request</span>
<span class="kn">from</span> <span class="nn">werkzeug</span> <span class="kn">import</span> <span class="n">secure_filename</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/upload'</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s">'GET'</span><span class="p">,</span> <span class="s">'POST'</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">upload_file</span><span class="p">():</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span><span class="p">:</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">files</span><span class="p">[</span><span class="s">'the_file'</span><span class="p">]</span>
<span class="n">f</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s">'/var/www/uploads/'</span> <span class="o">+</span> <span class="n">secure_filename</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">filename</span><span class="p">))</span>
<span class="o">...</span>
</pre></div>
</div>
<p>For some better examples, checkout the <a class="reference internal" href="patterns/fileuploads.html#uploading-files"><em>Uploading Files</em></a> pattern.</p>
</div>
<div class="section" id="cookies">
<h3>Cookies<a class="headerlink" href="#cookies" title="Permalink to this headline">¶</a></h3>
<p>To access cookies you can use the <a class="reference internal" href="api.html#flask.Request.cookies" title="flask.Request.cookies"><tt class="xref py py-attr docutils literal"><span class="pre">cookies</span></tt></a>
attribute. To set cookies you can use the
<a class="reference internal" href="api.html#flask.Response.set_cookie" title="flask.Response.set_cookie"><tt class="xref py py-attr docutils literal"><span class="pre">set_cookie</span></tt></a> method of response objects. The
<a class="reference internal" href="api.html#flask.Request.cookies" title="flask.Request.cookies"><tt class="xref py py-attr docutils literal"><span class="pre">cookies</span></tt></a> attribute of request objects is a
dictionary with all the cookies the client transmits. If you want to use
sessions, do not use the cookies directly but instead use the
<a class="reference internal" href="#sessions"><em>Sessions</em></a> in Flask that add some security on top of cookies for you.</p>
<p>Reading cookies:</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">request</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">():</span>
<span class="n">username</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">cookies</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'username'</span><span class="p">)</span>
<span class="c"># use cookies.get(key) instead of cookies[key] to not get a</span>
<span class="c"># KeyError if the cookie is missing.</span>
</pre></div>
</div>
<p>Storing cookies:</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">make_response</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">():</span>
<span class="n">resp</span> <span class="o">=</span> <span class="n">make_response</span><span class="p">(</span><span class="n">render_template</span><span class="p">(</span><span class="o">...</span><span class="p">))</span>
<span class="n">resp</span><span class="o">.</span><span class="n">set_cookie</span><span class="p">(</span><span class="s">'username'</span><span class="p">,</span> <span class="s">'the username'</span><span class="p">)</span>
<span class="k">return</span> <span class="n">resp</span>
</pre></div>
</div>
<p>Note that cookies are set on response objects. Since you normally you
just return strings from the view functions Flask will convert them into
response objects for you. If you explicitly want to do that you can use
the <a class="reference internal" href="api.html#flask.make_response" title="flask.make_response"><tt class="xref py py-meth docutils literal"><span class="pre">make_response()</span></tt></a> function and then modify it.</p>
<p>Sometimes you might want to set a cookie at a point where the response
object does not exist yet. This is possible by utilizing the
<a class="reference internal" href="patterns/deferredcallbacks.html#deferred-callbacks"><em>Deferred Request Callbacks</em></a> pattern.</p>
<p>For this also see <a class="reference internal" href="#about-responses"><em>About Responses</em></a>.</p>
</div>
</div>
<div class="section" id="redirects-and-errors">
<h2>Redirects and Errors<a class="headerlink" href="#redirects-and-errors" title="Permalink to this headline">¶</a></h2>
<p>To redirect a user to somewhere else you can use the
<a class="reference internal" href="api.html#flask.redirect" title="flask.redirect"><tt class="xref py py-func docutils literal"><span class="pre">redirect()</span></tt></a> function. To abort a request early with an error
code use the <a class="reference internal" href="api.html#flask.abort" title="flask.abort"><tt class="xref py py-func docutils literal"><span class="pre">abort()</span></tt></a> function. Here an example how this works:</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">abort</span><span class="p">,</span> <span class="n">redirect</span><span class="p">,</span> <span class="n">url_for</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">():</span>
<span class="k">return</span> <span class="n">redirect</span><span class="p">(</span><span class="n">url_for</span><span class="p">(</span><span class="s">'login'</span><span class="p">))</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/login'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">login</span><span class="p">():</span>
<span class="n">abort</span><span class="p">(</span><span class="mi">401</span><span class="p">)</span>
<span class="n">this_is_never_executed</span><span class="p">()</span>
</pre></div>
</div>
<p>This is a rather pointless example because a user will be redirected from
the index to a page they cannot access (401 means access denied) but it
shows how that works.</p>
<p>By default a black and white error page is shown for each error code. If
you want to customize the error page, you can use the
<a class="reference internal" href="api.html#flask.Flask.errorhandler" title="flask.Flask.errorhandler"><tt class="xref py py-meth docutils literal"><span class="pre">errorhandler()</span></tt></a> decorator:</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">render_template</span>
<span class="nd">@app.errorhandler</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">page_not_found</span><span class="p">(</span><span class="n">error</span><span class="p">):</span>
<span class="k">return</span> <span class="n">render_template</span><span class="p">(</span><span class="s">'page_not_found.html'</span><span class="p">),</span> <span class="mi">404</span>
</pre></div>
</div>
<p>Note the <tt class="docutils literal"><span class="pre">404</span></tt> after the <a class="reference internal" href="api.html#flask.render_template" title="flask.render_template"><tt class="xref py py-func docutils literal"><span class="pre">render_template()</span></tt></a> call. This
tells Flask that the status code of that page should be 404 which means
not found. By default 200 is assumed which translates to: all went well.</p>
</div>
<div class="section" id="about-responses">
<span id="id6"></span><h2>About Responses<a class="headerlink" href="#about-responses" title="Permalink to this headline">¶</a></h2>
<p>The return value from a view function is automatically converted into a
response object for you. If the return value is a string it’s converted
into a response object with the string as response body, an <tt class="docutils literal"><span class="pre">200</span> <span class="pre">OK</span></tt>
error code and a <tt class="docutils literal"><span class="pre">text/html</span></tt> mimetype. The logic that Flask applies to
converting return values into response objects is as follows:</p>
<ol class="arabic simple">
<li>If a response object of the correct type is returned it’s directly
returned from the view.</li>
<li>If it’s a string, a response object is created with that data and the
default parameters.</li>
<li>If a tuple is returned the response object is created by passing the
tuple as arguments to the response object’s constructor.</li>
<li>If neither of that works, Flask will assume the return value is a
valid WSGI application and converts that into a response object.</li>
</ol>
<p>If you want to get hold of the resulting response object inside the view
you can use the <a class="reference internal" href="api.html#flask.make_response" title="flask.make_response"><tt class="xref py py-func docutils literal"><span class="pre">make_response()</span></tt></a> function.</p>
<p>Imagine you have a view like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.errorhandler</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">not_found</span><span class="p">(</span><span class="n">error</span><span class="p">):</span>
<span class="k">return</span> <span class="n">render_template</span><span class="p">(</span><span class="s">'error.html'</span><span class="p">),</span> <span class="mi">404</span>
</pre></div>
</div>
<p>You just need to wrap the return expression with
<a class="reference internal" href="api.html#flask.make_response" title="flask.make_response"><tt class="xref py py-func docutils literal"><span class="pre">make_response()</span></tt></a> and get the result object to modify it, then
return it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.errorhandler</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">not_found</span><span class="p">(</span><span class="n">error</span><span class="p">):</span>
<span class="n">resp</span> <span class="o">=</span> <span class="n">make_response</span><span class="p">(</span><span class="n">render_template</span><span class="p">(</span><span class="s">'error.html'</span><span class="p">),</span> <span class="mi">404</span><span class="p">)</span>
<span class="n">resp</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s">'X-Something'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'A value'</span>
<span class="k">return</span> <span class="n">resp</span>
</pre></div>
</div>
</div>
<div class="section" id="sessions">
<span id="id7"></span><h2>Sessions<a class="headerlink" href="#sessions" title="Permalink to this headline">¶</a></h2>
<p>Besides the request object there is also a second object called
<a class="reference internal" href="api.html#flask.session" title="flask.session"><tt class="xref py py-class docutils literal"><span class="pre">session</span></tt></a> that allows you to store information specific to a
user from one request to the next. This is implemented on top of cookies
for you and signs the cookies cryptographically. What this means is that
the user could look at the contents of your cookie but not modify it,
unless they know the secret key used for signing.</p>
<p>In order to use sessions you have to set a secret key. Here is how
sessions work:</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="p">,</span> <span class="n">session</span><span class="p">,</span> <span class="n">redirect</span><span class="p">,</span> <span class="n">url_for</span><span class="p">,</span> <span class="n">escape</span><span class="p">,</span> <span class="n">request</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="nd">@app.route</span><span class="p">(</span><span class="s">'/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">index</span><span class="p">():</span>
<span class="k">if</span> <span class="s">'username'</span> <span class="ow">in</span> <span class="n">session</span><span class="p">:</span>
<span class="k">return</span> <span class="s">'Logged in as </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="n">escape</span><span class="p">(</span><span class="n">session</span><span class="p">[</span><span class="s">'username'</span><span class="p">])</span>
<span class="k">return</span> <span class="s">'You are not logged in'</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/login'</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s">'GET'</span><span class="p">,</span> <span class="s">'POST'</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">login</span><span class="p">():</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">==</span> <span class="s">'POST'</span><span class="p">:</span>
<span class="n">session</span><span class="p">[</span><span class="s">'username'</span><span class="p">]</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">form</span><span class="p">[</span><span class="s">'username'</span><span class="p">]</span>
<span class="k">return</span> <span class="n">redirect</span><span class="p">(</span><span class="n">url_for</span><span class="p">(</span><span class="s">'index'</span><span class="p">))</span>
<span class="k">return</span> <span class="s">'''</span>
<span class="s"> <form action="" method="post"></span>
<span class="s"> <p><input type=text name=username></span>
<span class="s"> <p><input type=submit value=Login></span>
<span class="s"> </form></span>
<span class="s"> '''</span>
<span class="nd">@app.route</span><span class="p">(</span><span class="s">'/logout'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">logout</span><span class="p">():</span>
<span class="c"># remove the username from the session if its there</span>
<span class="n">session</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s">'username'</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
<span class="k">return</span> <span class="n">redirect</span><span class="p">(</span><span class="n">url_for</span><span class="p">(</span><span class="s">'index'</span><span class="p">))</span>
<span class="c"># set the secret key. keep this really secret:</span>
<span class="n">app</span><span class="o">.</span><span class="n">secret_key</span> <span class="o">=</span> <span class="s">'A0Zr98j/3yX R~XHH!jmN]LWX/,?RT'</span>
</pre></div>
</div>
<p>The here mentioned <a class="reference internal" href="api.html#flask.escape" title="flask.escape"><tt class="xref py py-func docutils literal"><span class="pre">escape()</span></tt></a> does escaping for you if you are
not using the template engine (like in this example).</p>
<div class="admonition-how-to-generate-good-secret-keys admonition ">
<p class="first admonition-title">How to generate good secret keys</p>
<p>The problem with random is that it’s hard to judge what random is. And
a secret key should be as random as possible. Your operating system
has ways to generate pretty random stuff based on a cryptographic
random generator which can be used to get such a key:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">os</span>
<span class="gp">>>> </span><span class="n">os</span><span class="o">.</span><span class="n">urandom</span><span class="p">(</span><span class="mi">24</span><span class="p">)</span>
<span class="go">'\xfd{H\xe5<\x95\xf9\xe3\x96.5\xd1\x01O<!\xd5\xa2\xa0\x9fR"\xa1\xa8'</span>
</pre></div>
</div>
<p class="last">Just take that thing and copy/paste it into your code and you’re done.</p>
</div>
</div>
<div class="section" id="message-flashing">
<h2>Message Flashing<a class="headerlink" href="#message-flashing" title="Permalink to this headline">¶</a></h2>
<p>Good applications and user interfaces are all about feedback. If the user
does not get enough feedback they will probably end up hating the
application. Flask provides a really simple way to give feedback to a
user with the flashing system. The flashing system basically makes it
possible to record a message at the end of a request and access it next
request and only next request. This is usually combined with a layout
template that does this.</p>
<p>To flash a message use the <a class="reference internal" href="api.html#flask.flash" title="flask.flash"><tt class="xref py py-func docutils literal"><span class="pre">flash()</span></tt></a> method, to get hold of the
messages you can use <a class="reference internal" href="api.html#flask.get_flashed_messages" title="flask.get_flashed_messages"><tt class="xref py py-func docutils literal"><span class="pre">get_flashed_messages()</span></tt></a> which is also
available in the templates. Check out the <a class="reference internal" href="patterns/flashing.html#message-flashing-pattern"><em>Message Flashing</em></a>
for a full example.</p>
</div>
<div class="section" id="logging">
<h2>Logging<a class="headerlink" href="#logging" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 0.3.</span></p>
<p>Sometimes you might be in a situation where you deal with data that
should be correct, but actually is not. For example you may have some client
side code that sends an HTTP request to the server but it’s obviously
malformed. This might be caused by a user tempering with the data, or the
client code failing. Most of the time, it’s okay to reply with <tt class="docutils literal"><span class="pre">400</span> <span class="pre">Bad</span>
<span class="pre">Request</span></tt> in that situation, but sometimes that won’t do and the code has
to continue working.</p>
<p>You may still want to log that something fishy happened. This is where
loggers come in handy. As of Flask 0.3 a logger is preconfigured for you
to use.</p>
<p>Here are some example log calls:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">'A value for debugging'</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s">'A warning occurred (</span><span class="si">%d</span><span class="s"> apples)'</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">'An error occurred'</span><span class="p">)</span>
</pre></div>
</div>
<p>The attached <a class="reference internal" href="api.html#flask.Flask.logger" title="flask.Flask.logger"><tt class="xref py py-attr docutils literal"><span class="pre">logger</span></tt></a> is a standard logging
<a class="reference external" href="http://docs.python.org/dev/library/logging.html#logging.Logger" title="(in Python v3.3)"><tt class="xref py py-class docutils literal"><span class="pre">Logger</span></tt></a>, so head over to the official <a class="reference external" href="http://docs.python.org/library/logging.html">logging
documentation</a> for more
information.</p>
</div>
<div class="section" id="hooking-in-wsgi-middlewares">
<h2>Hooking in WSGI Middlewares<a class="headerlink" href="#hooking-in-wsgi-middlewares" title="Permalink to this headline">¶</a></h2>
<p>If you want to add a WSGI middleware to your application you can wrap the
internal WSGI application. For example if you want to use one of the
middlewares from the Werkzeug package to work around bugs in lighttpd, you
can do it like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">werkzeug.contrib.fixers</span> <span class="kn">import</span> <span class="n">LighttpdCGIRootFix</span>
<span class="n">app</span><span class="o">.</span><span class="n">wsgi_app</span> <span class="o">=</span> <span class="n">LighttpdCGIRootFix</span><span class="p">(</span><span class="n">app</span><span class="o">.</span><span class="n">wsgi_app</span><span class="p">)</span>
</pre></div>
</div>
</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="#">Quickstart</a><ul>
<li><a class="reference internal" href="#a-minimal-application">A Minimal Application</a></li>
<li><a class="reference internal" href="#debug-mode">Debug Mode</a></li>
<li><a class="reference internal" href="#routing">Routing</a><ul>
<li><a class="reference internal" href="#variable-rules">Variable Rules</a></li>
<li><a class="reference internal" href="#url-building">URL Building</a></li>
<li><a class="reference internal" href="#http-methods">HTTP Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#static-files">Static Files</a></li>
<li><a class="reference internal" href="#rendering-templates">Rendering Templates</a></li>
<li><a class="reference internal" href="#accessing-request-data">Accessing Request Data</a><ul>
<li><a class="reference internal" href="#context-locals">Context Locals</a></li>
<li><a class="reference internal" href="#the-request-object">The Request Object</a></li>
<li><a class="reference internal" href="#file-uploads">File Uploads</a></li>
<li><a class="reference internal" href="#cookies">Cookies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#redirects-and-errors">Redirects and Errors</a></li>
<li><a class="reference internal" href="#about-responses">About Responses</a></li>
<li><a class="reference internal" href="#sessions">Sessions</a></li>
<li><a class="reference internal" href="#message-flashing">Message Flashing</a></li>
<li><a class="reference internal" href="#logging">Logging</a></li>
<li><a class="reference internal" href="#hooking-in-wsgi-middlewares">Hooking in WSGI Middlewares</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="installation.html" title="previous chapter">Installation</a></li>
<li>Next: <a href="tutorial/index.html" title="next chapter">Tutorial</a></li>
</ul></li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/quickstart.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 2010, Armin Ronacher.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
|
