THE EXPERT’S VOICE® IN WEB DEVELOPMENT Updated for Django 1.1 The Definitive Guide to Web Development Done Right Django is a framework that saves you time and makes Web development a joy SECOND EDITION Adrian Holovaty and Jacob Kaplan-Moss Benevolent Dictators for Life, Django The Definitive Guide to Django Web Development Done Right, Second Edition Adrian Holovaty and Jacob Kaplan-Moss The Definitive Guide to Django: Web Development Done Right, Second Edition Copyright © 2009 by Adrian Holovaty and Jacob Kaplan-Moss 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 [email protected], 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 [email protected], 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 preparation 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. This book is dedicated to the Django community. 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 iv ■ ■ ■ PART 3 Other Django Features 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 v 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 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