Django

---
name: django
description: Best practices for Django web development including models, views, templates, and testing.
---

# Skill: Django

Best practices for Django web development including models, views, templates, and testing.

## When to Use

Apply this skill when working with Django projects — models, views, URL routing, templates, forms, admin, and management commands.

## Project Structure

-   Follow the standard Django app layout: `models.py`, `views.py`, `urls.py`, `admin.py`, `tests.py`, `forms.py`.
-   Keep each app focused on a single domain concept; avoid "god apps" with unrelated models.
-   Use `settings/base.py`, `settings/dev.py`, `settings/prod.py` for environment-specific configuration.

## Models

-   Always define `__str__` on models for admin and debugging readability.
-   Use `Meta.ordering` sparingly — it adds `ORDER BY` to every query. Prefer explicit `.order_by()` on querysets.
-   Use database indexes (`db_index=True`, `Meta.indexes`) for fields that appear in `filter()` / `order_by()`.
-   Prefer `CharField` with `choices` (or `TextChoices` / `IntegerChoices`) over bare strings for constrained fields.
-   Use `F()` expressions and `Q()` objects for complex queries to avoid race conditions and improve readability.

## Views

-   Prefer class-based views (CBVs) for CRUD; prefer function-based views for one-off logic.
-   Always explicitly set `queryset` or override `get_queryset()` — never rely on mutable class-level state.
-   Use `select_related()` and `prefetch_related()` to avoid N+1 query problems.
-   Set `LOGIN_URL` and use `@login_required` / `LoginRequiredMixin` consistently.

## Testing

-   Use `pytest-django` with `@pytest.mark.django_db` for database access.
-   Prefer `TestCase` or `TransactionTestCase` only when explicit transaction control is needed; otherwise use pytest fixtures.
-   Use `RequestFactory` or `Client` to test views without starting a server.
-   Use `baker.make()` (model-bakery) or factories instead of manual model construction in tests.

## Pitfalls

-   Never do blocking I/O in async views without wrapping in `sync_to_async`.
-   Avoid importing models at module level in `settings.py` or `urls.py` (circular imports).
-   Never store secrets in `settings.py` — use environment variables.
-   Avoid raw SQL unless the ORM genuinely cannot express the query.