django

Django

Use Django when its integrated ORM, migrations, forms, templates, authentication, and admin reduce the total system; python-stack owns non-Django Python packages, CLIs, and Litestar services.

Workflow

1. Establish the framework contract: inspect the installed Django version, settings, URL configuration, apps, migrations, database, and deployment target before editing; for a new application, read bootstrap.
2. Model the domain first: keep apps cohesive, encode invariants with fields, constraints, forms, and transactions, and decide whether a custom user model is needed before the first migration.
3. Prefer Django's integrated path: start with server-rendered templates, forms, authentication, and admin; add an API framework, task backend, cache, or JavaScript layer only for a demonstrated requirement.
4. Keep control flow visible: use thin views and explicit functions for multi-step use cases; avoid signals, custom middleware, managers, or repository/service layers when ordinary Django code is clearer.
5. Choose sync deliberately: default to synchronous request and transaction code; use async only for measured concurrent I/O and verify the ASGI, middleware, ORM, connection-pooling, and transaction boundaries end to end.
6. Treat schema changes as code: review generated migrations, preserve applied migration history, test data migrations in both directions when reversible, and never infer production schema state from models alone.
7. Verify the behavior: run focused model, form, permission, view, and template tests, then the project gate; include Django system, deployment, and migration-drift checks.

uv run python manage.py check --fail-level WARNING
uv run python manage.py makemigrations --check --dry-run
uv run pytest
mise run check
mise run test

Gotchas

• Generated settings are development-only: move secrets and environment-specific values to validated inputs, default DEBUG off, and run check --deploy against production-like settings.
• User models are an early boundary: changing AUTH_USER_MODEL after tables exist is complex; make the decision before the first migrate and reference users through settings.AUTH_USER_MODEL or get_user_model().
• Async is not a blanket optimization: transactions still do not work in async mode, so keep transactional work in a synchronous function called through sync_to_async(); disable CONN_MAX_AGE under ASGI in favor of the database backend's own pooling, and never set DJANGO_ALLOW_ASYNC_UNSAFE to bypass the safety check.
• Django needs stubs to type-check: add django-stubs as a dev dependency or ty reports unresolved-attribute on Model.objects; it reads PEP 561 stubs only, so declare reverse accessors under if TYPE_CHECKING: as comments: RelatedManager[Comment] rather than suppressing the diagnostic.
• runserver is not production: choose and test a production WSGI or ASGI server only after the deployment target and concurrency model are known.