Covers Django 2 & 3

Mastering
Django LE
P
M

MDj
A
S

The original, best-selling programmer’s

reference, now completely rewritten
for Django 2 and 3
Mastering Django - SAMPLE
Nigel George
 LE
P
M
A
S

Mastering Django - SAMPLE

 Mastering Django

LE
The original, best-selling programmer’s reference completely
P
rewritten for Django 2 and 3.
M
A
S

Nigel George

Mastering Django - SAMPLE

Mastering Django
Copyright©2020 by Nigel George

All rights reserved. No part of this publication may be reproduced, distributed, or

transmitted in any form or by any means, including photocopying, recording, or other
electronic or mechanical methods, without the prior written permission of the
publisher, except in the case of brief quotations embodied in critical reviews and

LE
certain other noncommercial uses permitted by copyright law.

Published by GNW Independent Publishing, Hamilton NSW, Australia

P
M
A
S

ISBN: 978-0-6488844-1-5 (PRINT)

22 21 20 123456789

Mastering Django - SAMPLE

 Acknowledgments

As always, my thanks go out to my family for putting up with the months of absences
and insanity that comes with completing a project like this around working for a

LE
living.

To the Django community, without your input and enthusiasm, I would never find the
motivation to even complete a web tutorial, let alone a 600-odd page textbook.

In particular, I would like to make special mention of my beta testers, who were (in no
particular order): P
Didier Clapasson, Dominic Bühler, Maria Hynes, James Bellis, Rick Colgan,
Simon Schliesky, Lourens Grové, Derrick Kearney, Adrian German, Raphael
M
Thanhoffer, Jan Gondol, David Price, Jaap Onderwaater, Georges Samaha,
Bogdan Górski, Hans Hendrick, Martijn Dekker, Alberto Nordmann G.,
Peter Boers, Robert Helewka, Phil Moose, Jean-Patrick Simard, Gerald
Brown, Daniel Coughlin and Hermann Kass.
A

Thank you all—your feedback and suggestions have helped me make this a far better
book than it would have been otherwise.
S

Mastering Django - SAMPLE

 LE
P
M
A
S

Mastering Django - SAMPLE

 Table of Contents

Chapter 1 — Introducing Mastering Django 1

LE
Who This Book is For 2
Structure of the Book 3
Required Programming Knowledge 4
Software Versions 4
Source Code 6
Found a Bug or Typo? 7
Errata and Django 3 Updates
Getting Help
P
Chapter 2 — Installing Python and Django
7
7
11
M
Installing Python 12
Installing Python on macOS 14
Creating a Python Virtual Environment 16
A

Create a Project Folder 17

Create a Python Virtual Environment 18
Installing Django 21
S

Starting a Project 23
Creating a Database 24
The Development Server 24
Chapter 3 — The Big Picture 27
Django’s Structure—A Heretic’s Eye View 27

Mastering Django - SAMPLE

Table of Contents

Django is a Loosely Coupled Framework 28

A Django View is Not a Controller 29
Django Project Structure 34
Creating Your Own Django Apps 39
URLconfs—Django’s Navigator 42
A Final Note on Writing Django Apps 45
Chapter 4 — Django’s Models 47

LE
Supported Databases 50
Defining Models in Python 51
Your First Model 52
Basic Data Access 58
Creating Database Records 59
Retrieving Records
Retrieve All Records
Retrieve a Single Record
P 62
62
63
M
Retrieve Multiple Records 64
Ordering Data 65
Slicing Data 66
Updating Records 68
A

Deleting Records 70
Creating Relationships 71
Working With Related Objects 78
S

Accessing Foreign Key Values 80

Accessing Many-to-Many Values 80
Chapter 5 — Django’s Views 83
Your First View 84
Configuring the URLs 85

— vi —
Mastering Django - SAMPLE
 Table of Contents

So What Just Happened? 88

Your Second View: Dynamic Content 89
Your Third View: Dynamic URLs 93
A Note About the Site Root 100
Chapter 6 — Django’s Templates 103
Template Design Philosophy 103

LE
1. Separate logic from presentation 104
2. Discourage redundancy 104
3. Be decoupled from HTML 105
4. XML should not be used for template languages 105
5. Assume designer competence 105
6. Treat whitespace obviously 105

8. Safety and security

9. Extensibility
P
7. Don’t invent a programming language 105
106
106
M
DTL Philosophy—Concluding Thoughts 106
Django Template System Basics 107
How Django Finds Templates 109
Creating a Site Template 111
A

Displaying a Template 113

Template Inheritance 117
Displaying Database Data 121
S

Loading Static Files 123

Listing 1: base.html 125
Listing 2: main.css 127
logo.png and top_banner.jpg 129
Template Includes 130

— vii —
Mastering Django - SAMPLE
Table of Contents

Chapter 7 — The Django Admin 135

Accessing the Django Admin Site 135
Registering Models With the Admin 138
Making Fields Optional 140
Customizing the Venue Change List 143
Customizing the Events Change List and Form 146

LE
Update the Event Model 148
Modify the Event Change List and Edit Form 149
Grouping Information with Fieldsets 152
Managing Users in the Admin 154
Changing Passwords 160
Chapter 8 — Django’s Forms 165
Creating a Contact Form
P
Add Contact Form URL to Site App
170
171
M
Add Navigation to Site Template 172
Create the Contact Form Template 173
Create the Contact Form View 174
Add Styles to the Contact Form 177
A

Emailing the Form Data 180

Model Forms 183
Create the Venue Form 183
S

Add the Venue View 184

Create the Venue Form Template 185
Link to the Add Venue Form 187
Overriding Form Methods 189
Chapter 9 — Advanced Models 195
Working With Data 195

— viii —
Mastering Django - SAMPLE
 Table of Contents

Methods That Return QuerySets 195

exclude() 198
annotate() 198
order_by() and reverse() 199
values() and values_list() 200
dates() and datetimes() 201
select_related() and prefetch_related() 201

LE
Methods That Don’t Return QuerySets 202
get_or_create() 204
update_or_create() 205
bulk_create() and bulk_update() 205
count() 207
in_bulk() 208
latest() and earliest()
first() and last()
aggregate() 209
P 208
209
M
exists() 209
Field Lookups 210
Aggregate Functions 212
A

More Complex Queries 213

Query Expressions 213
Q() Objects 216
Model Managers 217
S

Adding Extra Manager Methods 218

Renaming the Default Model Manager 219
Overriding Initial Manager QuerySets 220
Model Methods 222
Custom Model Methods 222

— ix —
Mastering Django - SAMPLE
Table of Contents

Overriding Default Model Methods 224

Model Inheritance 226
Multi-table Inheritance 227
Abstract Base Classes 228
Chapter 10 — Advanced Views 231
Request and Response Objects 231

LE
Request Objects 232
HttpRequest Attributes 232
HttpRequest Methods 239
Response Objects 240
Serving Files with FileResponse Objects 243
QueryDict Objects 244
TemplateResponse Objects
Middleware 251
P
Writing Your Own Middleware
247

253
M
Generating Non-HTML Content 255
Generating Text-based Files 256
Generating PDF Files 258
Pagination 260
A

Page Objects 263

Pagination in Views 264
Splitting Views Into Multiple Files 267
S

Chapter 11 — Advanced Templates 275

Setting Up the Demo Files 275
Django’s Default Template Tags and Filters 279
Template Tags 280
The comment Tag 281

—x—
Mastering Django - SAMPLE
 Table of Contents

The cycle Tag 282

The filter Tag 285
The firstof Tag 285
The for Tag 286
The if Tag 287
The lorem Tag 290
The now Tag 291

LE
The regroup Tag 291
The url Tag 292
The widthratio Tag 292
The with Tag 292
Template Filters 293
The add Filter 295
The addslashes Filter
Sentence Casing Filters
Field Alignment Filters
P 296
296
296
M
The cut Filter 297
The date and time Filters 297
The default and default_if_none Filters 297
A

The dictsort and dictsortreversed Filters 298

The divisibleby Filter 298
The filesizeformat Filter 298
The first and last Filters 299
S

The floatformat Filter 299

The get_digit Filter 299
The join Filter 300
The json_script Filter 300
The length_is Filter 301

— xi —
Mastering Django - SAMPLE
Table of Contents

The make_list Filter 302

The phone2numeric Filter 302
The random Filter 302
The slice Filter 302
The slugify Filter 303
The string_format Filter 303
The striptags Filter 303

LE
The timesince and timeuntil Filters 304
Truncating Strings 305
The unordered_list Filter 306
The urlencode Filter 306
The urlize Filter 306
The wordcount Filter 307
The wordwrap Filter
The yesno Filter
The Humanize Filters
P 307
307
308
M
How Invalid Variables are Handled 309
Custom Tags and Filters 310
Custom Filters 311
A

Custom Tags 313

Simple Tags 313
Inclusion Tags 315
More Advanced Template Tags 316
S

Context, RequestContext and Context Processors 316

The Context Class 316
Setting Default Values 317
Updating the Context 317
Converting the Context to a Single Dictionary 318

— xii —
Mastering Django - SAMPLE
 Table of Contents

Using the Context as a Stack 318

RequestContext and Context Processors 319
Writing Custom Context Processors 324
Template Back Ends and Loaders 326
Template Loaders 327
Code Listings 328
demo_views.py (partial listing) 328

LE
template_demo.html (complete listing) 330
event_custom_tags.py (complete listing) 339
Chapter 12 — Advanced Django Admin 341
Customizing the Admin 341
Changing Admin Site Text 341
Customizing Admin Styles P
Customizing the Default Admin Site
Overriding the Default Admin
343
345
347
M
Creating a Custom Admin Site 349
Customizing Admin Templates 353
How to Override a Template 355
Custom Validation in the Admin 360
A

The ModelAdmin Class 363

ModelAdmin Options 363
The inlines Option 365
S

The list_display_links Option 370

The list_editable Option 371
The save_as option 374
ModelAdmin Methods 375
Admin Actions 379
WYSIWYG Editor in the Admin 385

— xiii —
Mastering Django - SAMPLE
Table of Contents

Chapter 13 — Class Based Views 389

Comprehensive, Not Complex 390
The Basics—View, RedirectView and TemplateView 391
The View Class 392
The RedirectView Class 393
The TemplateView Class 396

LE
From Little Things, Big Things Grow 398
Customizing Generic View Classes and Methods 403
Using Django’s Class-based Generic Views 406
TemplateView 407
RedirectView 410
ListView and DetailView 411
Generic Editing Views
CreateView 418
UpdateView 423
P 417
M
DeleteView 426
FormView 428
Generic Date Views 432
ArchiveIndexView 432
A

The Date Archive Views 436

DateDetailView 439
Chapter 14 — Advanced User Management 441
S

Before We Start—Revert to Default Admin 441

The User Model Class 444
Creating Users 447
Extending the User Model 449
Creating a Custom User Model 456

— xiv —
Mastering Django - SAMPLE
 Table of Contents

Login With an Email Address 461

Custom Authentication 468
Users in the Front End 469
Add the Registration View 469
Create the Templates 471
The Login Template 471
The Register Template 472

LE
The Success Template 473
Modify the Base Template 473
Create URLconfs 474
Testing the Authentication System 475
Restricting Content in the Front End 477
Permission-based Restrictions 482
Chapter 15 — Advanced Forms
Customizing Forms
P 485
485
M
Adding Media to Forms 486
Custom Widgets 490
Rich-text in Forms 494
The Messages Framework 498
A

Django Formsets 504

Handling Multiple Forms 514
Model Form Wizards 520
S

Chapter 16 — Working With Databases 525

Database Management Commands 525
check 526
dbshell 526
dumpdata 526

— xv —
Mastering Django - SAMPLE
Table of Contents

flush 528
inspectdb 528
loaddata 530
makemigrations 530
migrate 531
showmigrations 531
sqlflush 532

LE
sqlmigrate 532
squashmigrations 532
Managing Migrations 534
Connecting to Existing Databases 535
Migrations Out Of Sync 536
Recreating Your Database 536

PostgreSQL 540
P
Connecting to Other Database Engines

Configuring Django for PostgreSQL

538

543
M
MySQL 545
Configuring Django for MySQL 552
MariaDB 554
A

Chapter 17 — Debugging and Testing 559

Using Django’s Error Page 559
Using the Messages Framework 562
S

Unit Testing 565

So Why Create Automated Tests? 566
Unit Testing in Django 567
Running Tests 567
Testing Classes and Methods 571
Testing Views 574

— xvi —
Mastering Django - SAMPLE
 Table of Contents

Chapter 18 — Odds and Ends 579

The Flatpages App 579
Django’s Cache Framework 588
Sessions in Django 589
System Logging 590
Syndication Feed Framework 590

LE
Internationalization and Localization 591
Security in Django 591
Images in Django 592
Signals 593
Search 594
Deploying Django 596
What’s New in Django 3 P 598
M
A
S

— xvii —
Mastering Django - SAMPLE
 LE
P
M
A
S

Mastering Django - SAMPLE

 1
Introducing Mastering Django

LE
When Django 2 was released, a lot changed in the Django world.

Not just because we finally got rid of the complications with having to deal with both
Python 2 and 3, but also because of the many new features, tweaks, updates and
P
optimizations that ensure Django keeps getting better and better. Django 3 continues
the tradition of continual improvement in Django’s codebase.

What many of you may not know, is the original Mastering Django:Core was an
M
update of the original book written by two of the creators of Django—Adrian
Holovaty and Jacob Kaplan-Moss. Given the original book had been around since
Django 1.1, it got dated. There are also a lot of similarities to the Django docs in
several chapters.
A

(Funny aside: I have had a couple of people email me and take me to task for copying
the docs. Lol! Given that the guys who wrote the original book also wrote the original
docs, that will happen folks!)
S

I have decided to start with a clean sheet of paper for Mastering Django. This means
you don’t just get an update; you get a new book, written from scratch to meet the
needs of today’s programmers.

First and foremost, the book remains a plain-English, easy to follow deep-dive into
Django’s commonly used core functionalities. It covers both Django 2 and Django 3.

Mastering Django - SAMPLE

Introduction

Second, the book complements the existing docs; it doesn’t just reproduce them in a
different format. I have removed all the original material from Jacob and Adrian’s
book and all the content from the Django documentation. There are lots of topics not
covered adequately in the docs, which provide ample opportunities for me to create
resources that will make you a better Django programmer. I have done my best to
include them in this book.

Third, the book takes a more practical approach, with less emphasis on theory and

LE
more exploration of working code. It’s impossible to put all Django’s functions into a
single book, but I have done my best to include the functions, classes and tools you
will use regularly. With each major function or class, I expand them into functioning
code examples. Source code is also available for Mastering Django.

And finally, while I will not be releasing the book as open-source, the early chapters
will remain free to access and read on djangobook.com. As with the previous book, all
P
income from sales support the Django Book project, allowing me to keep the core
content ad-free and accessible to all.
M
Exciting times ahead! :)

All the best with your programming journey!

Cheers,
A

Big Nige
S

Who This Book is For

This book is a programmer’s manual targeted at intermediate to advanced

programmers wishing to gain an in-depth understanding of Django.

—2—
Mastering Django - SAMPLE
 Chapter 1

In saying that, it doesn’t mean beginners can’t get value out of the book. Since the
publication of the first edition of the book, roughly half of the readers I have spoken
to identified as being a beginner when they started out with the book.

The way I write—building on simple concepts and explaining every step—is highly
accessible to beginners, so if you are a beginner, you will still learn a great deal about
Django from the book.

LE
Where the book can challenge beginners is all the peripheral stuff—HTML, CSS,
Python and web development in general—that I don’t explain in any detail. The book
is big enough as it is, without me trying to teach you all the stuff you need to know
that isn’t Django-related!

I do, however, give you lots of references so you can easily get more information if you
need it.

Structure of the Book

P
M
I’ve broken the book up into two parts:

f PART 1: Fundamentals—A high-level overview of Django, how it’s structured,

and its core components, so you can grasp how Django brings together each
A

element to create powerful and scalable web applications.

f PART 2: Essentials—This is the meaty part of the book where we take a deep
and detailed dive into the core modules of Django so you can gain a thorough
and practical understanding of all the most commonly used modules in Django.
S

Throughout the book, I will use snippets of code from a fictitious website for a social
or sporting club called MyClub.

It was my original plan for this book to end up with a complete website for MyClub.
However, it was apparent halfway through that a book that teaches you as much as

—3—
Mastering Django - SAMPLE
Introduction

possible about the popular parts of Django has very different goals to a book that
teaches you how to create a complex, professional website.

In the latter case, no more so than the need to write tests. Tests, while necessary for
developing a professional application, distract from learning the core functions of
Django. If I wrote proper tests for all the code in this book, I would double the size of
the codebase and add little to your learning. For these reasons, I have kept the code in
this book to illustrative snippets.

LE
Required Programming Knowledge

The book assumes you have little to no experience with Django.

I expect you to have a basic understanding of web technologies like HTML and CSS,
P
and a basic understanding of how to structure code. You should also be familiar with
your OS’s terminal or shell program. Absolute beginners shouldn’t be too concerned,
as it’s easy to learn the basics, and that’s all you need to get value out of the book.
M
As Django is written in Python, I also assume you have a basic understanding of
Python. Although, since Python is so easy to learn and there are such great resources
available online for Python, I haven’t heard from a learner yet who said not knowing
Python was a barrier. You will learn a lot about Python just by learning Django, and
A

all the extras you need to know are easy to find online.

Software Versions
S

As the book only covers core Django, you don’t require any special functions or
libraries, so the latest versions of Python 3 and Django 2 or 3 are OK. At the time of
writing, this is Python 3.8.3 and Django 2.2.12 (for Django 2) and Django 3.0.6 (for
Django 3).

—4—
Mastering Django - SAMPLE
 Chapter 1

Django 2 or 3??

There is very little difference between Django 2.2 and Django 3.0, which can be
confusing for programmers new to Django. What small differences exist, I have
noted in the book.

Django 2.2 is a Long Term Support version, so is older, more stable and better sup-
ported than Django 3.0. In saying this, the differences between the two versions
are sufficiently small that 99% of the code in this book will work on either version.

LE
Code that only works on Django 3 is clearly marked in the text, so you shouldn’t
have any problems identifying the parts specific to Django 3.

I provide installation instructions for Windows and Mac users. Linux users can refer
to the 90 million Linux installation tutorials online (OK, so that’s maybe an
exaggeration, but there are lots).
P
All the code in this book will run on Windows, macOS or Linux. While the code and
screenshots are all from a Windows machine, the fundamentals remain the same—all
three have a terminal or command window and management commands like
M
runserver work the same on all three platforms.

Coding style is also identical across platforms with one exception—I use Windows-
style backslashes in file paths. This is to assist Windows users to differentiate between
A

Windows’ native use of backslashes and Django’s implementation of forward slashes

in path names. Linux and macOS users, simply need to substitute forward slashes in
these cases.
S

All browser screenshots are taken from the latest version of the Chrome browser. If
you are using FireFox, Safari or some other browser, your screen may look different
than the screenshots.

The images are in full-color in the PDF and eBook versions, but are grayscale in the
printed book (color is way too expensive to print). Paperback users are encouraged to
run the code to see the full-color effect in your browser.

—5—
Mastering Django - SAMPLE
Introduction

Source Code

You can download the source code and resources in this book from https://
djangobook.com/mastering-django-source/.

The included source has been written in Django 3.0. All source code has been tested
and will run unmodified on Django 2.2, except for the MariaDB configuration files as

LE
MariaDB support was not added until Django 3.0.

The source has been tested against the version of SQLite that comes with Django.
While the data structures used in the book are simple and shouldn’t cause problems if
you decide to use another database, there are no guarantees. If you find any database-
related quirks, refer to the database engine documentation.

P
The source is broken up into folders, one for each chapter of the book. Rather than
delete code that changes from chapter to chapter, I have commented out lines of code
in the source so you can see where the code has changed.
M
Code line numbering in the book is provided so you can easily cross-reference my
explanations to individual lines of code in the book. In most cases, line numbering in
the book does not match line numbers in the source files.
A

The source is not designed to be executed as-is. The SQLite database file and
migrations for each chapter have been removed from the source. While copying the
source code from a chapter and running it inside a virtual environment will work in
most cases (after running the migrations), there is no guarantee it will. The source
S

code is for your reference and to assist your learning, it’s not fully functioning code
that you can just copy and use in your projects.

—6—
Mastering Django - SAMPLE
 Chapter 1

Found a Bug or Typo?

With a book project the size of Mastering Django the odd bug or typo will slip
through. This is even after countless edits from me and plenty of feedback from my
awesome beta testers (you know who you are :)).

In a perfect world, I’d be able to pay the megabucks for professional editors, but

LE
there’s a reason why those of us who support Django all have day jobs; it ain’t exactly a
meal ticket.

So, if you find a bug or a typo, get in touch with me via the Djangobook website1 and
let me know so I can fix the error. The major plus of self-publishing is that I can make
changes quickly and send updates to everyone as soon as I have a batch of edits
completed. I will even make sure you get a free electronic copy of the updated version
P
if one of your edits makes it through to a published version of the book.

Errata and Django 3 Updates

M
I will be publishing errata (bugs and typos) information and updates for future
versions of Django 3 on the website here:
A

https://djangobook.com/mastering-django-errata-and-updates/

Getting Help
S

For any other questions regarding the book, you can contact me via the help page on
the Djangobook website. Note that, due to working full-time, it’s very difficult for me
to find time to answer Django questions that don’t directly relate to my books and
courses.

1 https://djangobook.com/django-help/

—7—
Mastering Django - SAMPLE
Introduction

Your first points of contact for general information on Django and answers to “how
do I…” questions should be Stack Overflow2, your favorite search engine, and any one
of the dozens of social media groups relating to Django.

LE
P
M
A
S

2 https://stackoverflow.com/questions/tagged/django

—8—
Mastering Django - SAMPLE
 Part 1
Django Fundamentals

LE
P
M
A
S

Mastering Django - SAMPLE

 LE
P
M
A
S

Mastering Django - SAMPLE

 2
Installing Python and Django

LE
Before you can start learning Django, you must install some software on your
computer. Fortunately, this is a simple three-step process:

1. Install Python
2. Install a Python Virtual Environment; and
3. Install Django
P
I’ve written this chapter mostly for those of you running Windows, as most new users
M
are on Windows. I have also included a section on installing Python 3 and Django on
macOS.

If you are using Linux, there are many resources on the Internet—the best place to
start is Django’s own installation instructions1.
A

For Windows users, your computer can be running any recent version of Windows
(7, 8.1 or 10).
S

This chapter also assumes you’re installing Django on a desktop or laptop computer
and will use the development server and SQLite to run all the code in this book. This
is by far the easiest and best way to set up Django when you are first starting.

1 https://docs.djangoproject.com/en/dev/intro/install/

Mastering Django - SAMPLE

Installing Python and Django

Installing Python

A lot of Windows applications use Python, so it may be already installed on your

system. You can check this out by opening a command prompt, or running
PowerShell, and typing python at the prompt.

If Python isn’t installed you’ll get a message saying that Windows can’t find Python. If

LE
Python is installed, the python command will open the Python interactive interpreter:

C:\Users\Nigel>python
Python 3.6.0 (v3.6.0:41df79263a11, Dec 23 2016, 07:18:10) [MSC
v.1900 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more
information.
>>>
P
You can see in the above example that my PC is running Python 3.6.0. Django 2.2 is
compatible with Python version 3.5 and later. Django 3.0 is compatible with Python
version 3.6 and later. If you have an older version of Python, you must install Python
M
3.7 or 3.8 for the code in this book to work. If you have Python 3.5 or 3.6, I still
recommend you install Python 3.8 to ensure you have the latest version installed on
your machine.
A

Assuming Python 3 is not installed on your system, you first need to get the installer.
Go to https://www.python.org/downloads/ and click the big yellow button that
says “Download Python 3.8.x”.
S

At the time of writing, the latest version of Python is 3.8.3, but it may have been
updated by the time you read this, so the numbers may be slightly different. Once you
have downloaded the Python installer, go to your downloads folder and double click
the file python-3.x.x.msi to run the installer. The installation process is the same as
any other Windows program, so if you have installed software before, there should be
no problem here; however, there is one essential customization you must make.

— 12 —
Mastering Django - SAMPLE
 Chapter 2
By default, the Python executable is not added to the Windows PATH. For Django
to work correctly, Python must be listed in the PATH statement. Fortunately, this is
easy to rectify—when the Python installer screen opens, make sure “Add Python 3.8
to PATH” is checked before installing (Figure 2-1).

Do Not Forget This Step!

It will solve most problems that arise from the incorrect mapping of pythonpath

LE
(an important variable for Python installations) in Windows.

P
M
A
S

Figure 2-1. Check the “Add Python 3.8 to PATH” box before installing.

Once Python is installed, restart Windows and then type python at the command
prompt. You should see something like this:

— 13 —
Mastering Django - SAMPLE
Installing Python and Django
C:\Users\nigel> python
Python 3.8.3 (tags/v3.8.3:6f8c832, May 13 2020, 22:20:19) [MSC
v.1925 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more
information.
>>>

Installing Python on macOS

LE
If you open a terminal and type python at the prompt, you will see that the system
version is Python 2 (Figure 2-2). Django is not compatible with Python 2, so we need
to install the latest version of Python 3.

P
M
A
S

Figure 2-2. macOS uses Python 2, which is incompatible with Django.

— 14 —
Mastering Django - SAMPLE
 Chapter 2
Downloading a copy of Python 3 follows the same process as Windows—Go to
https://www.python.org/downloads/ and click the big yellow button that says
“Download Python 3.x.x”. Your browser should automatically detect that you are
using macOS and take you to the correct download page. If it doesn’t, select the
correct operating system from the links below the button.

The Mac installer is in .pkg format, so once it’s downloaded, double-click the file to
run the package installer (Figure 2-3). The screenshot is for Python 3.7, but the

LE
process is identical for Python 3.8.

P
M
A
S

Figure 2-3. Follow the prompts to install Python 3 on macOS.

— 15 —
Mastering Django - SAMPLE
Installing Python and Django
Follow the installations steps and, when Python 3 has been installed, open a new
terminal window. If the installation was successful, typing python3 at the prompt will
open the Python 3 interactive shell (Figure 2-4). Note that macOS will happily run
multiple versions of Python on the one machine, you just need to make sure you select
the correct version when running the terminal.

LE
P
M
A

Figure 2-4. Once Python 3 is installed, run it from the terminal with the python3
command.
S

Creating a Python Virtual Environment

When you are writing new software programs, it’s possible (and common!) to modify
dependencies and environment variables that your other software depends on. This
can cause many problems, so should be avoided. A Python virtual environment solves
this problem by wrapping all the dependencies and environment variables that your

— 16 —
Mastering Django - SAMPLE
 Chapter 2
new software needs into a filesystem separate from the rest of the software on your
computer.

The virtual environment tool in Python is called venv, but before we set up venv, we
need to create our club site project folder.

Create a Project Folder

LE
Our project folder will house not only our virtual environment, but all the code and
media for our Django club site.

The project folder can go anywhere on your computer, although it’s highly
recommended you create it somewhere in your user directory, so you don’t get
permission issues later on. A good place for your project in Windows is your My
P
Documents folder. On a Mac your Documents folder is also a logical choice; however, it
can go anywhere in your user directory.
M
Create a new folder on your system. I have named the folder myclub_project, but
you can give the folder any name that makes sense to you.

For the next step, you need to be in a command window (terminal on Linux and
macOS). The easiest way to do this in Windows is to open Windows Explorer, hold
A

the SHIFT key and right-click the folder to get the context menu and click on Open
command window here (Figure 2-5).
S

— 17 —
Mastering Django - SAMPLE
Installing Python and Django

LE
Figure 2-5. Hold the shift key and right-click a folder to open a command window.

Terminal in Windows 10
P
If you are running newer versions of Windows 10, the command prompt has been
replaced by PowerShell. For the examples in this book, the command prompt and
PowerShell are functionally the same, and all commands will run in PowerShell
M
unmodified.

Create a Python Virtual Environment

Once you have created your project folder, you need to create a virtual environment
A

for your project by typing the following at the command prompt you just opened:

On Windows
S

...\Documents\myclub_project> python -m venv env_myclub

On Mac

...$ python3 -m venv env_myclub

— 18 —
Mastering Django - SAMPLE
 Chapter 2
Remember, you must be inside the project folder!

The function of this command is straightforward—the -m option tells Python to run

the venv module as a script. venv in turn requires one parameter: the name of the
virtual environment to be created. So this command is saying “create a new Python
virtual environment and call it env_myclub”

Once venv has finished setting up your new virtual environment, it will switch to an

LE
empty command prompt. When it’s done, open Windows Explorer (Finder on a
Mac) and have a look at what venv created for you. In your project folder, you will
now see a folder called
\env_myclub (or whatever name you gave the virtual environment). If you open the
folder on Windows, you will see the following:

\Include
\Lib
\Scripts
pyvenv.cfg
P
M
On a Mac, it’s:

/bin
/Include
A

/Lib
pyvenv.cfg

On either platform, if you look inside the \Lib folder, you will see venv has created a
S

complete Python installation for you, separate from your other software, so you can
work on your project without affecting other software on your system.

To use this new Python virtual environment, we have to activate it, so let’s go back to
the command prompt and type the following:

— 19 —
Mastering Django - SAMPLE
Installing Python and Django
On Windows

env_myclub\scripts\activate

On Mac

source env_myclub/bin/activate

LE
This will run the activate script inside your virtual environment’s \scripts folder. You
will notice your command prompt has now changed:

(env_myclub) ...\Documents\myclub_project>

On a Mac, the prompt looks like this:

P
(env_myclub) ... <yourusername>$
M
The (env_myclub) at the beginning of the command prompt lets you know that you
are running in the virtual environment.

Oops! Script Error!

A

If you are using PowerShell and running this script for the first time, the
activate command will throw a permission error.
S

If this happens to you, open PowerShell as an administrator and run the command:

Set-ExecutionPolicy remoteSigned

Once you have run this command, the activation script will run.

— 20 —
Mastering Django - SAMPLE
 Chapter 2
If you want to exit the virtual environment, you just type deactivate at the
command prompt:

(env_myclub) ...\Documents\myclub_project> deactivate

...\Documents\myclub_project>

Installing Django

LE
Mac Users Note

Once Python 3 and the virtual environment are installed, the installation steps for
Django are identical on both Windows and macOS.

The critical thing to remember with macOS is that system Python is version 2 and
P
Django requires Python 3, so you must be running the Python virtual environment
on macOS to run any of the code in this book.
M
Now we have Python installed and are running a virtual environment, installing
Django is super easy, just type the command:

pip install "django>=2.2,<3"

A

For Django 3, the command is:

pip install "django>=3.0,<4"

S

If you are not familiar with the pip command, put briefly, it’s the Python package
manager and is used to install Python packages. To keep with Python programming
tradition, pip is a recursive acronym for “Pip Installs Packages”.

— 21 —
Mastering Django - SAMPLE
Installing Python and Django
This will instruct pip to install the latest version of Django 2 or Django 3 into your
virtual environment. Your command output should look like this (for Django 2.2):

(env_myclub) ...\myclub_project> pip install "django>=2.2,<3.0"

Collecting django<3.0,>=2.2
Downloading .../Django-2.2.12-py3-none-any.whl (7.5MB)
|################################| 7.5MB 2.2MB/s
Collecting pytz (from django<3.0,>=2.2)
Downloading .../pytz-2020.1-py2.py3-none-any.whl (510kB)

LE
|################################| 512kB 3.3MB/s
Collecting sqlparse (from django<3.0,>=2.2)
Downloading .../sqlparse-0.3.1-py2.py3-none-any.whl (40kB)
|################################| 40kB 2.6MB/s
Installing collected packages: pytz, sqlparse, django
Successfully installed django-2.2.12 pytz-2020.1 sqlparse-0.3.1

The Django 3 installation output is identical except for the version numbers.
P
To test the installation, go to your virtual environment command prompt, start the
Python interactive interpreter by typing python and hitting Enter. If the installation
M
was successful, you should be able to import the module django:

(env_myclub) ...\myclub_project>python
Python 3.8.3 (tags/v3.8.3:6f8c832, May 13 2020, 22:20:19) [MSC
v.1925 32 bit (Intel)] on win32
A

Type "help", "copyright", "credits" or "license" for more

information.
>>> import django
>>> django.get_version()
'2.2.12' # Your version may be different.
S

>>> exit()

Don’t forget to exit the Python interpreter when you are done (you can also use
CTRL-Z).

— 22 —
Mastering Django - SAMPLE
 Chapter 2
You can also check if Django has been installed directly from the command prompt
with:

(env_myclub) ...\myclub_project>python -m django --version

2.2.12 # Your version may be different.

Starting a Project

LE
Once you’ve installed Python and Django, you can take the first step in developing a
Django application by creating a Django project.

A Django project is a collection of settings and files for a single Django website. To
create a new Django project, we’ll be using a special command to auto-generate the
folders, files and code that make up a Django project. This includes a collection of
P
settings for an instance of Django, database configuration, Django-specific options
and application-specific settings.
M
I am assuming you are still running the virtual environment from the previous
installation step. If not, start it again with env_myclub\scripts\activate\.

From your virtual environment command line, run the following command:
A

(env_myclub) ...>django-admin startproject myclub_site

This command will automatically create a myclub_site folder in your project folder,
S

and all the necessary files for a basic, but fully functioning Django website. Feel free to
explore what startproject created now if you wish, however, we will go into greater
detail on the structure of a Django project in the next chapter.

— 23 —
Mastering Django - SAMPLE
Installing Python and Django

Creating a Database

Django includes several applications by default (e.g., the admin program and user
management and authentication). Some of these applications make use of at least one
database table, so we need to create tables in the project database before we can use
them. To do this, change into the myclub_site folder created in the last step (type cd
myclub_site at the command prompt) and run the following command:

LE
python manage.py migrate

The migrate command creates a new SQLite database and any necessary database
tables, according to the settings file created by the startproject command (more on
the settings file later). If all goes to plan, you’ll see a message for each migration it
applies:

Operations to perform:
P
(env_myclub) ...\myclub_site>python manage.py migrate

Apply all migrations: admin, auth, contenttypes, sessions

M
Running migrations:
Applying contenttypes.0001_initial... OK
# several more migrations (not shown)

The Development Server

A

Let’s verify your Django project works. Make sure you are in the outer myclub_site
directory and run the following command:
S

python manage.py runserver

This will start the Django development server—a lightweight Web server written in
Python. The development server was created so you can develop things rapidly,
without having to deal with configuring a production server until you’re ready for
deployment.

— 24 —
Mastering Django - SAMPLE
 Chapter 2
When the server starts, Django will output a few messages before telling you that the
development server is up and running at http://127.0.0.1:8000/. If you were
wondering, 127.0.0.1 is the IP address for localhost, or your local computer. The 8000
on the end is telling you that Django is listening at port 8000 on your local host.

You can change the port number if you want to, but I have never found a good reason
to change it, so best to keep it simple and leave it at the default.

LE
Now that the server is running, visit http://127.0.0.1:8000/ with your web
browser. You’ll see Django’s default welcome page, complete with a cool animated
rocket (Figure 2-6).

P
M
A
S

Figure 2-6. Django’s welcome page. The welcome page is the same for Django 2 and 3.

— 25 —
Mastering Django - SAMPLE
Installing Python and Django

TIP: Remember the Startup Sequence

It will help to make a note of this sequence, so you know how to start your Django
project each time you return to the examples in this book:

On Windows:

1. Shift right-click your project folder to open a command window.

2. Type in env_myclub\scripts\activate to run your virtual

LE
environment.
3. Change into your site directory (cd myclub_site) to run manage.py
commands (e.g., runserver).
4. Type deactivate to exit the virtual environment.

On macOS:

1. CTRL-click your project folder to open a terminal window.

P
2. Type in source env_myclub/bin/activate to run your virtual
environment.
3. Change into your site directory (cd myclub_site) to run manage.py
commands (e.g., runserver).
M
4. Type deactivate to exit the virtual environment.

Chapter Summary
A

In this chapter, I showed you how to install Python 3 and Django on both Windows
and macOS. In the next chapter, we will step back a bit and have a big-picture look at
Django’s structure and how all the parts of Django work together to create powerful,
scalable web applications.
S

— 26 —
Mastering Django - SAMPLE
 3
The Big Picture

LE
Django’s Structure—A Heretic’s Eye View

The most common complaints from those new to Django is “it’s too hard to
understand”, or “it’s too complex”. You may even be thinking this yourself right now.
P
At the fundamental level, Django isn’t complicated. Yes, it has its quirks and, yes, big
Django projects can be very complex beasts, but bottom line: Django is a logically
M
structured framework built on the easiest to learn programming language available
(Python).

As an educator, I have spent countless hours trying to work out why people find
Django complex and hard to learn. Thinking on this has led me to commit heresy #1:
A

it’s not your fault, we’ve just been teaching it wrong.

Remember all the books and tutorials that start with “Django is a Model-View-
S

Controller (MVC) framework…”? (This is cut and paste from one of my books, so I
am as guilty as anyone in this).

Stating up front that Django is an MVC framework gets one of two responses:

1. Beginners say “What the heck is MVC? *groan*. Guess that’s one more fricking
thing I have to learn!”

Mastering Django - SAMPLE

The Big Picture
2. More experienced programmers say “Aha! It’s just like Framework X.”

In both cases, they’re almost entirely wrong.

Django is a Loosely Coupled Framework

If you can indulge me a minute, and purge your brain of your favorite Three Letter

LE
Acronyms (TLAs), there’s an easier way to understand this.

The first step is to understand that Django is not the result of an academic exercise,
nor is it some guru’s idea of cool—Django’s creators designed Django to solve a
particular set of problems in a busy and complex news organization. At the center of
this set of problems were three very different needs:

P
1. The data guys (and gals) needed a common interface to work with disparate
data sources, formats and database software.
2. The design teams needed to manage the user experience with the tools they
already had (HTML, CSS, JavaScript etc.).
M
3. The hard-core coders required a framework that allowed them to deploy system
changes rapidly and keep everyone happy.

Crucial to making this all work was ensuring each of these core components—data,
A

design and business logic—could be managed independently, or to use the correct

computer parlance—the framework had to employ loose coupling.

Now, it’s important to understand that I’m not trying to say Django is doing anything
S

magic or new here, nor were the problems Django’s creators faced unique. The creators
of Django are brilliant guys, and they certainly knew MVC was a well-established
design pattern that would help solve their problems.

My point is it’s highly unlikely any of them ever said, “Hang on boys, we need to
change this code because Wikipedia says a controller should …”.

— 28 —
Mastering Django - SAMPLE
 Chapter 3
You need not get hung up on semantics—you can safely forget about the confusing
TLAs and whether Django is like Framework X and concentrate on what Django is.

Django’s architecture comprises three major parts:

f Part 1 is a set of tools that make working with data and databases much easier.
f Part 2 is a plain-text template system suitable for non-programmers; and

LE
f Part 3 is a framework that handles communication between the user and the
database and automates many of the painful parts of managing a complex
website.

Parts 1 and 2 are instantly relatable:

f Django Models are the tools we use to work with data and databases; and
P
f Django Templates provide a designer-friendly plain-text template system.

But what about Part 3? I hear you ask, isn’t that the controller, or a Django view?
M
Well, no. Which leads me to heresy #2:

A Django View is Not a Controller

A

Check out Figure 3-1 on the next page, does it look familiar?

This is one of my diagrams, but there are plenty of similar versions out there. A
S

common way of explaining Django’s architecture in terms of MVC is to describe it as

a Model-Template-View (MTV) or Model-View-Template (MVT). There’s no
difference between MTV and MVT—they’re two different ways to describe the same
thing, which adds to the confusion.

— 29 —
Mastering Django - SAMPLE
The Big Picture

Model Template
Object
Relational Display
Mapping t

LE
Logic
(ORM)

pu
Da

r In
tas
ets

Use
C re a

y
te,

p la
Up

D is
e,
da

P F

or
De
t

le te View D ata
Business
M
Logic
A

Figure 3-1. The somewhat misleading Django MTV diagram.

S

The misleading part of this diagram is the view. The view in Django is most often
described as being equivalent to the controller in MVC, but it’s not—it’s still the view.

Figure 3-2 is a variation on Figure 3-1 to illustrate my point.

— 30 —
Mastering Django - SAMPLE
 Chapter 3

LE
P
M
A

Figure 3-2. A slightly different view of Django’s MTV “stack”.

S

Note how I have drawn a line between the client- and server-side.
Like all client/server architectures, Django uses request and response objects to
communicate between the client and the server. As Django is a web framework, we’re
talking about HTTP request and response objects.

— 31 —
Mastering Django - SAMPLE
The Big Picture
So, in this simplified process, the view retrieves data from the database via the model,
formats it, bundles it up in an HTTP response object and sends it to the client
(browser).

In other words, the view presents the model to the client as an HTTP response. This
is also the exact definition of the view in MVC, or to quote Wikipedia (not the most
definitive source, I know, but close enough):

LE
“The view means presentation of the model in a particular format”

Trying to bend the definition of a Django view to fit a particular viewpoint inevitably
leads to one of two things:

1. Confused programmer puts everything in views module; or

2. Confused programmer says “Django is too hard!”, and watches TV instead.
P
So getting away from our M’s and T’s and V’s and C’s, Figure 3-3 presents a more
holistic view of Django’s architecture.
M
The first point of confusion we can clear up is where to put a particular function or
class:

Does the function/class return a response?

A

f YES—it’sa view. Put it in the views module (views.py).

f NO—it’s not a view, it’s app logic. Put it somewhere else (somewhere_else.py).
S

We’ll discuss the somewhere else part in the next section of this chapter.

— 32 —
Mastering Django - SAMPLE
 Chapter 3

LE
P
M
A

Figure 3-3. A more holistic view of Django’s architecture.

The next point to note is that the Django framework encapsulates the model, view
S

logic and business logic. In some tutorials, it’s said that the Django framework is the
controller, but that isn’t true either—the Django framework can do much more than
respond to user input and interact with data.

A perfect example of this extra power is Django’s middleware, which sits between the
view and the client-side. Django’s middleware performs critical security and
authentication checks before sending the response to the browser.

— 33 —
Mastering Django - SAMPLE
The Big Picture
So, returning to the two confused responses from the beginning of the chapter:

1. Beginners—no, you don’t have to learn about MVC because it’s more than
likely going to confuse you and lead to more questions than answers.
2. Programmers—no, Django is not like Framework X, and trying to think it is,
is likely to confuse you and lead to more questions than answers.

Now we’ve got that out of the way, let’s have a look at the structure of a Django

LE
project.

Django Project Structure

Django doesn’t require you to build web applications in any particular way. In fact,
billions of electrons have been sacrificed discussing the One Best Way to structure a
P
Django project. We’re all pragmatic programmers here, so we won’t play that game.

Django does, however, have a default way of doing things, and there is a definite
underlying logic to it you need to understand to become a professional Django
M
programmer.

The fundamental unit of a Django web application is a Django project. A Django

project comprises one or more Django apps (Figure 3-4)
A

A Django app is a self-contained package that should only do one thing. For example,
a blog, a membership app or an event calendar. Notice at the bottom of Figure 3-4,
there’s an extra package called Django Apps.
S

— 34 —
Mastering Django - SAMPLE
 Chapter 3

LE
P
M
A
S

Figure 3-4. Django’s project structure.

— 35 —
Mastering Django - SAMPLE
The Big Picture
This is another case where Django’s logic carries right through the framework—
Django itself is a collection of apps, each designed to do one thing. With Django’s
built-in apps, they’re all designed to make your life easier, which is a Good Thing.

While the built-in apps are invisible in your project tree, you can see them in your
settings.py file:

# ...\myclub_project\myclub_site\myclub_site\settings.py

LE
# partial listing

INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',

]
P
'django.contrib.staticfiles',
M
You can see that Django has added several apps to your project automatically. There
are also many other built-in Django apps you can add to the INSTALLED_APPS list.
When you add your apps to a Django project, you also add a link to the app
configuration class to this list.
A

You can see this logic in what Django has created for you so far. Open up your \
myclub_project folder. The folder structure should look something like this:

# ...\my_clubproject
S

\env_myclub
\myclub_site <= This is your Django project
\myclub_site <= This is a Django app
db.sqlite3 <= Your project database
manage.py <= Django project management utility

— 36 —
Mastering Django - SAMPLE
 Chapter 3
Let’s examine these files and folders in more detail:

f The env_myclub folder is where Django stores your virtual environment files.
Generally, you should leave everything inside this folder alone.
f The outer myclub_site folder is your Django project. Django created this
folder and its contents when you ran the startproject command in the last
chapter. Django doesn’t care about the folder name, so you can rename it to
something meaningful to you.

LE
f Inside the outer myclub_site folder are two files:
Z db.sqlite3. The database created when you ran the migrate command;
and
Z manage.py. A command-line utility for executing Django commands from
within your project.
f The inner myclub_site folder is your Django website application. This is the
P
one application that Django creates automatically for you. Because Django is a
web framework, it assumes you want a website app.

This should make more sense by now, but I bet there is one thing that’s still a bit
M
confusing—the two myclub_site folders.

A very common complaint from programmers new to Django is how confusing it is

to know which folder they should work in when there are two folders named the
A

same. Django is not alone with this convention—Integrated Development

Environments (IDEs) like Visual Studio create a project folder and application folder
with the same name. But just because it’s common, that doesn’t mean it isn’t
confusing.
S

As I said a moment ago, Django doesn’t care what you name this folder—so let’s
commit heresy #3, breaking thirteen years of Django tutorial convention while we are
at it, and rename the folder!

Here, we’re renaming it to “myclub_root”.

— 37 —
Mastering Django - SAMPLE
The Big Picture
Once you have made the change, your folder structure should go from this:

\myclub_project
\myclub_site
\myclub_site

To this:

LE
\myclub_project
\myclub_root
\myclub_site

Now we’ve taken care of that source of confusion, let’s have a look inside the myclub_
site website app Django created for us:

\myclub_site
__init.py__
P
# \myclub_project\myclub_root\
M
asgi.py # Django 3 only
settings.py
urls.py
wsgi.py
A

Looking closer at these files:

f The __init__.py file tells Python that this folder (your Django app) is a
Python package.
S

f asgi.py enables ASGI compatible web servers to serve your project (Django 3
only).
f settings.py contains the settings for your Django project. Every Django
project must have a settings file. By convention, Django puts it in your website
app, but it doesn’t have to live there. There are proponents for other structures as
I mentioned earlier, but here we’re using the default.

— 38 —
Mastering Django - SAMPLE
 Chapter 3
f urls.py contains project-level URL configurations. By default, this contains a
single URL pattern for the admin. We will cover more on URLs later in the
chapter, and in great detail in Chapter 5.
f wsgi.py enables WSGI compatible web servers to serve your project.

Now that we’ve had a good look at the basic structure of a Django project, it’s time to
take the next step and add our own Django app.

LE
Creating Your Own Django Apps

You might have noticed that there is no real program code in your project so far. There
is a settings file with configuration information, an almost empty URLs file, and a
command-line utility that launches a website that doesn’t do much.

P
This is because to create a functioning Django website, you need to create Django
applications. A Django application (or app for short) is where the work gets done.
Apps are one of Django’s killer features. Not only do they allow you to add
functionality to a Django project without interfering with other parts of the project,
M
but apps are designed to be portable so you can use one app in multiple projects.

So, let’s create our first custom Django app. Our social club website needs an events
calendar to show upcoming events for the club, so we’re creating a Django app called
A

events.

Fire up your Python virtual environment, switch into the \myclub_root folder and
run the command:
S

python manage.py startapp events

This is what your command shell output should look like:

(env_myclub) ...> cd myclub_root

— 39 —
Mastering Django - SAMPLE
The Big Picture
(env_myclub) ...\myclub_root> python manage.py startapp events
(env_myclub) ...\myclub_root>

Once you have created your app, you must tell Django to install it into your project.
This is easy to do—inside your settings.py file is a list named INSTALLED_APPS.
This list contains all the apps installed in your Django project. Django comes with a
few apps pre-installed, we just have to add your new events app to the list (change in
bold):

LE
1 INSTALLED_APPS = [
2 'events.apps.EventsConfig',
3 'django.contrib.admin',
4 # more apps
5 ]

P
Inside every app, Django creates a file, apps.py, containing a configuration class
named after your app. Here, the class is named EventsConfig. To register our app
with Django, we need to point to the EventsConfig class—which is what we are
doing in line 2 of our modified INSTALLED_APPS list.
M
If you were wondering, EventsConfig contains a single configuration option by
default—the name of the app (“events”).
A

Line Numbering in Code Examples

Throughout the book, I use line numbering to make it easier for you to follow
along with the explanations.
S

As I often use code snippets from your application files, the line numbering in the
example is not the same as the line numbering in the actual source code file.

— 40 —
Mastering Django - SAMPLE
 Chapter 3
Now let’s look inside the \myclub_root folder to see what Django has created for us:

\events
\migrations
__init__.py
admin.py
apps.py
models.py
tests.py

LE
views.py

f The migrations folder is where Django stores migrations, or changes to your

database. There’s nothing in here you need to worry about right now.
f __init__.py tells Python that your events app is a package.
f admin.py is where you register your app’s models with the Django admin
application.
f apps.py
P
is a configuration file common to all Django apps.
f models.py is the module containing the models for your app.
f tests.py contains test procedures that run when testing your app.
M
f views.py is the module containing the views for your app.

Now we have a complete picture of a Django project, we can also answer the question
from earlier in the chapter: “well, if it’s not a view, where does it go?”
A

When you have code that isn’t a view, you create a new Python module (.py file)
inside your app and put related functions and classes inside the file. Note the emphasis
on related. If you have a bunch of functions that provide database management
S

utilities, for example, put them all in one file. Functions and classes not related to
database management should go in another file. You should also try to be descriptive
in naming modules—after all, it’s more sensible to put your database functions in a
file called db_utils.py than a file called monkeys.py…

When creating new modules for your Django project, you should also consider scope.
While adding custom modules to apps is far more common (and more portable), you

— 41 —
Mastering Django - SAMPLE
The Big Picture
can have project-level modules (e.g., Django’s manage.py) and site-level modules. In
the latter case, your custom modules should go in the same folder as your settings.
py file.

The last couple of points might seem blindingly obvious, but it’s important to
understand that, while Django has a default logic to its structure, nothing is cast in
stone. Django is flexible and allows you to expand and change your project structure
to suit the logic of your web application.

LE
Now we have a thorough understanding of the structure of Django’s projects and
apps, the next obvious question, given we are building web applications is “how do we
navigate a Django project?”

To answer this question, we need to check out the final piece of the Django big
picture puzzle—URL configurations.

URLconfs—Django’s Navigator
P
M
There’s one last piece to the Django framework puzzle—the critical communication
pathway that matches a request on the client-side with a project resource (the arrows
between the view and the template in Figure 3-3). Like all web applications, Django
uses Uniform Resource Locators (URLs) to match content with a request.
A

Django’s urls package provides dozens of functions and classes for working with
different URL formats, name resolution, exception handling and other navigational
utilities. However, at its most basic, it allows you to map a URL to a function or class
S

within your Django project.

A Django URL configuration (or URLconf for short) matches a unique URL with a
project resource. You can think of it being like matching a person’s name with their
address. Except in Django, we’re not matching a street address—we’re matching a
Python path using Python’s dot notation.

— 42 —
Mastering Django - SAMPLE
 Chapter 3
Assuming you’re not familiar with dot notation, it’s a common idiom in object-
oriented programming. I like to think of the dot like a point because the dot points to
something. With Python, the dot operator points to the next object in the object
chain.

In Django classes, the object chain is like this:

package.module.class.method

LE
Or with functions:

package.module.function.attribute

Some real-life examples:

f forms.Form
P
points to the Form class in the forms package.
f events.apps.EventsConfig points to the EventsConfig class in the apps
M
sub-package of the events package (i.e., the apps.py file in your events app).
f django.conf.urls points to the urls package inside the conf package inside
Django, which is also a Python package!

This can sometimes get a bit confusing, but if you remember to join the dots (sorry, a
A

bad pun there), you can usually find out what the dot operator is referring to.

With a URLconf, the path points to a function or class inside a module (.py file).
Let’s look at our Django project diagram again (Figure 3-5).
S

— 43 —
Mastering Django - SAMPLE
The Big Picture

LE
P
M
Figure 3-5. Finding functions and classes with Django’s URLconfs.
A

To create a URLconf, we use the path() function. The first part of the function is the
URL, so in Figure 3-5 the URL is app1/. The path() function then maps this URL
to app1.views.some_view().
S

Assuming your site address is http://www.mycoolsite.com, in plain English we’re

saying:

“When someone navigates to http://www.mycoolsite.com/app1/, run the some_

view() function inside app1’s views.py file”

— 44 —
Mastering Django - SAMPLE
 Chapter 3
Note a URL doesn’t have to map to a view—it can map to any module in your
Django app. For example, you may have a set of wireless environmental sensors that
post data back to the server. You could have a custom module called sensors.py that
has a function or class to record the sensor data to your database, all without ever
touching a view.

And that’s all there is to it. Of course, URLconfs can do a lot more than map a static
URL to a function or class, but if you can understand the basics—that Django’s

LE
incredibly fast and powerful navigation system is based on the simple concept of
matching a URL with a resource—then you have all you need to tie all your Django
apps together into a navigable web project.

A Final Note on Writing Django Apps

basic structure:
P
A common and inevitable question arises once you get your head around Django’s

“Where do I start? Should I start with writing my models, the URL configurations,
M
my views? Or what?”

Well, here’s your final heresy for the chapter: it doesn’t matter.
A

Some people like to start by building all the models so they can see how the data
structure looks; others prefer to build the visual layout first, so they start with
templates. Others might like to get the basic communication framework in place, so
they start with views and URLconfs. Others will start at whatever point seems logical
S

for the project.

Being pragmatic to the bone, I am usually in the last group. I try not to get fixated on
what someone else thinks is the right or the wrong way to do things and try to find
the simplest and quickest way to achieve the result I want. I also like to work
incrementally starting small getting the flow right and building on it to create the

— 45 —
Mastering Django - SAMPLE
The Big Picture
complete application. This approach means I inevitably end up jumping from one
element to another as the application grows.

Your brain is wired differently to mine and every other programmer. This is a Good
Thing. Just remember, an imperfect start to a project is way better than not starting at
all. Do what works for you.

Chapter Summary

LE
In this chapter, I gave you a high-level overview of how Django projects are
structured, how each component works with other parts of Django to create a web
application, and how to create a Django app.

In the next chapter, we will start diving into the inner working of Django’s core
P
modules by exploring the fundamentals of Django’s models.
M
A
S

— 46 —
Mastering Django - SAMPLE
 4
Django’s Models

LE
Unless you are creating a simple website, there is little chance of avoiding the need to
interact with some form of database when building modern web applications.

Unfortunately, this usually means you have to get your hands dirty with Structured
P
Query Language (SQL)—which is just about nobody’s idea of fun. In Django, the
messy issues with SQL is a solved problem: you don’t have to use SQL at all unless
you want to. Instead, you use a Django model to access the database.
M
Django’s models provide an Object-relational Mapping (ORM) to the underlying
database. ORM is a powerful programming technique that makes working with data
and relational databases much easier.
A

Most common databases are programmed with some form of SQL, but each database
implements SQL in its own way. SQL can also be complicated and difficult to learn.
An ORM tool simplifies database programming by providing a simple mapping
between an object (the ‘O’ in ORM) and the underlying database. This means the
S

programmer need not know the database structure, nor does it require complex SQL
to manipulate and retrieve data (Figure 4-1).

Mastering Django - SAMPLE

Django's Models

SQL


CREATE TABLE "pages_page" ("id"
integer NOT NULL PRIMARY KEY
AUTOINCREMENT, "title" varchar(60)
NOT NULL, "permalink" varchar(12)
NOT NULL UNIQUE, "update_date"
datetime NOT NULL, "bodytext"
text NOT NULL); COMMIT;

LE
Database
Django ORM
P

class Page():
title = CharField
M
permalink = CharField
update_date = DateTimeField
bodytext = TextField
A

Figure 4-1. An ORM allows for simple manipulation of data without having to write
complex SQL.
S

In Django, the model is the object mapped to the database. When you create a model,
Django executes SQL to create a corresponding table in the database (Figure 4-2)
without you having to write a single line of SQL. Django prefixes the table name with
the name of your Django application. The model also links related information in the
database.

— 48 —
Mastering Django - SAMPLE
 Chapter 4

Table yourapp_userprofile
Model :
ID 1001
username
username big-nige

Nigel
last_name
last_name George
email

LE
email [email protected]

Figure 4-2. Creating a Django model creates a corresponding table in the database.

In Figure 4-3, a second model keeps track of a user’s course enrollments. Repeating all
the user’s information in the yourapp_Course table would be against sound design
principles, so we instead create a relationship (the ‘R’ in ORM) between the yourapp_
P
Course table and the yourapp_UserProfile table.

Table
M
ID 1001

username big-nige

Nigel

last_name George

email [email protected]
A

Table yourapp_Course
Model Course:
S

ID 2001

user_id 1001
course_name
course_name Django 101
description
description This course is...
start_date
start_date 09/09/2017

Figure 4-3. Foreign key links in Django models create relationships between tables.

— 49 —
Mastering Django - SAMPLE
Django's Models
This relationship is created by linking the models with a foreign key—i.e., the user_
id field in the yourapp_Course table is a key field linked to the id field in the
foreign table yourapp_UserProfile.

This is a simplification, but is a handy overview of how Django’s ORM uses the
model data to create database tables. We will dig much deeper into models shortly, so
don’t worry if you don’t 100% understand what is going on right now. Things become
clearer once you have had the chance to build actual models.

LE
Supported Databases

Django officially supports five databases:

f PostgreSQL
f
f
f
MySQL
SQLite
Oracle
P
M
f MariaDB (Django 3 only)

There are also several third-party applications available if you need to connect to an
unofficially supported database.
A

The preference for most Django developers, myself included, is PostgreSQL. MySQL
is also a common database back end for Django. Installing and configuring a database
is not a task for a beginner. Luckily, Django installs and configures SQLite
S

automatically, with no input from you, so we will use SQLite in this book.

I cover running your project with PostgreSQL, MySQL and MariaDB in Chapter 16.

— 50 —
Mastering Django - SAMPLE
 End of sample content.
To purchase the complete book, go to https://djangobook.com/mastering-django-2-book/.