django-pro

Overview

Django is Python's batteries-included web framework: ORM, admin, auth, migrations, and templating ship together with a strong opinion about project layout. That completeness is its superpower — teams move fast without assembling a stack — and its trap, when projects fight the framework instead of using it. This skill covers the Django way done well: fat models, thin views, the ORM's query behavior, and what to configure before going live.

When to use

• Building a full-stack Python web app or admin-backed API.
• Taming N+1 queries, slow ORM queries, or migration pain.
• Structuring a growing Django project (apps, settings, services).
• Hardening Django for production (security settings, static files, DB).
• Deciding between Django, DRF, FastAPI, or Rails-style frameworks.
• Customizing the Django admin for internal tooling.
• Adding caching or async views to an existing Django app.

Core concepts

• MTV and the request path. URLconf → view → template/response. Keep views thin: parse input, call domain logic, return a response. Business rules belong in models, managers, or service modules — not in views.
• The ORM is a query builder. QuerySets are lazy; nothing hits the DB until evaluated. Learn select_related (FK joins) and prefetch_related (M2M/reverse FK) — they eliminate the N+1 queries that sink Django apps. Use .only()/.defer() and .values() to slim wide tables.
• Migrations are code. Never edit a migration that's been applied anywhere shared; write new ones. Use sqlmigrate to inspect generated SQL, keep migrations small and reversible, and run them with zero-downtime patterns (add nullable column → backfill → add constraint).
• Apps are boundaries. Split by domain (billing, users, orders), not by technical layer. Each app owns its models, views, and templates. Cross-app imports signal a missing shared app or a boundary violation.
• Settings per environment. One settings.py with environment overrides beats copy-pasted files. Validate required env vars at startup (django-environ or similar); fail fast on missing secrets.
• Auth and admin. Django's auth (users, groups, permissions, sessions) plus the auto-generated admin cover most back-office needs. Customize the admin per model (list_display, list_filter, search_fields) — an unconfigured admin is both slow and dangerous.
• Async support is partial. Async views and ORM methods exist, but much of Django (middleware, ORM internals) still runs sync. Use async for I/O-bound views with async-compatible libraries; don't expect Node-style throughput from a sync stack.
• Managers and QuerySets. Custom managers (objects = OrderManager()) encapsulate query logic so views stay dumb; chainable QuerySet methods compose. Put "how we query X" in exactly one place.
• Signals. post_save/m2m_changed decouple side effects — and create invisible coupling when overused. Prefer explicit service calls; reserve signals for cross-app concerns (audit logs, cache invalidation).
• Caching framework. Per-view, template-fragment, and low-level caching with Redis/Memcached backends. Cache the expensive, invalidate deliberately — stale caches are a correctness bug, not a performance feature.
• Testing tools. Django's TestCase wraps each test in a transaction with fast rollback; use SimpleTestCase for non-DB tests. Prefer factories (factory_boy) over brittle JSON fixtures for test data.
• Don't reimplement contrib. Sessions, flash messages, pagination, sitemaps, humanize — check django.contrib before adding a dependency; it's maintained and already installed.

Practical workflow

1. Scaffold cleanly. django-admin startproject config . (project package named config, not the app name), then one app per domain. Split settings: settings/base.py, settings/prod.py.

2. Model the domain. Write models with managers/querysets encapsulating query logic; add indexes for every filtered/ordered field (db_index, Meta.indexes); prefer DecimalField for money, DateTimeField with timezone support on.

   class Order(models.Model):
       customer = models.ForeignKey(Customer, on_delete=models.PROTECT, related_name="orders")
       status = models.CharField(max_length=20, choices=Status.choices, db_index=True)
       total = models.DecimalField(max_digits=10, decimal_places=2)
       created_at = models.DateTimeField(auto_now_add=True, db_index=True)
       class Meta:
           indexes = [models.Index(fields=["customer", "-created_at"])]
   

3. Build views + serializers. For APIs use DRF or Ninja; validate input with serializers, paginate every list endpoint, and throttle public ones.

   • Use ModelViewSet judiciously — explicit APIViews are clearer for non-CRUD behavior.

4. Audit queries. Install django-debug-toolbar in dev; in CI, assert query counts on hot endpoints (assertNumQueries). Fix N+1s with select_related/prefetch_related before they ship.

5. Harden settings for prod. DEBUG=False, ALLOWED_HOSTS set, SECURE_SSL_REDIRECT, SESSION_COOKIE_SECURE, CSRF_COOKIE_SECURE, SECURE_HSTS_SECONDS; static files via WhiteNoise or a CDN; media on object storage, never local disk.

   • Run python manage.py check --deploy — Django's own production checklist catches the common misses.

6. Configure the admin. list_display, list_filter, search_fields, readonly_fields for audit columns; override get_queryset with select_related for list pages; restrict sensitive models with custom permissions.

7. Add caching where it pays. Cache expensive querysets and rendered fragments; version cache keys on deploy; monitor hit rates — an unused cache is just complexity.

8. Deploy. Gunicorn/uvicorn workers behind a reverse proxy; run migrations as a separate deploy step (not in the web process); collect static at build time; back up the DB before migrating.

   # settings/prod.py essentials
   DEBUG = False
   ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")
   SECURE_HSTS_SECONDS = 31_536_000
   SECURE_SSL_REDIRECT = True
   SESSION_COOKIE_SECURE = CSRF_COOKIE_SECURE = True
   

Common pitfalls

• N+1 queries from template loops and serializer nesting — the #1 Django performance bug; profile query counts, not just wall time.
• Fat views, anemic models — logic scattered across views becomes untestable; push it into models/managers/services.
• Editing applied migrations — corrupts every environment's migration state; always add a new migration.
• DEBUG=True in production — leaks tracebacks, env details, and enables the debug toolbar attack surface.
• Naive datetimes — set USE_TZ=True and store UTC; convert at the presentation edge only.
• Unbounded querysets in admin/list views — paginate everything; a missing paginator on a million-row table is an outage.
• Running migrations inside web dynos — concurrent migrates race; run once per deploy from a dedicated step.
• Signal spaghetti — side effects hidden in signals firing in surprising order; prefer explicit calls.
• Unindexed foreign keys on large tables — joins and cascading checks slow to a crawl; index FKs and filtered columns.
• Storing uploads on local disk — doesn't survive multi-server deploys; use object storage via django-storages.
• Evaluating querysets repeatedly — re-evaluating the same queryset in a loop instead of caching it in a variable; evaluate once, reuse the list.
• Ignoring CONN_MAX_AGE — opening a new DB connection per request adds latency; use persistent connections plus a pooler (PgBouncer) in production.
• Fixture-based tests rotting — giant JSON fixtures that break on every model change; factories express intent and survive refactors.