Flask Documentation - Flask (A Python Microframework)

302 Pages·2016·0.91 MB·English

Flask Documentation
Release 0.10.1-20170321
Mar 21, 2017

CONTENTS
I User’s Guide 1
1 Foreword 3
2 ForewordforExperiencedProgrammers 5
3 Installation 7
4 Quickstart 11
5 Tutorial 27
6 Templates 39
7 TestingFlaskApplications 43
8 LoggingApplicationErrors 51
9 DebuggingApplicationErrors 57
10 ConfigurationHandling 59
11 Signals 67
12 PluggableViews 75
13 TheApplicationContext 81
14 TheRequestContext 85
15 ModularApplicationswithBlueprints 91
16 FlaskExtensions 97
17 WorkingwiththeShell 99
18 PatternsforFlask 101
19 DeploymentOptions 157
i
20 BecomingBig 171
II API Reference 175
21 API 177
III Additional Notes 235
22 DesignDecisionsinFlask 237
23 HTML/XHTMLFAQ 241
24 SecurityConsiderations 247
25 UnicodeinFlask 251
26 FlaskExtensionDevelopment 255
27 PocooStyleguide 263
28 Python3Support 267
29 UpgradingtoNewerReleases 269
30 FlaskChangelog 277
31 License 289
Index 293
ii
Part I
USER’S GUIDE
This part of the documentation, which is mostly prose, begins with some background
information about Flask, then focuses on step-by-step instructions for web develop-
mentwithFlask.
1
2
CHAPTER
ONE
FOREWORD
Read this before you get started with Flask. This hopefully answers some questions
about the purpose and goals of the project, and when you should or should not be
usingit.
1.1 What does “micro” mean?
“Micro”doesnotmeanthatyourwholewebapplicationhastofitintoasinglePython
file, although it certainly can. Nor does it mean that Flask is lacking in functionality.
The “micro” in microframework means Flask aims to keep the core simple but exten-
sible. Flask won’t make many decisions for you, such as what database to use. Those
decisionsthatitdoesmake,suchaswhattemplatingenginetouse,areeasytochange.
Everything else is up to you, so that Flask can be everything you need and nothing
youdon’t.
Bydefault,Flaskdoesnotincludeadatabaseabstractionlayer,formvalidationorany-
thing else where different libraries already exist that can handle that. Instead, Flask
supports extensions to add such functionality to your application as if it was imple-
mented in Flask itself. Numerous extensions provide database integration, form val-
idation, upload handling, various open authentication technologies, and more. Flask
maybe“micro”,butit’sreadyforproductionuseonavarietyofneeds.
1.2 Configuration and Conventions
Flask has many configuration values, with sensible defaults, and a few conventions
when getting started. By convention templates and static files are stored in subdirec-
tories within the application’s Python source tree, with the names templates and static
respectively. While this can be changed you usually don’t have to, especially when
gettingstarted.
3
1.3 Growing with Flask
Once you have Flask up and running, you’ll find a variety of extensions available in
the community to integrate your project for production. The Flask core team reviews
extensionsandensuresapprovedextensionsdonotbreakwithfuturereleases.
As your codebase grows, you are free to make the design decisions appropriate for
your project. Flask will continue to provide a very simple glue layer to the best that
Python has to offer. You can implement advanced patterns in SQLAlchemy or an-
otherdatabasetool,introducenon-relationaldatapersistenceasappropriate,andtake
advantageofframework-agnostictoolsbuiltforWSGI,thePythonwebinterface.
Flask includes many hooks to customize its behavior. Should you need more cus-
tomization, the Flask class is built for subclassing. If you are interested in that, check
outtheBecomingBigchapter. IfyouarecuriousabouttheFlaskdesignprinciples,head
overtothesectionaboutDesignDecisionsinFlask.
ContinuetoInstallation,theQuickstart,ortheForewordforExperiencedProgrammers.
4
CHAPTER
TWO
FOREWORD FOR EXPERIENCED
PROGRAMMERS
2.1 Thread-Locals in Flask
One of the design decisions in Flask was that simple tasks should be simple; they
should not take a lot of code and yet they should not limit you. Because of that, Flask
hasfewdesignchoicesthatsomepeoplemightfindsurprisingorunorthodox. Forex-
ample,Flaskusesthread-localobjectsinternallysothatyoudon’thavetopassobjects
around from function to function within a request in order to stay threadsafe. This
approach is convenient, but requires a valid request context for dependency injection
orwhenattemptingtoreusecodewhichusesavaluepeggedtotherequest. TheFlask
projectishonestaboutthread-locals,doesnothidethem,andcallsoutinthecodeand
documentationwheretheyareused.
2.2 Develop for the Web with Caution
Alwayskeepsecurityinmindwhenbuildingwebapplications.
If you write a web application, you are probably allowing users to register and leave
theirdataonyourserver. Theusersareentrustingyouwithdata. Andevenifyouare
the only user that might leave data in your application, you still want that data to be
storedsecurely.
Unfortunately, there are many ways the security of a web application can be com-
promised. Flask protects you against one of the most common security problems of
modern web applications: cross-site scripting (XSS). Unless you deliberately mark in-
secure HTML as secure, Flask and the underlying Jinja2 template engine have you
covered. Buttherearemanymorewaystocausesecurityproblems.
The documentation will warn you about aspects of web development that require at-
tention to security. Some of these security concerns are far more complex than one
might think, and we all sometimes underestimate the likelihood that a vulnerability
willbeexploited-untilacleverattackerfiguresoutawaytoexploitourapplications.
And don’t think that your application is not important enough to attract an attacker.
5
Dependingonthekindofattack,chancesarethatautomatedbotsareprobingforways
tofillyourdatabasewithspam,linkstomalicioussoftware,andthelike.
Flask is no different from any other framework in that you the developer must build
withcaution,watchingforexploitswhenbuildingtoyourrequirements.
2.3 The Status of Python 3
Currently the Python community is in the process of improving libraries to support
thenewiterationofthePython programminglanguage. Whilethesituationisgreatly
improving there are still some issues that make it hard for users to switch over to
Python 3 just now. These problems are partially caused by changes in the language
that went unreviewed for too long, partially also because we have not quite worked
out how the lower- level API should change to account for the Unicode differences in
Python3.
We strongly recommend using Python 2.6 and 2.7 with activated Python 3 warnings
during development. If you plan on upgrading to Python 3 in the near future we
stronglyrecommendthatyoureadHowtowriteforwardscompatiblePythoncode.
IfyoudowanttodiveintoPython3alreadyhavealookatthepython3_supportpage.
ContinuetoInstallationortheQuickstart.
6