Core concepts

What we're doing: Scaffold a new Django project and see the pieces it generates before any app-specific code is written.

pip install django
django-admin startproject mysite
cd mysite
python manage.py runserver

2

startproject generates a runnable project: manage.py plus a mysite/ package holding settings.py, urls.py, asgi.py, wsgi.py.

4

runserver starts a development server — no separate web server or database setup needed to see it working.

Why this works: Every Django project starts from the same generated skeleton, which is the point: settings, URL routing, and the WSGI/ASGI entry points are already wired together and agree with each other, so the first thing you run is a working (if empty) site rather than a pile of decisions to make before anything responds to a request.

What we're doing: See how many of Django's "batteries" are already turned on in a freshly generated settings.py.

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]

2

The admin site — a full CRUD interface generated from your models, with no view code written for it.

3

Authentication — a User model, login/logout, and permission checks, ready before any app-specific code exists.

4

Sessions — per-visitor server-side storage, addressed later in this subsection.

5

Messages — the one-time flash-notification framework, also covered later.

Why this works: A brand-new Django project already has working admin, auth, sessions, and messaging before a single line of app-specific code is written — that upfront list is what "batteries-included" means concretely, not just as a slogan. A microframework would need a separate package installed and wired up for each of these.

What we're doing: Trace one request through all three MTV layers for a single article page.

from django.shortcuts import render
from .models import Article

def article_detail(request, pk):
    article = Article.objects.get(pk=pk)
    return render(request, "articles/detail.html", {"article": article})

2

Article is the Model — imported here, defined in models.py, and mapped to a database table.

4

article_detail is the View — it owns no data shape of its own, only the logic connecting request to Model to Template.

5

render() combines the "articles/detail.html" Template with a context dict — the Template never queries the database itself.

Why this works: Each layer has exactly one job: the Model defines what an Article is and how it is stored, the View decides which Article to fetch and which Template to use, and the Template only knows how to lay out whatever context dict it was handed. Keeping these separate is what Django's "loose coupling" design philosophy means in practice — you can redesign detail.html without touching views.py, and vice versa.

What we're doing: Show the file layout that startproject and startapp each generate, and how an app gets wired into the project.

mysite/                # the PROJECT root
    manage.py
    mysite/
        settings.py     # one settings module for the whole project
        urls.py         # the root URL configuration
    blog/                # an APP — self-contained feature
        models.py
        views.py
        urls.py
        migrations/

7

blog/ is registered in mysite/settings.py's INSTALLED_APPS — that single line is what makes the project aware the app exists.

Why this works: Splitting a site into a project (settings, root routing — the "house") and one or more apps (features — the "rooms") is what lets an app like a third-party comment system be dropped into any project's INSTALLED_APPS without rewriting it, while the project itself stays a one-off, specific to this site.

What we're doing: Register signal receivers safely by connecting them from AppConfig.ready(), which only runs after the registry has finished loading every model.

from django.apps import AppConfig

class BlogConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "blog"
    verbose_name = "Blog"

    def ready(self):
        from . import signals

3

BlogConfig customizes the app — this class is what the registry stores metadata against.

8

ready() runs after every app's models are importable, so importing signals here is safe — doing it at module import time earlier in startup risks importing a model before it exists.

Why this works: The registry loads in three explicit stages precisely so code like signal registration has a well-defined safe point to run: by the time ready() fires, every app's models module has already been imported, so signals.py can safely import and reference any model in the project without a circular-import risk.

What we're doing: Read a setting correctly from application code, and see why importing it directly does not work.

from django.conf import settings

def debug_banner(request):
    if settings.DEBUG:
        return HttpResponse("DEBUG MODE")
    return HttpResponse("")

1

settings is imported as an object from django.conf, not as the settings.py module itself.

4

settings.DEBUG reads the current value — Django resolves this against whichever module DJANGO_SETTINGS_MODULE points at.

Why this works: django.conf.settings is a lazily-evaluated proxy object, not the settings module — it resolves DJANGO_SETTINGS_MODULE the first time any setting is accessed, so the same application code works unchanged whether the environment points it at settings.py, settings_dev.py, or settings_prod.py.

What we're doing: Split a project's URLconf into a root file and a per-app file using include(), then capture a typed argument.

from django.urls import include, path
from django.contrib import admin

urlpatterns = [
    path("admin/", admin.site.urls),
    path("articles/", include("articles.urls")),
]

# articles/urls.py
# from django.urls import path
# from . import views
#
# app_name = "articles"
# urlpatterns = [
#     path("<int:year>/<int:month>/", views.archive, name="archive"),
# ]

5

include("articles.urls") delegates everything under /articles/ to the articles app's own urlpatterns — the app owns its own routing.

12

<int:year> and <int:month> are captured and converted to Python ints before being passed to the view as positional arguments.

Why this works: include() lets an app be dropped into any project and immediately own a whole section of the URL space, without the root urls.py needing to list every one of the app's individual routes — the exact reusability project vs. application describes for apps in general.

What we're doing: Write a function-based view that looks up an object, handles the not-found case, and renders a template.

from django.http import Http404
from django.shortcuts import render
from .models import Article

def detail(request, pk):
    try:
        article = Article.objects.get(pk=pk)
    except Article.DoesNotExist:
        raise Http404("Article does not exist")
    return render(request, "articles/detail.html", {"article": article})

5

detail(request, pk) — request is always first; pk arrives as a captured URL segment (see URL configuration).

6

The lookup can fail, so it is wrapped rather than assumed to succeed.

8

raise Http404(...) is how a view signals "not found" — Django catches it and returns a proper 404 response.

9

render() is the usual way to satisfy the "must return an HttpResponse" contract — it returns one built from a template and context.

Why this works: Every view must return an HttpResponse no matter what happens inside it — Http404 is not a way to skip that contract, it is Django's own mechanism for producing a normal (if unsuccessful) HttpResponse from an exceptional case, which is why raising it works instead of returning early with nothing.

What we're doing: Write a minimal middleware that times a request and adds the duration as a response header, showing the before/after split around get_response().

import time

def timing_middleware(get_response):
    def middleware(request):
        start = time.monotonic()
        response = get_response(request)
        elapsed = time.monotonic() - start
        response["X-Response-Time"] = f"{elapsed:.3f}s"
        return response
    return middleware

3

timing_middleware(get_response) is the factory — Django calls it once at startup, with get_response being the next layer inward.

5

Code before get_response(request) is the "on the way in" phase.

6

get_response(request) hands off to the next layer — eventually the view itself.

8

Code after get_response(request) is the "on the way out" phase — it runs after the view has already produced a response.

Why this works: Splitting each middleware into "before get_response" and "after get_response" is what makes the onion model work: the timer has to start before the view runs and read elapsed time after it returns, so it necessarily wraps get_response() rather than running entirely before or after the whole chain.

What we're doing: Define a model, then use its auto-generated manager API to create and query rows.

from django.db import models

class BlogPost(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    is_published = models.BooleanField(default=False)

# usage, e.g. in a view or shell:
post = BlogPost.objects.create(title="Hello", content="First post", is_published=True)

published = BlogPost.objects.filter(is_published=True)

3

BlogPost(models.Model) — the class defines the shape of a row, three fields plus the automatic id.

9

.objects.create(...) builds and saves one new row in a single call — the class itself is never queried directly, only through .objects.

11

.objects.filter(...) returns a QuerySet — a lazy, database-backed collection matching the condition, not a plain Python list.

Why this works: The class body only declares shape — title, content, is_published — nothing about it queries or writes to the database until .objects is used, the same separation between "define the blueprint" and "build/query instances of it" that classes and objects establishes for plain Python classes.

What we're doing: Register a model with the bare minimum, then upgrade to a customized ModelAdmin.

from django.contrib import admin
from .models import Article

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ["title", "author", "is_published"]
    list_filter = ["is_published"]
    search_fields = ["title"]

4

@admin.register(Article) connects the class below it to Article — equivalent to calling admin.site.register(Article, ArticleAdmin) afterward.

6

list_display controls the columns shown on the change list page — without it, only the object's __str__ shows.

7

list_filter adds a sidebar for narrowing the list by is_published, with no extra view code.

Why this works: Every one of these options customizes presentation of a model that already exists — none of them touch the database or add new fields, because the admin's whole value is generating an interface FROM the model you already defined, not defining a second, separate one just for admin.

What we're doing: Write a custom command that closes a poll by id, using add_arguments() for input and self.style for output.

from django.core.management.base import BaseCommand, CommandError
from polls.models import Question as Poll

class Command(BaseCommand):
    help = "Closes the specified poll for voting"

    def add_arguments(self, parser):
        parser.add_argument("poll_ids", nargs="+", type=int)

    def handle(self, *args, **options):
        for poll_id in options["poll_ids"]:
            try:
                poll = Poll.objects.get(pk=poll_id)
            except Poll.DoesNotExist:
                raise CommandError(f'Poll "{poll_id}" does not exist')
            poll.opened = False
            poll.save()
            self.stdout.write(self.style.SUCCESS(f'Closed poll "{poll_id}"'))

4

class Command(BaseCommand) — this exact name, in this exact file location, is what manage.py discovers automatically.

7

add_arguments() defines the command's CLI arguments using the standard library's argparse.

10

handle() is the one required method — everything the command actually does goes here.

Why this works: Placing the file at polls/management/commands/closepoll.py is the entire registration mechanism — Django discovers commands by walking that directory structure across every installed app, so `python manage.py closepoll 1 2 3` works with no import or settings entry beyond the app itself being in INSTALLED_APPS.

What we're doing: Render a template that loops over related objects and conditionally shows content, driven entirely by the view's context dict.

<h1>{{ story.title }}</h1>
<p>By {{ story.author }}</p>
{% if story.published %}
  <p>{{ story.content }}</p>
{% else %}
  <p>This story is not yet published.</p>
{% endif %}
{% for comment in story.comments %}
  <p>{{ comment.text }} — {{ comment.author }}</p>
{% endfor %}

3

{% if story.published %} branches purely on a value already computed and passed in by the view — the template does not query anything.

8

{% for comment in story.comments %} iterates whatever iterable the view put in the context under that key.

Why this works: Every value the template touches — story, story.published, story.comments — was already resolved by the view before render() was called. The template only formats what it is handed, which is the same MTV separation of concerns that keeps a Template ignorant of HTTP and the database entirely.

What we're doing: Handle both GET (show a blank form) and POST (validate submitted data) with the same Form class in one view.

from django.shortcuts import render, redirect
from .forms import ContactForm

def contact(request):
    if request.method == "POST":
        form = ContactForm(request.POST)
        if form.is_valid():
            subject = form.cleaned_data["subject"]
            sender = form.cleaned_data["sender"]
            return redirect("thanks")
    else:
        form = ContactForm()
    return render(request, "contact.html", {"form": form})

6

ContactForm(request.POST) is bound to the submitted data — the same class used unbound on line 11 for a fresh GET request.

7

is_valid() must be called before cleaned_data is trustworthy — it runs every field's validator and collects errors.

8

cleaned_data["subject"] is the validated, converted value — not the raw request.POST["subject"] string.

Why this works: The same ContactForm class handles both branches because a Form is just a description of fields and their validation rules — whether it is "unbound" (line 11, nothing to validate yet) or "bound" (line 6, data attached) is a property of the instance, not something requiring two different classes.

What we're doing: Send a welcome email exactly once, when a User is first created — not on every subsequent save.

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User

@receiver(post_save, sender=User)
def notify_user_created(sender, instance, created, **kwargs):
    if created:
        send_mail("Welcome!", f"Welcome {instance.username}",
                   "from@example.com", [instance.email])

3

sender=User restricts this receiver to only fire for User saves, not every model in the project.

5

created is True only on the INSERT that first creates the row — False on every later .save() that updates it.

6

if created guards the email so an existing user editing their profile does not get "welcomed" again.

Why this works: post_save fires on every save — insert AND update — so `created` is the only way to tell them apart from inside the receiver. Checking it is what makes this a "welcome new user" signal instead of a "spam every save" signal.

What we're doing: Reference an app-namespaced static file from a template, then prepare it for production with collectstatic.

{% load static %}
<link rel="stylesheet" href="{% static 'blog/post.css' %}">
<img src="{% static 'blog/hero.jpg' %}" alt="Post hero image">

1

{% load static %} must appear before any {% static %} tag is used in the template.

2

'blog/post.css' resolves against blog/static/blog/post.css — the app-name subfolder prevents two apps' files from colliding.

Why this works: Namespacing each app's static files under its own name (blog/static/blog/...) is what lets two different apps each ship a file literally named logo.png without one silently overwriting the other once collectstatic merges everything into one STATIC_ROOT directory.

What we're doing: Define a model that accepts an uploaded photo, and show the three ways to read back where it ended up.

from django.db import models

class Car(models.Model):
    name = models.CharField(max_length=255)
    photo = models.ImageField(upload_to="cars")
    specs = models.FileField(upload_to="specs")

5

ImageField(upload_to="cars") — Django writes uploads under MEDIA_ROOT/cars/ and validates the upload is actually an image.

6

FileField accepts any file type — use it when there's no need to validate the upload is an image specifically.

Why this works: upload_to keeps different kinds of uploads separated on disk (cars/ vs specs/) the same way an app's static/<app_name>/ namespacing keeps static files from colliding — the same organizing idea, applied to content that arrives at runtime instead of being shipped with the code.

What we're doing: Write a login view that authenticates then logs in, and a protected view guarded by login_required.

from django.contrib.auth import authenticate, login
from django.contrib.auth.decorators import login_required
from django.shortcuts import redirect, render

def login_view(request):
    if request.method == "POST":
        username = request.POST["username"]
        password = request.POST["password"]
        user = authenticate(request, username=username, password=password)
        if user is not None:
            login(request, user)
            return redirect("dashboard")
    return render(request, "login.html")

@login_required
def dashboard(request):
    return render(request, "dashboard.html", {"user": request.user})

9

authenticate() only checks the credentials — nothing about the request or session changes yet, and the return value could still be None.

10

login(request, user) is the separate call that actually attaches this user to request.session — this is the step that makes future requests see them as logged in.

15

@login_required wraps dashboard — an unauthenticated visitor is redirected to LOGIN_URL instead of ever reaching the view body.

Why this works: authenticate() and login() being two calls rather than one lets a view check credentials without necessarily starting a session — useful for anything that needs "is this password right?" without "log this person in", which login() alone commits to.

What we're doing: Use request.session to prevent the same visitor from submitting a comment twice, without requiring them to be logged in.

def post_comment(request, new_comment):
    if request.session.get("has_commented", False):
        return HttpResponse("You've already commented.")
    Comment.objects.create(text=new_comment)
    request.session["has_commented"] = True
    return HttpResponse("Thanks for your comment!")

2

request.session.get(..., False) reads with a default the same way a plain dict would — no key means "never set", treated as False.

5

Setting request.session["has_commented"] = True persists across this visitor's future requests, keyed by their session cookie.

Why this works: This works for anonymous visitors too, since a session exists independent of authentication (see authentication) — request.session is available as soon as SessionMiddleware runs, whether or not the visitor has ever logged in.

What we're doing: Queue a success message in a view right before a redirect, then render it in the template the following request loads.

from django.contrib import messages
from django.shortcuts import redirect

def update_profile(request):
    # ... save the form ...
    messages.success(request, "Profile details updated.")
    return redirect("profile")

5

messages.success() queues the message during THIS request — it is not rendered here, since a redirect follows immediately.

6

The redirect sends a fresh request to "profile", whose template is where {% for message in messages %} will actually display it.

Why this works: The redirect-then-display pattern is exactly why messages need to survive across requests in the first place — a plain context variable would be lost the instant the redirect happens, since a redirect is a brand-new request with no memory of the one before it. Messages are stored (cookie/session) specifically to bridge that gap.

What we're doing: Mark a message translatable in both Python and a template, using the same underlying gettext mechanism.

from django.utils.translation import gettext as _
from django.shortcuts import render

def homepage(request):
    greeting = _("Welcome to my site")
    return render(request, "home.html", {"greeting": greeting})

# home.html:
# {% load i18n %}
# <h1>{{ greeting }}</h1>
# <p>{% trans "Thanks for visiting." %}</p>

1

gettext as _ is the conventional alias — _("...") marks a string for extraction into a .po file.

5

The greeting is translated in Python and passed through context, while a second string is marked directly in the template via {% trans %} — both feed the same translation catalogue.

Why this works: Both mechanisms exist because a string can originate on either side of the MTV split (mtv-architecture) — some translatable text is computed in a view, some is static markup living entirely in a template — and i18n has to cover both without forcing everything through one layer.

What we're doing: Record a timestamp the correct way, then activate a per-request time zone so it displays converted for one visitor without altering the stored value.

from django.utils import timezone
import zoneinfo

def place_order(request):
    order = Order.objects.create(placed_at=timezone.now())  # stored in UTC
    return redirect("order-detail", pk=order.pk)

class TimezoneMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        tzname = request.session.get("django_timezone")
        if tzname:
            timezone.activate(zoneinfo.ZoneInfo(tzname))
        return self.get_response(request)

4

timezone.now() — the value actually saved to the database is UTC, regardless of who placed the order or from where.

8

TimezoneMiddleware activates a per-request zone for DISPLAY purposes only — it never changes what was stored in placed_at.

Why this works: Splitting "what is stored" (always UTC, via timezone.now()) from "what is displayed" (converted per-request, via timezone.activate()) is the whole point of USE_TZ = True — order.placed_at means the same instant in time everywhere, and only its on-screen rendering changes based on the active zone, matching the middleware chain's general pattern of adding per-request context.