The definitive guide to django

71 CHApTER 6 The Django Admin Site.. 17 Using Django Without a Database.. 94 CHApTER 6 The Django Admin Site.. 96 Using the Admin Site.. 145 Using Multiple View Prefixes.. 178 Writing C

The eXperT’s Voice® in WeB DeVelopmenT

The Definitive Guide to

Web Development Done Right

SeconD eDiTion

Adrian Holovaty

Benevolent Dictators for Life, Django

The Definitive Guide

All rights reserved No part of this work may be reproduced or transmitted in any form or by any means,

electronic or mechanical, including photocopying, recording, or by any information storage or retrieval

system, without the prior written permission of the copyright owner and the publisher

ISBN 13: 978-1-4302-1936-1

ISBN (electronic): 978-1-4302-1937-8

Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1

Trademarked names may appear in this book Rather than use a trademark symbol with every occurrence

of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark

owner, with no intention of infringement of the trademark

Java™ and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc., in the

US and other countries Apress, Inc., is not affiliated with Sun Microsystems, Inc., and this book was

writ-ten without endorsement from Sun Microsystems, Inc

Lead Editor: Duncan Parkes

Technical Reviewer: Sean Legassick

Editorial Board: Clay Andres, Steve Anglin, Mark Beckner, Ewan Buckingham, Tony Campbell,

Gary Cornell, Jonathan Gennick, Michelle Lowman, Matthew Moodie, Jeffrey Pepper, Frank Pohlmann,

Ben Renow-Clarke, Dominic Shakeshaft, Matt Wade, Tom Welsh

Project Managers: Grace Wong and James Markham

Copy Editors: Nancy Sixsmith and Candace English

Associate Production Director: Kari Brooks-Copony

Production Editor: Katie Stence

Compositor: Patrick Cunningham

Proofreader: April Eddy

Indexer: BIM Indexing & Proofreading Services

Artist: April Milne

Cover Designer: Kurt Krames

Manufacturing Director: Tom Debolski

Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor,

New York, NY 10013 Phone 1-800-SPRINGER, fax 201-348-4505, e-mail orders-ny@springer-sbm.com, or

visit http://www.springeronline.com

For information on translations, please contact Apress directly at 2855 Telegraph Avenue, Suite 600,

Berkeley, CA 94705 Phone 510-549-5930, fax 510-549-5939, e-mail info@apress.com, or visit http://www

apress.com

Apress and friends of ED books may be purchased in bulk for academic, corporate, or promotional use

eBook versions and licenses are also available for most titles For more information, reference our Special

Bulk Sales–eBook Licensing web page at http://www.apress.com/info/bulksales

The information in this book is distributed on an “as is” basis, without warranty Although every

precau-tion has been taken in the preparaprecau-tion of this work, neither the author(s) nor Apress shall have any liability

to any person or entity with respect to any loss or damage caused or alleged to be caused directly or

indi-rectly by the information contained in this work

The source code for this book is available to readers at http://www.apress.com

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

CHApTER 13 Generating Non-HTML Content 237

CHApTER 14 Sessions, Users, and Registration 255

CHApTER 15 Caching 277

CHApTER 16 django.contrib 291

CHApTER 17 Middleware 309

CHApTER 18 Integrating with Legacy Databases and Applications 317

CHApTER 19 Internationalization 323

CHApTER 20 Security 341

PART 4 ■ ■ ■ Appendixes AppEnDix A Model Definition Reference 353

AppEnDix B Database API Reference 369

AppEnDix C Generic View Reference 395

AppEnDix D Settings 413

AppEnDix E Built-in Template Tags and Filters 429

AppEnDix F The django-admin Utility 455

AppEnDix G Request and Response Objects 469

inDEx 479

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

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 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

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

CHApTER 5 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

CHApTER 6 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 103

Making Date and Numeric Fields Optional 104

Customizing Field Labels 105

Custom ModelAdmin 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 Not To 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

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

URLconf Tricks 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

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 URLconfs 162

How Captured Parameters Work with include() 163

How Extra URLconf Options Work with include() 164

What’s Next? 165

CHApTER 9 Advanced Templates 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 for Writing Your Own Context Processors 172

Automatic HTML Escaping 173

How to Turn It Off 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

CHApTER 10 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 197

Adding Extra Manager Methods 197

Modifying Initial Manager QuerySets 198

Model Methods 199

Executing Raw SQL 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_SETTINGS_MODULE 217

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

PART 3 ■ ■ ■ 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

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

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

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

Permissions, Groups, and Messages 274

Permissions 274

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

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 306

ordinal 307

Markup Filters 307

What’s Next? 307

CHApTER 17 Middleware 309

What’s Middleware? 309

Middleware Installation 310

Middleware Methods 311

Initializer: 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 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 internationalization 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

SQL 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

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

CommaSeparatedIntegerField 354

DateField 355

DateTimeField 355

DecimalField 355

EmailField 355

FileField 355

FilePathField 357

FloatField 357

ImageField 357

IntegerField 358

IPAddressField 358

NullBooleanField 358

PositiveIntegerField 358

PositiveSmallIntegerField 358

SlugField 358

SmallIntegerField 358

TextField 358

TimeField 358

URLField 359

XMLField 359

Universal Field Options 359

null 359

blank 360

choices 360

db_column 361

db_index 361

db_tablespace 361

default 361

editable 361

help_text 361

primary_key 362

unique 362

unique_for_date 362

unique_for_month 362

unique_for_year 362

verbose_name 362

Relationships 363

ForeignKey 363

ManyToManyField 364

OneToOneField 365

Model Metadata Options 365

abstract 365

db_table 366

db_tablespace 366

get_latest_by 366

managed 366

ordering 367

proxy 368

unique_together 368

verbose_name 368

verbose_name_plural 368

AppEnDix B Database Api Reference 369

Creating Objects 370

What Happens When You Save? 370

Autoincrementing Primary Keys 370

Saving Changes to Objects 371

Retrieving Objects 372

Caching and QuerySets 373

Filtering Objects 373

Chaining Filters 374

Limiting QuerySets 375

Query Methods That Return New QuerySets 376

QuerySet Methods That Do Not Return QuerySets 379

The pk Lookup Shortcut 385

Complex Lookups with Q Objects 385

Falling Back to Raw SQL 393

AppEnDix C Generic View Reference 395

Common Arguments to Generic Views 395

“Simple” Generic Views 396

Rendering a Template 396

Redirecting to Another URL 397

List/Detail Generic Views 397

Archive for Today 409

Date-Based Detail Pages 409

AppEnDix D Settings 413

The Basics of Settings Files 413

Default Settings 413

Seeing Which Settings You’ve Changed 414

Using Settings in Python Code 414

Altering Settings at Runtime 414

Security 414

Creating Your Own Settings 415

Designating the Settings: DJANGO_SETTINGS_MODULE 415

The django-admin py Utility 415

On the Server (mod_python) 416

Using Settings Without Setting DJANGO_SETTINGS_MODULE 416

Custom Default Settings 417

Either configure() or DJANGO_SETTINGS_MODULE Is Required 417

AppEnDix E Built-in Template Tags and Filters 429

Built-in Tag Reference 429

Determining the Version 456

Displaying Debug Output 456

sqlall <appname appname > 463

sqlclear <appname appname > 463

sqlcustom <appname appname > 464

sqlflush 464

sqlindexes <appname appname > 464

sqlreset <appname appname > 464

sqlsequencereset <appname appname > 464

Customizing the 404 (Not Found) View 476

Customizing the 500 (Server Error) View 477

inDEx 479

About the Authors

■ADRiAn HOLOVATy is a cocreator and co–Benevolent Dictator for Life of Django He runs a Web

start-up called EveryBlock He lives with his wife in Chicago and spends his free time

attempt-ing to play guitar in the style of Django Reinhardt

■JACOB KApLAn-MOSS is a lead developer and co–Benevolent Dictator for Life of Django Jacob

is a partner at Revolution Systems, a consultancy that helps companies make the most of open

source software Jacob previously worked for the Lawrence Journal-World, the locally owned

newspaper in Lawrence, Kansas where Django was developed At Journal-World Jacob was the

lead developer of Ellington, a commercial Web-publishing platform for media companies

About the Technical Reviewer

■SEAn LEGASSiCK has been creating software for over 15 years His work

designing the architecture of South African open source framework Chisimba has contributed significantly to software-engineering capac-ity-building in Africa and other areas of the developing world He is a cofounder of MobGeo, a start-up developing innovative location-aware mobile marketing solutions Away from the world of software, he writes

on politics and culture

Acknowledgments

Thanks to the many people who contributed to our online first drafts, and thanks to the folks

at Apress for their great editing

Preface

Welcome to the second edition of The Definitive Guide to Django, informally known as The

Django Book! This book aims to teach you how to use the Django Web framework to develop

Web sites efficiently

When Jacob Kaplan-Moss and I wrote the first edition of this book, Django was still in a

pre-1.0 stage Once Django version 1.0 was released, with its several backward-incompatible

changes, the first edition inevitably became outdated and people began demanding an update

I’m happy to report this edition covers Django 1.1 and should serve you well for some time

My thanks go to the many contributors who posted comments, corrections, and rants to

http://djangobook.com/, the accompanying Web site for this book, where I posted chapter

drafts as I wrote them You guys are great

Adrian Holovaty

Cocreator and co–Benevolent Dictator for Life, Django

Introduction

in the early days, Web developers wrote every page by hand Updating a Web site meant

edit-ing HTML; a “redesign” involved redoedit-ing every sedit-ingle page, one at a time

As Web sites grew and became more ambitious, it quickly became obvious that that

situation was tedious, time-consuming, and ultimately untenable A group of enterprising

hackers at NCSA (the National Center for Supercomputing Applications, where Mosaic, the

first graphical Web browser, was developed) solved this problem by letting the Web server

spawn external programs that could generate HTML dynamically They called this protocol

the Common Gateway Interface, or CGI, and it changed the Web forever

It’s hard now to imagine what a revelation CGI must have been: instead of treating HTML

pages as simple files on disk, CGI allows you to think of your pages as resources generated

dynamically on demand The development of CGI ushered in the first generation of dynamic

Web sites

However, CGI has its problems: CGI scripts need to contain a lot of repetitive “boilerplate”

code, they make code reuse difficult, and they can be difficult for first-time developers to write

and understand

PHP fixed many of these problems, and it took the world by storm—it’s now by far the

most popular tool used to create dynamic Web sites, and dozens of similar languages and

environments (ASP, JSP, etc.) have followed PHP’s design closely PHP’s major innovation is its

ease of use: PHP code is simply embedded into plain HTML The learning curve for someone

who already knows HTML is extremely shallow

But PHP has its own problems; its very ease of use encourages sloppy, repetitive, ill-

conceived code Worse, PHP does little to protect programmers from security vulnerabilities,

and thus many PHP developers found themselves learning about security only once it was

too late

These and similar frustrations led directly to the development of the current crop of

“third- generation” Web-development frameworks These frameworks—Django and Ruby

on Rails appear to be the most popular these days—recognize that the Web’s importance has

escalated of late

With this new explosion of Web development comes yet another increase in ambition;

Web developers are expected to do more and more every day

Django was invented to meet these new ambitions Django lets you build deep, dynamic,

interesting sites in an extremely short time Django is designed to let you focus on the fun,

interesting parts of your job while easing the pain of the repetitive bits In doing so, it provides

high-level abstractions of common Web-development patterns, shortcuts for frequent

pro-gramming tasks, and clear conventions on how to solve problems At the same time, Django

tries to stay out of your way, letting you work outside the scope of the framework as needed

We wrote this book because we firmly believe that Django makes Web development

bet-ter It’s designed to quickly get you moving on your own Django projects, and then ultimately

teach you everything you need to know to successfully design, develop, and deploy a site that

you’ll be proud of

We’re extremely interested in your feedback The online version of this book—available

at http://djangobook.com/—will let you comment on any part of the book and discuss it with

other readers We’ll do our best to read all the comments posted there, and to respond to as

many as possible If you prefer e-mail, please drop us a line at feedback@djangobook.com Either

way, we’d love to hear from you!

We’re glad you’re here, and we hope you find Django as exciting, fun, and useful as we do

Getting Started