Two Scoops of Django Best Practices For Django 1.5 Daniel Greenfeld Audrey Roy Two Scoops of Django: Best Practices for Django 1.5 First Edition, Final Version, 20130411 by Daniel Greenfeld and Audrey Roy Copyright ⃝c 2013 Daniel Greenfeld, Audrey Roy, and Cartwheel Web. All rights reserved. is book may not be reproduced in any form, in whole or in part, without written permission from the authors, except in the case of brief quotations embodied in articles or reviews. Limit of Liability and Disclaimer of Warranty: e authors have used their best efforts in preparing this book, and the information provided herein “as is.” e information provided is sold without warranty, either express or implied. Neither the authors nor Cartwheel Web will be held liable for any damages to be caused either directly or indirectly by the contents of this book. Trademarks: Rather than indicating every occurence of a trademarked name as such, this book uses the names only in an editorial fashion and to the benet of the trademark owner with no intention of infringement of the trademark. First printing, January 2013 For more information, visit https://django.2scoops.org. For Malcolm Tredinnick 1971-2013 We miss you. iii Contents List of Figures xv List of Tables xvii Authors’ Notes xix A Few Words From Daniel Greenfeld . xix A Few Words From Audrey Roy . xx Introduction xxi A Word About Our Recommendations . xxi Why Two Scoops of Django? . xxii Before You Begin . xxiii is book is intended for Django 1.5 and Python 2.7.x . xxiii Each Chapter Stands On Its Own . xxiii Conventions Used in is Book . xxiv Core Concepts . xxv Keep It Simple, Stupid . xxv Fat Models, Helper Modules, in Views, Stupid Templates . xxvi Start With Django By Default . xxvi Stand on the Shoulders of Giants . xxvi 1 Coding Style 1 1.1 e Importance of Making Your Code Readable . 1 1.2 PEP8......................................... 2 1.3 e Word on Imports . 2 1.4 Use Explicit Relative Imports . 3 1.5 Avoid Using Import * . 6 1.6 Django Coding Style Guidelines . 7 iv Contents 1.7 Never Code to the IDE (or Text Editor) . 8 1.8 Summary . 8 2 e Optimal Django Environment Setup 9 2.1 Use the Same Database Engine Everywhere . 9 2.1.1 Fixtures Are Not a Magic Solution . 9 2.1.2 You Can’t Examine an Exact Copy of Production Data Locally . 10 2.1.3 Different Databases Have Different Field Types/Constraints . 10 2.2 Use Pip and Virtualenv . 11 2.3 Install Django and Other Dependencies via Pip . 13 2.4 Use a Version Control System . 14 2.5 Summary . 14 3 How to Lay Out Django Projects 15 3.1 Django 1.5’s Default Project Layout . 15 3.2 Our Preferred Project Layout . 16 3.2.1 Top Level: Repository Root . 16 3.2.2 Second Level: Django Project Root . 16 3.2.3 ird Level: Conguration Root . 17 3.3 Sample Project Layout . 17 3.4 What About the Virtualenv? . 20 3.5 Using a Startproject Template to Generate Our Layout . 21 3.6 Other Alternatives . 22 3.7 Summary . 22 4 Fundamentals of Django App Design 23 4.1 e Golden Rule of Django App Design . 23 4.1.1 A Practical Example of Apps in a Project . 24 4.2 What to Name Your Django Apps . 25 4.3 When in Doubt, Keep Apps Small . 26 4.4 Summary . 26 5 Settings and Requirements Files 27 5.1 Avoid Non-Versioned Local Settings . 28 5.2 Using Multiple Settings Files . 29 5.2.1 A Development Settings Example . 32 5.2.2 Multiple Development Settings . 33 v Contents 5.3 Keep Secret Keys Out With Environment Variables . 34 5.3.1 A Caution Before Using Environment Variables for Secrets . 35 5.3.2 How to Set Environment Variables Locally . 35 5.4 How to Set Environment Variables in Production . 37 5.4.1 Handling Missing Secret Key Exceptions . 38 5.5 Using Multiple Requirements Files . 40 5.5.1 Installing From Multiple Requirements Files . 41 5.5.2 Using Multiple Requirements Files With Platforms as a Service (PaaS) . 42 5.6 Handling File Paths in Settings . 42 5.7 Summary . 45 6 Database/Model Best Practices 47 6.1 Basics . 48 6.1.1 Break Up Apps With Too Many Models . 48 6.1.2 Don’t Drop Down to Raw SQL Until It’s Necessary . 48 6.1.3 Add Indexes as Needed . 49 6.1.4 Be Careful With Model Inheritance . 49 6.1.5 Model Inheritance in Practice: e TimeStampedModel . 51 6.1.6 Use South for Migrations . 53 6.2 Django Model Design . 53 6.2.1 Start Normalized . 54 6.2.2 Cache Before Denormalizing . 54 6.2.3 Denormalize Only if Absolutely Needed . 54 6.2.4 When to Use Null and Blank . 55 6.3 Model Managers . 56 6.4 Summary . 58 7 Function- and Class-Based Views 61 7.1 When to Use FBVs or CBVs . 61 7.2 Keep View Logic Out of URLConfs . 63 7.3 Stick to Loose Coupling in URLConfs . 64 7.3.1 What if we aren’t using CBVs? . 66 7.4 Try to Keep Business Logic Out of Views . 66 7.5 Summary . 66 8 Best Practices for Class-Based Views 69 vi Contents 8.1 Using Mixins With CBVs . 70 8.2 Which Django CBV Should Be Used for What Task? . 72 8.3 General Tips for Django CBVs . 73 8.3.1 Constraining Django CBV Access to Authenticated Users . 73 8.3.2 Performing Custom Actions on Views With Valid Forms . 74 8.3.3 Performing Custom Actions on Views With Invalid Forms . 75 8.4 How CBVs and Forms Fit Together . 76 8.4.1 Views + ModelForm Example . 77 8.4.2 Views + Form Example . 81 8.5 Summary . 83 9 Common Patterns for Forms 85 9.1 e Power of Django Forms . 85 9.2 Pattern 1: Simple ModelForm With Default Validators . 86 9.3 Pattern 2: Custom Form Field Validators in ModelForms . 87 9.4 Pattern 3: Overriding the Clean Stage of Validation . 91 9.5 Pattern 4: Hacking Form Fields (2 CBVs, 2 Forms, 1 Model) . 94 9.6 Pattern 5: Reusable Search Mixin View . 98 9.7 Summary . 100 10 More ings to Know About Forms 101 10.1 Use the POST Method in HTML Forms . 101 10.1.1 Don’t Disable Django’s CSRF Protection . 102 10.2 Know How Form Validation Works . 102 10.2.1 Form Data Is Saved to the Form, en the Model Instance . 103 10.3 Summary . 104 11 Building REST APIs in Django 105 11.1 Fundamentals of Basic REST API Design . 105 11.2 Implementing a Simple JSON API . 107 11.3 REST API Architecture . 109 11.3.1 Code for an App Should Remain in the App . 110 11.3.2 Try to Keep Business Logic Out of API Views . 110 11.3.3 Grouping API URLs . 110 11.3.4 Test Your API . ..