Flask Documentation Release 0.7dev July 14, 2014 Contents I User’s Guide1 1 Foreword3 1.1 What does “micro” mean?...........................3 1.2 A Framework and an Example........................4 1.3 Web Development is Dangerous.......................4 1.4 The Status of Python 3.............................4 2 Installation7 2.1 virtualenv....................................7 2.2 System Wide Installation...........................8 2.3 Living on the Edge...............................9 2.4 easy_install on Windows............................9 3 Quickstart 11 3.1 A Minimal Application............................ 11 3.2 Debug Mode.................................. 12 3.3 Routing..................................... 13 3.4 Static Files.................................... 17 3.5 Rendering Templates.............................. 17 3.6 Accessing Request Data............................ 19 3.7 Redirects and Errors.............................. 22 3.8 Sessions..................................... 22 3.9 Message Flashing................................ 23 3.10 Logging..................................... 24 3.11 Hooking in WSGI Middlewares....................... 24 4 Tutorial 25 4.1 Introducing Flaskr............................... 25 4.2 Step 0: Creating The Folders......................... 26 4.3 Step 1: Database Schema........................... 27 4.4 Step 2: Application Setup Code........................ 27 i 4.5 Step 3: Creating The Database........................ 29 4.6 Step 4: Request Database Connections.................... 30 4.7 Step 5: The View Functions.......................... 30 4.8 Step 6: The Templates............................. 32 4.9 Step 7: Adding Style.............................. 34 4.10 Bonus: Testing the Application........................ 35 5 Templates 37 5.1 Jinja Setup.................................... 37 5.2 Standard Context................................ 37 5.3 Standard Filters................................. 38 5.4 Controlling Autoescaping........................... 39 5.5 Registering Filters............................... 39 5.6 Context Processors............................... 40 6 Testing Flask Applications 41 6.1 The Application................................ 41 6.2 The Testing Skeleton.............................. 41 6.3 The First Test.................................. 42 6.4 Logging In and Out.............................. 43 6.5 Test Adding Messages............................. 44 6.6 Other Testing Tricks.............................. 44 6.7 Keeping the Context Around......................... 45 7 Handling Application Errors 47 7.1 Error Mails................................... 47 7.2 Logging to a File................................ 48 7.3 Controlling the Log Format.......................... 49 7.4 Other Libraries................................. 50 8 Configuration Handling 53 8.1 Configuration Basics.............................. 53 8.2 Builtin Configuration Values......................... 54 8.3 Configuring from Files............................. 55 8.4 Configuration Best Practices......................... 55 8.5 Development / Production.......................... 56 9 Signals 59 9.1 Subscribing to Signals............................. 59 9.2 Creating Signals................................ 61 9.3 Sending Signals................................. 61 9.4 Decorator Based Signal Subscriptions.................... 62 9.5 Core Signals................................... 62 10 Pluggable Views 65 10.1 Basic Principle................................. 65 10.2 Method Hints.................................. 66 10.3 Method Based Dispatching.......................... 67 ii 11 The Request Context 69 11.1 Diving into Context Locals.......................... 69 11.2 How the Context Works............................ 70 11.3 Callbacks and Errors.............................. 71 11.4 Teardown Callbacks.............................. 71 11.5 Notes On Proxies................................ 72 11.6 Context Preservation on Error........................ 73 12 Modular Applications with Blueprints 75 12.1 Why Blueprints?................................ 75 12.2 The Concept of Blueprints........................... 76 12.3 My First Blueprint............................... 76 12.4 Registering Blueprints............................. 76 12.5 Blueprint Resources.............................. 77 12.6 Building URLs................................. 78 13 Working with the Shell 81 13.1 Creating a Request Context.......................... 81 13.2 Firing Before/After Request......................... 82 13.3 Further Improving the Shell Experience................... 82 14 Patterns for Flask 83 14.1 Larger Applications.............................. 83 14.2 Application Factories............................. 85 14.3 Application Dispatching............................ 87 14.4 Using URL Processors............................. 90 14.5 Deploying with Distribute.......................... 92 14.6 Deploying with Fabric............................. 95 14.7 Using SQLite 3 with Flask........................... 99 14.8 SQLAlchemy in Flask............................. 101 14.9 Uploading Files................................. 104 14.10 Caching..................................... 108 14.11 View Decorators................................ 109 14.12 Form Validation with WTForms....................... 112 14.13 Template Inheritance.............................. 114 14.14 Message Flashing................................ 115 14.15 AJAX with jQuery............................... 117 14.16 Custom Error Pages.............................. 120 14.17 Lazily Loading Views............................. 121 14.18 MongoKit in Flask............................... 123 14.19 Adding a favicon................................ 126 15 Deployment Options 129 15.1 mod_wsgi (Apache).............................. 129 15.2 CGI........................................ 132 15.3 FastCGI..................................... 133 15.4 uWSGI...................................... 135 15.5 Other Servers.................................. 136 iii 16 Becoming Big 139 16.1 Why consider Forking?............................ 139 16.2 Scaling like a Pro................................ 140 16.3 Dialogue with the Community........................ 140 II API Reference 141 17 API 143 17.1 Application Object............................... 143 17.2 Blueprint Objects................................ 158 17.3 Incoming Request Data............................ 161 17.4 Response Objects................................ 163 17.5 Sessions..................................... 164 17.6 Application Globals.............................. 164 17.7 Useful Functions and Classes......................... 165 17.8 Message Flashing................................ 170 17.9 Returning JSON................................ 171 17.10 Template Rendering.............................. 172 17.11 Configuration.................................. 172 17.12 Useful Internals................................. 174 17.13 Signals...................................... 176 17.14 Class Based Views............................... 177 III Additional Notes 179 18 Design Decisions in Flask 181 18.1 The Explicit Application Object........................ 181 18.2 One Template Engine............................. 182 18.3 Micro with Dependencies........................... 183 18.4 Thread Locals.................................. 183 18.5 What Flask is, What Flask is Not....................... 184 19 HTML/XHTML FAQ 185 19.1 History of XHTML............................... 185 19.2 History of HTML5............................... 186 19.3 HTML versus XHTML............................. 186 19.4 What does “strict” mean?........................... 187 19.5 New technologies in HTML5......................... 188 19.6 What should be used?............................. 189 20 Security Considerations 191 20.1 Cross-Site Scripting (XSS)........................... 191 20.2 Cross-Site Request Forgery (CSRF)...................... 192 20.3 JSON Security.................................. 192 21 Unicode in Flask 195 21.1 Automatic Conversion............................. 195 iv 21.2 The Golden Rule................................ 196 21.3 Encoding and Decoding Yourself....................... 196 21.4 Configuring Editors.............................. 196 22 Flask Extension Development 199 22.1 Anatomy of an Extension........................... 199 22.2 “Hello Flaskext!”................................ 200 22.3 Initializing Extensions............................. 201 22.4 The Extension Code.............................. 202 22.5 Adding an init_app Function......................... 203 22.6 End-Of-Request Behavior........................... 204 22.7 Learn from Others............................... 205 22.8 Approved Extensions............................. 205 23 Pocoo Styleguide 207 23.1 General Layout................................. 207 23.2 Expressions and Statements.......................... 208 23.3 Naming Conventions............................. 209 23.4 Docstrings.................................... 210 23.5 Comments.................................... 210 24 Upgrading to Newer Releases 211 24.1 Version 0.7.................................... 211 24.2 Version 0.6.................................... 215 24.3 Version 0.5.................................... 215 24.4 Version 0.4.................................... 215 24.5 Version 0.3.................................... 216 25 Flask Changelog 217 25.1 Version 0.7.................................... 217 25.2 Version 0.6.1..................................