Two Scoops of Django: Best Practices for Django 1.8

Dedication......Page 7
 About the Dedication......Page 8
 A Few Words From Audrey Roy Greenfeld......Page 29
 Why Two Scoops of Django?......Page 31
 Before You Begin......Page 32
 Conventions Used in This Book......Page 33
 Our Writing Concepts......Page 35
  Publish Errata......Page 37
 1.1 The Importance of Making Your Code Readable......Page 39
 1.2 PEP 8......Page 40
 1.3 The Word on Imports......Page 41
 1.4 Use Explicit Relative Imports......Page 42
 1.5 Avoid Using Import *......Page 45
  1.6.2 Use Underscores in URL Pattern Names Rather Than Dashes......Page 47
  1.7.1 JavaScript Style Guides......Page 48
 1.8 Never Code to the IDE (Or Text Editor)......Page 49
 1.9 Summary......Page 50
  2.1.1 You Can\'t Examine an Exact Copy of Production Data Locally......Page 51
  2.1.2 Different Databases Have Different Field Types/Constraints......Page 52
 2.2 Use Pip and Virtualenv......Page 53
 2.3 Install Django and Other Dependencies via Pip......Page 55
 2.4 Use a Version Control System......Page 56
  2.5.1 Vagrant and VirtualBox......Page 57
 2.6 Summary......Page 58
 3.1 Django 1.8\'s Default Project Layout......Page 59
 3.2 Our Preferred Project Layout......Page 60
  3.2.3 Third Level: Configuration Root......Page 61
 3.3 Sample Project Layout......Page 62
 3.4 What About the Virtualenv?......Page 65
 3.5 Going Beyond startproject......Page 66
  3.5.1 Generating Project Boilerplate With Cookiecutter......Page 67
  3.5.2 Our Favorite Project Template......Page 68
  3.5.4 Other Alternatives......Page 69
 3.6 Summary......Page 70
4 Fundamentals of Django App Design......Page 71
 4.1 The Golden Rule of Django App Design......Page 72
  4.1.1 A Practical Example of Apps in a Project......Page 73
 4.2 What to Name Your Django Apps......Page 74
  4.4.1 Common App Modules......Page 75
  4.4.2 Uncommon App Modules......Page 76
 4.5 Summary......Page 78
5 Settings and Requirements Files......Page 79
 5.1 Avoid Non-Versioned Local Settings......Page 80
 5.2 Using Multiple Settings Files......Page 81
  5.2.1 A Development Settings Example......Page 84
  5.2.2 Multiple Development Settings......Page 85
 5.3 Separate Configuration From Code......Page 86
  5.3.2 How to Set Environment Variables Locally......Page 87
  5.3.3 How to Set Environment Variables in Production......Page 89
  5.3.4 Handling Missing Secret Key Exceptions......Page 90
  5.4.1 Using JSON Files......Page 92
 5.5 Using Multiple Requirements Files......Page 93
  5.5.2 Using Multiple Requirements Files With Platforms as a  Service (PaaS)......Page 95
 5.6 Handling File Paths in Settings......Page 96
 5.7 Summary......Page 98
6 Model Best Practices......Page 101
  6.1.2 Be Careful With Model Inheritance......Page 102
  6.1.3 Model Inheritance in Practice: The TimeStampedModel......Page 104
  6.1.4 Database Migrations......Page 105
  6.2.3 Denormalize Only if Absolutely Needed......Page 107
  6.2.4 When to Use Null and Blank......Page 108
  6.2.5 When to Use BinaryField......Page 110
  6.2.6 Try to Avoid Using Generic Relations......Page 111
  6.2.7 PostgreSQL-Specific Fields: When to Use Null and Blank......Page 112
 6.4 Model Managers......Page 113
 6.5 Understanding Fat Models......Page 115
  6.5.1 Model Behaviors a.k.a Mixins......Page 116
 6.6 Summary......Page 117
 7.1 Use get_object_or_404() for Single Objects......Page 119
  7.2.1 ObjectDoesNotExist vs. DoesNotExist......Page 120
 7.3 Use Lazy Evaluation to Make Queries Legible......Page 121
 7.4 Lean on Advanced Query Tools......Page 122
  7.4.1 Query Expressions......Page 123
  7.4.2 Database Functions......Page 124
 7.5 Don\'t Drop Down to Raw SQL Until It\'s Necessary......Page 125
 7.6 Add Indexes as Needed......Page 126
  7.7.1 Wrapping Each HTTP Request in a Transaction......Page 127
  7.7.2 Explicit Transaction Declaration......Page 130
  7.7.3 django.http.StreamingHttpResponse and Transactions......Page 131
 7.8 Summary......Page 132
 8.1 When to Use FBVs or CBVs......Page 133
 8.2 Keep View Logic Out of URLConfs......Page 135
 8.3 Stick to Loose Coupling in URLConfs......Page 136
 8.4 Use URL Namespaces......Page 139
  8.4.1 Makes for Shorter, More Obvious and Don\'t Repeat Yourself URL Names......Page 140
  8.4.2 Increases Interoperability With Third-Party Libraries......Page 141
 8.5 Don\'t Reference Views as Strings in URLConfs......Page 142
 8.6 Try to Keep Business Logic Out of Views......Page 143
  8.7.1 The Simplest Views......Page 144
 8.8 Don\'t Use locals() as Views Context......Page 145
 8.9 Summary......Page 146
 9.1 Advantages of FBVs......Page 147
 9.2 Passing the HttpRequest Object......Page 148
 9.3 Decorators Are Sweet......Page 151
  9.3.1 Be Conservative With Decorators......Page 153
 9.5 Summary......Page 154
10 Best Practices for Class-Based Views......Page 155
 10.2 Using Mixins With CBVs......Page 156
 10.3 Which Django GCBV Should Be Used for What Task?......Page 158
 10.4 General Tips for Django CBVs......Page 159
  10.4.2 Performing Custom Actions on Views With Valid Forms......Page 160
  10.4.3 Performing Custom Actions on Views With Invalid Forms......Page 161
  10.4.4 Using the View Object......Page 162
 10.5 How GCBVs and Forms Fit Together......Page 164
  10.5.1 Views + ModelForm Example......Page 165
  10.5.2 Views + Form Example......Page 169
 10.6 Using Just django.views.generic.View......Page 171
 10.7 Additional Resources......Page 173
 10.8 Summary......Page 174
 11.1 Validate All Incoming Data With Django Forms......Page 175
 11.2 Use the POST Method in HTML Forms......Page 178
  11.3.1 Posting Data via AJAX......Page 179
 11.4 Understand How to Add Django Form Instance Attributes......Page 180
 11.5 Know How Form Validation Works......Page 181
  11.5.1 ModelForm Data Is Saved to the Form, Then the Model Instance......Page 183
 11.6 Add Errors to Forms with Form.add_error()......Page 184
 11.7 Fields Without Pre-Made Widgets......Page 185
 11.9 Summary......Page 186
12 Common Patterns for Forms......Page 187
 12.1 Pattern 1: Simple ModelForm With Default Validators......Page 188
 12.2 Pattern 2: Custom Form Field Validators in ModelForms......Page 189
 12.3 Pattern 3: Overriding the Clean Stage of Validation......Page 194
 12.4 Pattern 4: Hacking Form Fields (2 CBVs, 2 Forms, 1 Model)......Page 197
 12.5 Pattern 5: Reusable Search Mixin View......Page 201
 12.6 Summary......Page 203
 13.1 Keep Templates Mostly in templates/......Page 205
  13.2.1 2-Tier Template Architecture Example......Page 206
  13.2.2 3-Tier Template Architecture Example......Page 207
  13.2.3 Flat Is Better Than Nested......Page 208
 13.3 Limit Processing in Templates......Page 209
  13.3.1 Gotcha 1: Aggregation in Templates......Page 211
  13.3.2 Gotcha 2: Filtering With Conditionals in Templates......Page 213
  13.3.3 Gotcha 3: Complex Implied Queries in Templates......Page 215
  13.3.4 Gotcha 4: Hidden CPU Load in Templates......Page 216
 13.4 Don\'t Bother Making Your Generated HTML Pretty......Page 217
 13.5 Exploring Template Inheritance......Page 219
 13.6 block.super Gives the Power of Control......Page 222
 13.7 Useful Things to Consider......Page 223
  13.7.3 Location, Location, Location!......Page 224
  13.7.5 Use URL Names Instead of Hardcoded Paths......Page 225
 13.8 Error Page Templates......Page 226
 13.9 Follow a Minimalist Approach......Page 227
 13.10 Summary......Page 228
 14.1 Filters Are Functions......Page 229
  14.1.2 Filters and Code Reuse......Page 230
  14.2.3 The Performance Cost of Template Tags......Page 231
 14.3 Naming Your Template Tag Libraries......Page 232
  14.4.1 Watch Out for This Crazy Anti-Pattern......Page 233
 14.5 Summary......Page 234
 15.1 What\'s the Syntactical Difference?......Page 235
  15.2.1 Advantages of DTL......Page 236
 15.3 Considerations When Using Jinja2 With Django......Page 237
  15.3.3 Using Django-Style Template Filters in Jinja2 Templates......Page 238
  15.3.4 Context Processors Aren\'t Called by Jinja2 Templates......Page 240
  15.3.5 The Jinja2 Environment Object Should Be Considered Static......Page 242
 15.5 Summary......Page 243
16 Building REST APIs......Page 245
 16.1 Fundamentals of Basic REST API Design......Page 246
 16.2 Implementing a Simple JSON API......Page 248
  16.3.1 Code for a Project Should Be Neatly Organized......Page 251
  16.3.3 Try to Keep Business Logic Out of API Views......Page 252
  16.3.4 Grouping API URLs......Page 253
 16.4 Service-Oriented Architecture......Page 255
  16.5.1 Step #1: Notify Users of Pending Shut Down......Page 256
 16.6 Evaluating REST Frameworks......Page 257
  16.6.3 Are Remote Procedure Calls Easy to Implement?......Page 258
  16.7.1 Unfettered API Access is Dangerous......Page 259
 16.8 Advertising Your REST API......Page 260
 16.10 Summary......Page 261
17 Consuming REST APIs......Page 263
 17.1 Learn How to Debug the Client......Page 264
  17.3.1 Read the Search Engine Documentation......Page 265
  17.3.2 Hand-Craft the sitemap.xml......Page 266
  17.4.1 Solution: Mask the Latency With Animations......Page 267
 17.5 Avoid the Anti-Patterns......Page 268
  17.5.4 Storing Data in the DOM When It\'s Not jQuery......Page 269
  17.6.1 JQuery and the CSRF Token......Page 270
  17.6.3 AngularJS and the CSRF Token......Page 272
 17.8 Follow JavaScript Coding Standards......Page 273
 17.10 Summary......Page 274
18 Tradeoffs of Replacing Core Components......Page 275
 18.1 The Temptation to Build FrankenDjango......Page 276
  18.2.1 Not All Non-Relational Databases Are ACID Compliant......Page 277
  18.2.3 Ignore the Hype and Do Your Own Research......Page 278
 18.4 Summary......Page 279
19 Working With the Django Admin......Page 281
 19.3 Viewing String Representations of Objects......Page 282
 19.4 Adding Callables to ModelAdmin Classes......Page 286
 19.5 Don\'t Use list_editable in Multiuser Environments......Page 287
 19.6 Django\'s Admin Documentation Generator......Page 288
 19.8 Using Custom Skins With the Django Admin......Page 289
  19.8.2 Write Tests for Any Admin Extensions You Create......Page 290
 19.9 Summary......Page 291
 20.1 Use Django\'s Tools for Finding the User Model......Page 293
  20.1.2 Don\'t Use get_user_model() for Foreign Keys to User......Page 294
 20.3 Custom User Fields for Django 1.8 Projects......Page 295
  20.3.1 Option 1: Subclass AbstractUser......Page 296
  20.3.3 Option 3: Linking Back From a Related Model......Page 297
 20.4 Summary......Page 299
21 Django\'s Secret Sauce: Third-Party Packages......Page 301
 21.2 Know About the Python Package Index......Page 302
 21.5 Tools for Installing and Managing Packages......Page 303
  21.7.2 Step 2: Add Package and Version Number to Your Requirements......Page 304
  21.7.3 Step 3: Install the Requirements Into Your Virtualenv......Page 305
 21.9 Releasing Your Own Django Packages......Page 306
  21.10.1 Purpose......Page 307
  21.10.5 Templates......Page 308
  21.10.9 Availability on PyPI......Page 309
  21.10.10 Uses the Broadest Requirements Specifiers Possible......Page 310
  21.10.11 Proper Version Numbers......Page 311
  21.10.12 Name......Page 312
  21.10.15 Use URL Namespaces......Page 313
 21.11 Creating Your Own Packages the Easy Way......Page 314
  21.12.2 Handling Bad Pull Requests......Page 315
  21.12.3 Do Formal PyPI Releases......Page 316
  21.12.4 Create and Deploy Wheels to PyPI......Page 317
  21.12.7 Provide Sample Base Templates......Page 318
 21.13 Additional Reading......Page 319
 21.14 Summary......Page 320
 22.1 Testing Saves Money, Jobs, and Lives......Page 321
 22.2 How to Structure Tests......Page 322
  22.3.1 Each Test Method Tests One Thing......Page 323
  22.3.2 For Views, When Possible Use the Request Factory......Page 326
  22.3.4 Don\'t Repeat Yourself Doesn\'t Apply to Writing Tests......Page 327
  22.3.6 Things That Should Be Tested......Page 328
  22.3.7 Test for Failure......Page 329
  22.3.8 Use Mock to Keep Unit Tests From Touching the World......Page 330
  22.3.9 Use Fancier Assertion Methods......Page 332
 22.4 What About Integration Tests?......Page 333
 22.6 Who Cares? We Don\'t Have Time for Tests!......Page 334
  22.8.1 Step 1: Start Writing Tests......Page 335
  22.8.3 Step 3: Generate the Report!......Page 336
 22.10 Alternatives to unittest......Page 337
 22.11 Summary......Page 338
 23.1 Use reStructuredText for Python Docs......Page 339
 23.3 What Docs Should Django Projects Contain?......Page 341
 23.5 The Markdown Alternative......Page 343
  23.5.2 Markdown Resources......Page 344
 23.7 Summary......Page 345
  24.2.1 Find Excessive Queries With Django Debug Toolbar......Page 347
  24.2.2 Reduce the Number of Queries......Page 348
  24.2.3 Speed Up Common Queries......Page 349
  24.3.1 Know What Doesn\'t Belong in the Database......Page 350
  24.3.3 Getting the Most Out of MySQL......Page 351
 24.6 Consider Third-Party Caching Packages......Page 352
 24.7 Compression and Minification of HTML, CSS, and JavaScript......Page 353
 24.9 Other Resources......Page 354
 24.10 Summary......Page 356
25 Asynchronous Task Queues......Page 357
 25.1 Do We Need a Task Queue?......Page 358
 25.2 Choosing Task Queue Software......Page 359
  25.3.2 Tasks Aren\'t Free......Page 360
  25.3.5 Logging!......Page 361
  25.3.9 Use the Queue\'s Error Handling......Page 362
 25.4 Resources for Task Queues......Page 363
 25.5 Summary......Page 364
 26.2 Know Django\'s Security Features......Page 365
 26.5 HTTPS Everywhere......Page 366
  26.5.2 Use HTTP Strict Transport Security (HSTS)......Page 368
 26.6 Use Allowed Hosts Validation......Page 370
  26.8.3 Use JSON Encoding for Data Consumed by JavaScript......Page 371
  26.9.2 Python Standard Library Modules That Can Execute Code......Page 372
  26.9.4 Be Careful With Cookie-Based Sessions......Page 373
 26.10 Validate All Incoming Data With Django Forms......Page 374
 26.12 Handle User-Uploaded Files Carefully......Page 375
  26.12.2 Django and User-Uploaded Files......Page 376
 26.13 Don\'t Use ModelForms.Meta.exclude......Page 377
  26.13.1 Mass Assignment Vulnerabilities......Page 379
 26.16 Never Store Credit Card Data......Page 380
  26.17.1 Change the Default Admin URL......Page 381
  26.17.4 Limit Admin Access Based on IP......Page 382
 26.20 Keep Your Dependencies Up-to-Date......Page 383
 26.23 Explore Two-Factor Authentication......Page 384
 26.25 Force the Use of Strong Passwords......Page 385
 26.27 Put Up a Vulnerability Reporting Page......Page 386
  26.29.1 Shut Everything Down or Put It in Read-Only Mode......Page 387
  26.29.4 Email security@djangoproject.com, Even if It\'s Your Fault......Page 388
  26.29.5 Start Looking Into the Problem......Page 389
 26.30 Obfuscate Primary Keys with UUIDs......Page 390
 26.32 Keep Up-to-Date on General Security Practices......Page 391
 26.33 Summary......Page 392
 27.1 Application Logs vs. Other Logs......Page 393
 27.3 When to Use Each Log Level......Page 394
  27.3.2 Log Production Errors With ERROR......Page 395
  27.3.3 Log Lower-Priority Problems With WARNING......Page 396
  27.3.5 Log Debug-Related Messages to DEBUG......Page 397
 27.4 Log Tracebacks When Catching Exceptions......Page 399
 27.6 Log Locally to Rotating Files......Page 400
 27.8 Necessary Reading Material......Page 401
 27.10 Summary......Page 402
 28.1 When to Use and Avoid Signals......Page 403
  28.2.1 Using Custom Model Manager Methods Instead of Signals......Page 404
  28.2.3 Override Your Model\'s Save or Delete Method Instead......Page 407
 28.3 Summary......Page 408
 29.1 Create a Core App for Your Utilities......Page 409
  29.2.2 Trimming Models......Page 410
 29.3 Django\'s Own Swiss Army Knife......Page 411
  29.3.2 django.utils.decorators.method_decorator(decorator)......Page 412
  29.3.5 django.utils.functional.cached_property......Page 413
  29.3.8 django.utils.html.strip_tags(value)......Page 414
  29.3.10 django.utils.text.slugify(value)......Page 415
  29.4.2 django.core.exceptions.ObjectDoesNotExist......Page 417
  29.4.3 django.core.exceptions.PermissionDenied......Page 419
 29.5 Serializers and Deserializers......Page 420
  29.5.1 django.core.serializers.json.DjangoJSONEncoder......Page 422
 29.6 Summary......Page 423
30 Deployment: Platforms as a Service......Page 425
  30.1.1 Compliance......Page 426
  30.1.3 Uptime......Page 427
  30.1.5 Scaling......Page 428
  30.1.7 Performance Degradation......Page 429
  30.2.1 Aim for Identical Environments......Page 430
  30.2.4 Prepare for Disaster With Backups and Rollbacks......Page 431
 30.3 Summary......Page 432
  31.1.1 Should You Bother?......Page 433
  31.1.2 Example: Quick Ubuntu + Gunicorn Setup......Page 434
 31.2 Multi-Server for Medium to Large Projects......Page 435
  31.2.1 Advanced Multi-Server Setup......Page 438
 31.3 WSGI Application Servers......Page 439
 31.4 Performance and Tuning: uWSGI and Gunicorn......Page 440
  31.6.1 Apache and Environment Variables......Page 441
 31.7 Automated, Repeatable Deployments......Page 442
  31.7.1 A Rapidly Changing World......Page 444
 31.9 Current Infrastructure Automation Tools......Page 445
 31.11 Summary......Page 448
32 Continuous Integration......Page 449
  32.1.2 Keeping the Build Fast......Page 450
  32.2.1 Tox......Page 451
 32.3 Continuous Integration as a Service......Page 452
 32.5 Summary......Page 453
  33.1.2 That Annoying CBV Error......Page 455
  33.1.4 Remember the Essentials for Form File Uploads......Page 457
 33.2 Debugging Production Systems......Page 460
  33.2.3 UserBasedExceptionMiddleware......Page 461
  33.2.4 That Troublesome settings.ALLOWED_HOSTS Error......Page 462
 33.3 Feature Flags......Page 463
 33.4 Summary......Page 464
 34.2 How to Ask Great Django Questions in IRC......Page 465
 34.3 Feed Your Brain......Page 466
  34.4.1 9 Easy Ways to Participate......Page 467
 34.5 Summary......Page 468
35 Closing Thoughts......Page 469
Appendix A: Packages Mentioned In This Book......Page 471
 Our Recommended Solutions......Page 479
  Check Your Virtualenv Installation......Page 480
  Check For Other Problems......Page 481
 JavaScript Resources......Page 483
 Start Early......Page 489
 Wrap Content Strings with Translation Functions......Page 490
 Don\'t Interpolate Words in Sentences......Page 491
 Browser Page Layout......Page 493
 Twelve Factor-Style Settings......Page 497
 Working With Python 2 and 3......Page 499
 Resources......Page 502
 SESSION_SERIALIZER......Page 503
Acknowledgments......Page 505
List of Figures......Page 510
List of Tables......Page 513
Index......Page 515