The Definitive Guide to Django

The Definitive Guide to Django Web Development Done Right, Second Edition cession No. ok ID for signout Adrian Holovaty and Jacob Kaplan-Moss 882 Apresse

Contents at a Glance About the Author.................................... xxvii About the Technical Reviewer.............................. xxix Acknowledgments............................................. xxxi Preface........................................ xxxiii Introduction......................... ~............ xxxv PART 1 Getting Started CHAPTER 1 Introduction to Django........................ 3 CHAPTER 2 Getting Started................................ 11 CHAPTER 3 Views and URLconfs........................ 21 CHAPTER 4 Templates..................................... 39 CHAPTER 5 Models......................................... 71 CHAPTER 6 The Django Admin Site.............................. 95 CHAPTER 7 Forms................... 119 PART 2 Advanced Usage CHAPTER 8 Advanced Views and URLconfs.................... 145 CHAPTER 9 Advanced Templates............. 167 CHAPTER 10 Advanced Models........................ 191 CHAPTER 11 Generic Views......................... 203 CHAPTER 12 Deploying Django..................................... 213 PART 3 CHAPTER 13 CHAPTER 14 CHAPTER 15 CHAPTER 16 CHAPTER 17 CHAPTER 18 CHAPTER 19 CHAPTER20 PART 4 APPENDIX A APPENDIX B APPENDIX C APPENDIX D APPENDIX E APPENDIX F APPENDIX G INDEX....... iv

Contents About the Author..................................... xxvii About the Technical Reviewer....................................... xxix Acknowledgments...................................... xxxi Preface..................................... xxxiii Introduction............................. xxxv PART 1 Getting Started CHAPTER 1 Introduction to Django............... 3 What Is a Web Framework?.............................. 3 The MVC Design Pattern............................ 5 Django's History............................ 7 How to Read This Book.............. 8 Required Programming Knowledge............... 8 Required Python Knowledge......................... 8 Required Django Version....... 9 Getting Help.............................. 9 What's Next?............................ 9 CHAPTER 2 Getting Started.............. 11 Installing Python................. 11 Python Versions........................... 11 Installation................................. 12 Installing Django................................. 12 Installing an Official Release........................ 12 Installing the Trunk Version............ 13 Testing the Django Installation............ 14 vii

viii CONTENTS Setting Up a Database...................... 15 Using Django with PostgreSQL........ 16 Using Django with SQLite 3..................... 16 Using Django with MySQL...................... 17 Using Django with Oracle..................... 17 Using Django Without a Database........ 17 Starting a Project....................... 17 Running the Development Server.................... 18 What's Next?.............. 19 CHAPTER 5 CHAPTER 3 Views and URLconfs............... 21 Your First Django-Powered Page: Hello World............... 21 Your First View........................... 21 Your First URLconf................................ 22 A Quick Note About 404 Errors...... 26 A Quick Note About the Site Root................ 27 How Django Processes a Request........................ 28 Your Second View: Dynamic Content..................... 28 URLconfs and Loose Coupling........................... 31 Your Third View: Dynamic URLs..................... 31 Django's Pretty Error Pages.......................... 35 What's Next?................................. 37 CHAPTER 4 Templates................................ 39 Template-System Basics......................... 40 Using the Template System........................ 41 Creating Template Objects............... 42 Rendering a Template......................... 43 Multiple Contexts, Same Template...................... 45 Context Variable Lookup........................ 46 Playing with Context Objects............. 49 Basic Template Tags and Filters..................... 50 Tags...................................... 50 Filters........................... _........... 56 Philosophies and Limitations............. 57 Using Templates in Views............... 58 CHAPTER 6

CONTENTS ix............... 15............ 16............. 16............. ' 17.............. 17............. '' 17....... 17......... ' 18............... 19.............. 21............ 21.............. 21............. 22............ 26.............. 27.............. 28........... 28.......... 31............. 31............. 35............ ' 37.............. 39......... 40.............. 41............. 42........... 43............. 45............. 46........... 49.............. 50........... 50..... '........ 56.............. 57............ 58 CHAPTER 5 CHAPTER 6 Template Loading.......................... 60 render_to_response()................................. 63 The locals() Trick................................. 63 Subdirectories in get_ template()........................... 64 The include Template Tag................................ 65 Template Inheritance......................... 66 What's Next?................................... 70 Models............................ 71 The "Dumb" Way to Do Database Queries in Views.................. 71 The MTV (or MVC) Development Pattern............. 72 Configuring the Database.................... 74 Your First App................................ 76 Defining Models in Python........................ 77 Your First Model............................. 78 Installing the Model.................................. 80 Basic Data Access..................... 83 Adding Model String Representations........................... 84 Inserting and Updating Data.................... 86 Selecting Objects................... 88 Filtering Data............................ 88 Retrieving Single Objects...................... 89 Ordering Data..................... 90 Chaining Lookups.................... 91 Slicing Data................................ 92 Updating Multiple Objects in One Statement.............. 92 Deleting Objects....................... 93 What's Next?......................................... 94 The Django Admin Site.............. 95 The django.contrib Packages............................ 95 Activating the Admin Interface............................. 96 Using the Admin Site.................... 97 Adding Your Models to the Admin Site.......................... 102 How the Admin Site Works............. 103 Making Fields Optional........................ 1 03 Making Date and Numeric Fields Optional.................. 104 Customizing Field Labels.......................... 105

x CONTENTS Custom ModeiAdmin Classes............ 106 Customizing Change Lists.............. 106 Customizing Edit Forms............. 112 Users, Groups, and Permissions..................... 116 When and Why to Use the Admin Interface-And When NotTo.... 117 What's Next?....................... 118 CHAPTER 7 Forms................................ 119 Getting Data from the Request Object................... 119 Information About the URL........... 119 Other Information About the Request...................... 120 CHAPTER 9 Information About Submitted Data............ 121 A Simple Form-Handling Example.................... 122 Improving Our Simple Form-Handling Example................. 125 Simple Validation......................... 127 Making a Contact Form............................. 129 Your First Form Class............. 133 Tying Form Objects into Views............. 136 Changing How Fields Are Rendered.................. 137 Setting a Maximum Length............... 137 Setting Initial Values...................... 138 Adding Custom Validation Rules............. 138 Specifying Labels........................ 139 Customizing Form Design............. 139 What's Next?.................... 141 PART 2 Advanced Usage CHAPTER 8 Advanced Views and URLconfs................ 145 URLconfTricks...................... 145 Streamlining Function Imports......... 145 Using Multiple View Prefixes........... 147 Special-Casing URLs in Debug Mode...................... 148 Using Named Groups.................... 148 Understanding the Matching/Grouping Algorithm............ 150 Passing Extra Options to View Functions.............. 150 Using Default View Arguments......... 155

CONTENTS xi ''....... 106.. '''.'..... 106........... 112 ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' 116 n NotT o.... 117........ 118 '.'....... '.... 119............. 119 '......... 119 '... 120....... '.... 121.. '.'.. '..... 122........... 125....... 127. '............ 129... 133.......... 136......... 137........... 137........... 138. '... '... 138. '..... 139....... 139...... '... 141........... 145.......... 145........... 145.......... 147... '... 148 '...... '.... 148...... '''... '. 150........ '.... 150........ '' ' 155 CHAPTER 9 Special-Casing Views....................... 156 Capturing Text in URLs.................... 157 Determining What the URLconf Searches Against............ 158 Higher-Level Abstractions of View Functions............. 158 Wrapping View Functions.............. 161 Including Other URLconts................. 162 How Captured Parameters Work with includeo........ 163 How Extra URLcont Options Work with includeo...... 164 What's Next?............................... 165 Advanced Templat~s........................... 167 Template Language Review................ 167 RequestContext and Context Processors................... 168 django.core.context_processors.auth.............. 171 django.core.context_processors.debug................. 171 django.core.context_processors.i18n................... 172 django.core.context_processors.request................. 172 Guidelines tor Writing Your Own Context Processors......... 172 Automatic HTML Escaping...................... 173 How to Turn It Ott.......................... 174 Notes................................... 175 Automatic Escaping of String Literals in Filter Arguments...... 176 Inside Template Loading.................. 176 Extending the Template System.................. 177 Creating a Template Library.................... 177 Writing Custom Template Filters............. 178 Writing Custom Template Tags........................ 180 Writing the Compilation Function......................... 180 Writing the Template Node....................... 182 Registering the Tag................ 182 Setting a Variable in the Context............... 183 Parsing Until Another Template Tag.................. 184 Parsing Until Another Template Tag and Saving Contents... 185 Shortcut for Simple Tags.......................... 185 Inclusion Tags............................... 186 Writing Custom Template Loaders............. 188 Configuring the Template System in Standalone Mode...... 189 What's Next?............................ 190

xil CONTENTS CHAPTER 1 o Advanced Models................. 191 Related Objects...................................... 191 Accessing Foreign Key Values.................. 192 Accessing Many-to-Many Values.... 193 Making Changes to a Database Schema.... 193 Adding Fields.............................. 193 Removing Fields................................ 196 Removing Many-to-Many Fields........... 196 Removing Models................................ 196 Managers................................... 1 97 Adding Extra Manager Methods... :....... 197 Modifying Initial Manager QuerySets... 198 Model Methods...................................... 199 Executing Raw SOL Queries...................... 200 What's Next?......................... 201 CHAPTER 11 Generic Views......................... 203 Using Generic Views........................ 204 Generic Views of Objects......................... 205 Extending Generic Views.......................... 207 Making "Friendly" Template Contexts............. 207 Adding Extra Context....................... 208 Viewing Subsets of Objects................ 209 Complex Filtering with Wrapper Functions......... 210 Performing Extra Work................................ 211 What's Next?............................. 212 CHAPTER 12 Deploying Django........................ 213 Preparing Your Codebase for Production...... 213 Turning Off Debug Mode............... 213 Turning Off Template Debug Mode.................... 214 Implementing a 404 Template.............. 214 Implementing a 500 Template............ 214 Setting Up Error Alerts............. 215 Setting Up Broken Link Alerts................ 215 Using Different Settings for Production......... 216 DJANGO_SETIINGS_MODULE............... 217 PART 3 CHAPTER 13 Usi1 Usi1 Sea Per Wh Ge ThE Pro Ger

CONTENTS xiii........ 191.............. 191.......... 192......... 193....... 193........ 193...... 196........... 196......... 196........... 197... 197............. 198............. 199........... 200............. 201....... 203............. 204.... 205............ 207.......... 207........ 208............. 209....... 210............. 211....... 212............ 213.......... 213....... 213..... 214... 214...... 214... 215...... 215.............. 216........ 217 PART 3 Using Django with Apache and mod_python................... 218 Basic Configuration......................... 218 Running Multiple Django Installations on the Same Apache Instance............ 219 Running a Development Server with mod_python........ 220 Serving Django and Media Files from the Same Apache Instance....................... 220 Error Handling.............................. 221 Handling a Segmentation Fault.................... 221 An Alternative: mod_wsgi........................ 222 Using Django with FastCGI........................ 222 FastCGI Overview.~........................ 222 Running Your FastCGI Server....................... 223 Using Django with Apache and FastCGI................ 224 FastCGI and lighttpd.................. 225 Running Django on a Shared-Hosting Provider with Apache... 227 Scaling............................. 228 Running on a Single Server...................... 228 Separating Out the Database Server................... 229 Running a Separate Media Server...................... 229 Implementing Load Balancing and Redundancy........... 230 Going Big.................... 232 Performance Tuning.................... 232 There's No Such Thing As Too Much RAM............... 233 Turn Off Keep-Alive..................... 233 Use Memcached.......................................... 233 Use Memcached Often................................ 234 Join the Conversation.................... 234 What's Next?................................... 234 Other Django Features CHAPTER 13 Generating Non-HTML Content............ 237 The Basics: Views and MIME Types................ 237 Producing CSV.......................... 238 Generating PDFs........................... 239 Installing Reportlab............... 240 Writing Your View.................... 240 Complex PDFs................... 241

xiv CONTENTS Other Possibilities............................ 242 The Syndication-Feed Framework.................... 242 Initialization............................. 243 A Simple Feed....................... 244 A More Complex Feed...................... 245 Specifying the Type of Feed......................... 247 Enclosures..................................... 247 CHAPTER 15 Language................................... 248 URLs................................ 248 Publishing Atom and RSS Feeds in Tandem................. 248 The Sitemap Framework...................... 249 Installation........... ~........ 249 Initialization............................ 250 Sitemap Classes................................ 250 Shortcuts................................. 251 Creating a Sitemap Index..................... 252 Pinging Google..................................... 253 What's Next?............................... 254 CHAPTER 14 Sessions, Users, and Registration............... 255 Cookies........................ 255 Getting and Setting Cookies........................ 256 The Mixed Blessing of Cookies........... 257 Django's Session Framework........................ 258 Enabling Sessions.................... 258 Using Sessions in Views.............................. 259 Setting Test Cookies................................... 261 Using Sessions Outside of Views.................... 261 CHAPTER 16 When Sessions Are Saved....................... 262 Browser-Length Sessions vs. Persistent Sessions... 262 Other Session Settings.................. 263 Users and Authentication........................... 264 Enabling Authentication Support.................. 264 Using Users....................... 265 Logging In and Out............................ 267 limiting Access to Logged-in Users...................... 269 limiting Access to Users Who Pass a Test...... 269 Managing Users, Permissions, and Groups.............. 271 Using Authentication Data in Templates............. 273

CONTENTS xv.............. 242....... 242..... 243......... 244.......... 245...... 247..... 247.............. 248............ 248...... 248...... 249.... 249............ 250.... 250........... 251........ 252....... 253....... 254.......... 255............. 255........... 256.......... 257...... 258......... 258....... 259...... 261......... 261...... 262........... 262...... 263... 264..... 264......... 265........... 267........... 269.... 269........... 271...... 273 Permissions, Groups, and Messages......... 274 Permissions................................. 27 4 Groups......................... 275 Messages...................... 275 What's Next?................ 276 CHAPTER 15 Caching............ 277 Setting Up the Cache.............................. 278 Memcached................................ 278 Database Caching............................... 279 Filesystem Caching........................ 279 Local-Memory Caching........................ 280 Dummy Caching (for Development)......... 280 Using a Custom Cache Back-End................ 280 CACHE_BACKEND Arguments.......... 281 The Per-Site Cache........................ 281 The Per-View Cache....................... 282 Specifying Per-View Cache in the URLconf............ 283 Template Fragment Caching......................... 284 The Low-Level Cache API...................... 284 Upstream Caches........................ 286 Using Vary Headers............................ 287 Controlling Cache: Using Other Headers....... 288 Other Optimizations............... 290 Order of MIDDLEWARE_CLASSES..................... 290 What's Next?..................... 290 CHAPTER 16 django.contrib......................... 291 The Django Standard Library........................ 291 Sites..................................... 293 Scenario 1: Reusing Data on Multiple Sites................ 293 Scenario 2: Storing Your Site Name/Domain in One Place... 293 How to Use the Sites Framework........... 293 The Sites Framework's Capabilities...................... 294 CurrentSiteManager................... 297 How Django Uses the Sites Framework........... 298 Flatpages........................................... 299 Using Flatpages................. 299 Adding, Changing, and Deleting Flatpages............ 301 Using Flatpage Templates................... 301

xvi CONTENTS Redirects...................................... 302 Using the Redirects Framework........................ 302 Adding, Changing, and Deleting Redirects............... 303 CSRF Protection........................................... 304 A Simple CSRF Example........................ 304 A More Complex CSRF Example......................... 304 Preventing CSRF................................. 304 Humanizing Data.............................. 306 apnumber................................. 306 intcomma.......................... 306 intword.............................. J.. 306 ordinal.................................. 307 Markup Filters................ 307 What's Next?.................................... 307 CHAPTER 18 lnt1 lnte lnte lnte Wh< CHAPTER 19 lnt 1 Hov CHAPTER 17 Middleware.................................... 309 What's Middleware?......................................... 309 Middleware Installation................................. 310 Middleware Methods...................................... 311 lnitializer: _ init_(self).......................... 311 Request Preprocessor: process_request(self, request)..... 311 View Preprocessor: process_view(self, request, view, args, kwargs).......................................... 311 Response Postprocessor: process_response(self, request, response)............................ 312 Exception Postprocessor: process_exception(self, request, exception)................................ 312 Built-in Middleware....................................... 313 Authentication Support Middleware............... 313 "Common" Middleware........................... 313 Compression Middleware........................ 314 Conditional GET Middleware.............................. 314 Reverse Proxy Support (X-Forwarded-For Middleware)... 314 Session Support Middleware............................. 315 Sitewide Cache Middleware....................... 315 Transaction Middleware......................... 315 What's Next?................................. 315 CHAPTER 20 Ho Hov Usi The Tr Not ge Wh Se The Sat Cro Cro Ses

CONTENTS xvii........ 302...... 302.............. 303............ 304..... 304........ 304........... 304.......... 306....... 306........... 306..... 306.......... 307.............. 307........ 307......... 309....... 309.............. 310.... 311....... 311 uest)....... 311 view,............. 311,....... 312 f,.............. 312..... 313......... 313........ 313............. 314........ 314 Ware)... 314......... 315........ 315........... 315........... 315 chapter 18 Integrating with Legacy Databases and Applications... 317 Integrating with a Legacy Database.................. 317 Using inspectdb........................ 317 Cleaning Up Generated Models...................... 318 Integrating with an Authentication System....................... 319 Specifying Authentication Back-Ends.............. 319 Writing an Authentication Back-End........................ 319 Integrating with Legacy Web Applications..................... 321 What's Next?.............................................. 322 chapter 19 lnternationalizatim1.............. 323 How to Specify Translation Strings................ 324 In Python Code............. 324 In Template Code.................... 327 Working with Lazy Translation Objects................. 329 How to Create Language Files............................ 330 Message Files................................ 330 Compiling Message Files............... 332 How Django Discovers Language Preference............. 333 Using Translations in Your Own Projects........ 335 The set_language Redirect View.............. 336 Translations and JavaScript.......... 337 The javascript_catalog View........... 337 Using the JavaScript Translation Catalog........ 337 Creating JavaScript Translation Catalogs...... 339 Notes for Users Familiar with gettext........... 339 gettext on Windows......................... 339 What's Next?.......... 340 CHAPTER 20 Security......... 341 The Theme of Web Security.................. 341 SOL Injection......................................... 342 The Solution.............. 343 Cross-Site Scripting (XSS)................ 343 The Solution........................... 344 Cross-Site Request Forgery.......... 345 Session Forging/Hijacking.............................. 345 The Solution................. 346

xviii CONTENTS E-mail Header Injection..................... 347 The Solution.................... 347 Directory Traversal............... 347 The Solution............... 348 Exposed Error Messages.................... 349 The Solution............................ 349 A Final Word on Security............. 349 What's Next?................. 349 PART 4 Appendixes APPENDIX A Model Definition Reference........ 353 Fields................. 353 AutoField.................... 354 BooleanField................ 354 CharField...................... 354 CommaSeparatedlntegerField.............. 354 DateField.......... 355 DateTimeField..................... 355 Decimal Field......................... 355 Email Field............................ 355 FileField......... 355 FilePathField............... 357 FloatField............................. 357 lmagefield................ 357 lntegerfield........... 358 IPAddressField................... 358 NuiiBooleanField..................... 358 PositivelntegerField......... 358 PositiveSmalllntegerField.......... 358 Slug Field................ 358 SmalllntegerField......... 358 TextField................. 358 Time Field........................... 358 URLField................................. 359 XMLField.......................... 359 APPENDIX B