Flask Documentation

259 Pages·1.134 MB·English

Flask Documentation
Release 0.9-dev
March 13, 2012

CONTENTS
I User’s Guide 1
1 Foreword 3
1.1 Whatdoes“micro”mean? . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 WebDevelopmentisDangerous . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 TheStatusofPython3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Installation 5
2.1 virtualenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 System-WideInstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 LivingontheEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4 pipanddistributeonWindows . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Quickstart 9
3.1 AMinimalApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 DebugMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4 StaticFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.5 RenderingTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.6 AccessingRequestData . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.7 RedirectsandErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.8 AboutResponses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.9 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.10 MessageFlashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.11 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.12 HookinginWSGIMiddlewares . . . . . . . . . . . . . . . . . . . . . . . 23
3.13 DeployingtoaWebServer . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4 Tutorial 25
4.1 IntroducingFlaskr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2 Step0: CreatingTheFolders . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.3 Step1: DatabaseSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4 Step2: ApplicationSetupCode . . . . . . . . . . . . . . . . . . . . . . . . 27
4.5 Step3: CreatingTheDatabase . . . . . . . . . . . . . . . . . . . . . . . . 29
4.6 Step4: RequestDatabaseConnections . . . . . . . . . . . . . . . . . . . . 30
4.7 Step5: TheViewFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.8 Step6: TheTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
i
4.9 Step7: AddingStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.10 Bonus: TestingtheApplication . . . . . . . . . . . . . . . . . . . . . . . . 35
5 Templates 37
5.1 JinjaSetup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.2 StandardContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.3 StandardFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.4 ControllingAutoescaping . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.5 RegisteringFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.6 ContextProcessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6 TestingFlaskApplications 41
6.1 TheApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.2 TheTestingSkeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.3 TheFirstTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.4 LoggingInandOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.5 TestAddingMessages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.6 OtherTestingTricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.7 KeepingtheContextAround . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.8 AccessingandModifyingSessions . . . . . . . . . . . . . . . . . . . . . . 46
7 LoggingApplicationErrors 47
7.1 ErrorMails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.2 LoggingtoaFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.3 ControllingtheLogFormat . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.4 OtherLibraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
8 DebuggingApplicationErrors 53
8.1 WheninDoubt,RunManually . . . . . . . . . . . . . . . . . . . . . . . . 53
8.2 WorkingwithDebuggers . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
9 ConfigurationHandling 55
9.1 ConfigurationBasics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
9.2 BuiltinConfigurationValues . . . . . . . . . . . . . . . . . . . . . . . . . 56
9.3 ConfiguringfromFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
9.4 ConfigurationBestPractices . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.5 Development/Production . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.6 InstanceFolders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
10 Signals 63
10.1 SubscribingtoSignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.2 CreatingSignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
10.3 SendingSignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
10.4 DecoratorBasedSignalSubscriptions . . . . . . . . . . . . . . . . . . . . 66
10.5 CoreSignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
11 PluggableViews 69
11.1 BasicPrinciple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
11.2 MethodHints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
ii
11.3 MethodBasedDispatching . . . . . . . . . . . . . . . . . . . . . . . . . . 71
11.4 DecoratingViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
11.5 MethodViewsforAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
12 TheRequestContext 75
12.1 DivingintoContextLocals . . . . . . . . . . . . . . . . . . . . . . . . . . 75
12.2 HowtheContextWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
12.3 CallbacksandErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
12.4 TeardownCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
12.5 NotesOnProxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
12.6 ContextPreservationonError . . . . . . . . . . . . . . . . . . . . . . . . 79
13 ModularApplicationswithBlueprints 81
13.1 WhyBlueprints? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
13.2 TheConceptofBlueprints . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
13.3 MyFirstBlueprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
13.4 RegisteringBlueprints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
13.5 BlueprintResources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
13.6 BuildingURLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
14 FlaskExtensions 87
14.1 FindingExtensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
14.2 UsingExtensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
14.3 FlaskBefore0.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
15 WorkingwiththeShell 89
15.1 CreatingaRequestContext . . . . . . . . . . . . . . . . . . . . . . . . . . 89
15.2 FiringBefore/AfterRequest . . . . . . . . . . . . . . . . . . . . . . . . . 90
15.3 FurtherImprovingtheShellExperience . . . . . . . . . . . . . . . . . . . 90
16 PatternsforFlask 91
16.1 LargerApplications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
16.2 ApplicationFactories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
16.3 ApplicationDispatching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
16.4 UsingURLProcessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
16.5 DeployingwithDistribute . . . . . . . . . . . . . . . . . . . . . . . . . . 100
16.6 DeployingwithFabric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
16.7 UsingSQLite3withFlask . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
16.8 SQLAlchemyinFlask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
16.9 UploadingFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
16.10 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
16.11 ViewDecorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
16.12 FormValidationwithWTForms . . . . . . . . . . . . . . . . . . . . . . . 120
16.13 TemplateInheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
16.14 MessageFlashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
16.15 AJAXwithjQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
16.16 CustomErrorPages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
16.17 LazilyLoadingViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
16.18 MongoKitinFlask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
iii
16.19 Addingafavicon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
16.20 StreamingContents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
16.21 DeferredRequestCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . 137
17 DeploymentOptions 139
17.1 mod_wsgi(Apache) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
17.2 CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
17.3 FastCGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
17.4 uWSGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
17.5 OtherServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
18 BecomingBig 149
18.1 WhyconsiderForking? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
18.2 ScalinglikeaPro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
18.3 DialoguewiththeCommunity . . . . . . . . . . . . . . . . . . . . . . . . 150
II API Reference 151
19 API 153
19.1 ApplicationObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
19.2 BlueprintObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
19.3 IncomingRequestData . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
19.4 ResponseObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
19.5 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
19.6 SessionInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
19.7 TestClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
19.8 ApplicationGlobals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
19.9 UsefulFunctionsandClasses . . . . . . . . . . . . . . . . . . . . . . . . . 179
19.10 MessageFlashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
19.11 ReturningJSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
19.12 TemplateRendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
19.13 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
19.14 Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
19.15 UsefulInternals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
19.16 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
19.17 Class-BasedViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
19.18 URLRouteRegistrations . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
19.19 ViewFunctionOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
III Additional Notes 197
20 DesignDecisionsinFlask 199
20.1 TheExplicitApplicationObject . . . . . . . . . . . . . . . . . . . . . . . . 199
20.2 TheRoutingSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
20.3 OneTemplateEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
20.4 MicrowithDependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
20.5 ThreadLocals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
iv
20.6 WhatFlaskis,WhatFlaskisNot . . . . . . . . . . . . . . . . . . . . . . . 202
21 HTML/XHTMLFAQ 203
21.1 HistoryofXHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
21.2 HistoryofHTML5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
21.3 HTMLversusXHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
21.4 Whatdoes“strict”mean? . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
21.5 NewtechnologiesinHTML5 . . . . . . . . . . . . . . . . . . . . . . . . . 206
21.6 Whatshouldbeused? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
22 SecurityConsiderations 207
22.1 Cross-SiteScripting(XSS) . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
22.2 Cross-SiteRequestForgery(CSRF) . . . . . . . . . . . . . . . . . . . . . . 208
22.3 JSONSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
23 UnicodeinFlask 211
23.1 AutomaticConversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
23.2 TheGoldenRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
23.3 EncodingandDecodingYourself . . . . . . . . . . . . . . . . . . . . . . . 212
23.4 ConfiguringEditors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
24 FlaskExtensionDevelopment 215
24.1 AnatomyofanExtension . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
24.2 “HelloFlaskext!” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
24.3 InitializingExtensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
24.4 TheExtensionCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
24.5 Addinganinit_appFunction . . . . . . . . . . . . . . . . . . . . . . . . . 219
24.6 End-Of-RequestBehavior . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
24.7 LearnfromOthers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
24.8 ApprovedExtensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
24.9 ExtensionImportTransition . . . . . . . . . . . . . . . . . . . . . . . . . 222
25 PocooStyleguide 223
25.1 GeneralLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
25.2 ExpressionsandStatements . . . . . . . . . . . . . . . . . . . . . . . . . . 224
25.3 NamingConventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
25.4 Docstrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
25.5 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
26 UpgradingtoNewerReleases 227
26.1 Version0.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
26.2 Version0.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
26.3 Version0.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
26.4 Version0.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
26.5 Version0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
26.6 Version0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
27 FlaskChangelog 235
27.1 Version0.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
v
27.2 Version0.8.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
27.3 Version0.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
27.4 Version0.7.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
27.5 Version0.7.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
27.6 Version0.7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
27.7 Version0.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
27.8 Version0.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
27.9 Version0.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
27.10 Version0.5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
27.11 Version0.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
27.12 Version0.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
27.13 Version0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
27.14 Version0.3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
27.15 Version0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
27.16 Version0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
27.17 Version0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
28 License 243
28.1 Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
28.2 GeneralLicenseDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . 244
28.3 FlaskLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
28.4 FlaskArtworkLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Index 247
vi
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