--- name: django description: | Django batteries-included Python framework. Covers models, views, templates, ORM, and admin. Use when building full-featured Python web applications. USE WHEN: user mentions "django", "django orm", "django admin", "django templates", asks about "python cms", "django rest framework", "drf", "django models", "django migrations", "django channels", "django forms" DO NOT USE FOR: FastAPI projects - use `fastapi` instead, Flask projects - use `flask` instead, async-first Python APIs, microservices without admin panel allowed-tools: Read, Grep, Glob, Write, Edit --- # Django Core Knowledge > **Full Reference**: See [advanced.md](advanced.md) for Django Channels setup, WebSocket consumers, JWT authentication middleware, broadcasting from views, room management, and WebSocket testing. > **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `django` for comprehensive documentation. ## Model Definition ```python from django.db import models class User(models.Model): name = models.CharField(max_length=100) email = models.EmailField(unique=True) created_at = models.DateTimeField(auto_now_add=True) is_active = models.BooleanField(default=True) class Meta: ordering = ['-created_at'] def __str__(self): return self.name ``` ## Views (Class-Based) ```python from django.views.generic import ListView, DetailView, CreateView from django.urls import reverse_lazy class UserListView(ListView): model = User template_name = 'users/list.html' context_object_name = 'users' paginate_by = 20 class UserDetailView(DetailView): model = User template_name = 'users/detail.html' class UserCreateView(CreateView): model = User fields = ['name', 'email'] success_url = reverse_lazy('user-list') ``` ## Django REST Framework ```python from rest_framework import viewsets, serializers class UserSerializer(serializers.ModelSerializer): class Meta: model = User fields = ['id', 'name', 'email', 'created_at'] class UserViewSet(viewsets.ModelViewSet): queryset = User.objects.all() serializer_class = UserSerializer ``` ## Key Commands ```bash python manage.py makemigrations python manage.py migrate python manage.py createsuperuser python manage.py runserver ``` ## Project Structure ``` myproject/ ├── manage.py ├── myproject/ │ ├── settings.py │ ├── urls.py │ └── wsgi.py └── users/ ├── models.py ├── views.py ├── urls.py └── admin.py ``` ## When NOT to Use This Skill - **FastAPI projects** - FastAPI is async-first with automatic OpenAPI docs - **Flask microservices** - Django is heavyweight for simple APIs - **Non-Python backends** - Use language-appropriate frameworks - **Real-time only apps** - Consider Node.js or Go for WebSocket-heavy apps - **Serverless functions** - Django startup time is too slow ## Anti-Patterns | Anti-Pattern | Why It's Bad | Solution | |--------------|--------------|----------| | N+1 queries | Slow performance | Use `select_related()` and `prefetch_related()` | | No index on frequently queried fields | Slow queries | Add `db_index=True` to model fields | | Using `.filter()` in loops | Multiple DB hits | Use `.filter(id__in=list)` | | Storing sensitive data in settings.py | Security risk | Use environment variables | | Missing CSRF protection | XSS vulnerability | Keep `CsrfViewMiddleware` enabled | | Fat models | Hard to test | Move business logic to services | ## Quick Troubleshooting | Problem | Diagnosis | Fix | |---------|-----------|-----| | "No such table" error | Migrations not applied | Run `python manage.py migrate` | | Static files not loading | STATIC_URL misconfigured | Run `collectstatic` in production | | CSRF verification failed | Missing CSRF token | Add `{% csrf_token %}` to forms | | "OperationalError: database is locked" | SQLite concurrency | Use PostgreSQL in production | | Circular import errors | Models importing each other | Use `get_model()` or string references | | Slow admin interface | No list_select_related | Add `list_select_related` to ModelAdmin | ## Production Readiness ### Security Configuration ```python # settings/production.py DEBUG = False ALLOWED_HOSTS = env.list('ALLOWED_HOSTS') SECRET_KEY = env('SECRET_KEY') # Security headers SECURE_SSL_REDIRECT = True SECURE_HSTS_SECONDS = 31536000 SECURE_HSTS_INCLUDE_SUBDOMAINS = True SECURE_CONTENT_TYPE_NOSNIFF = True X_FRAME_OPTIONS = 'DENY' # Session security SESSION_COOKIE_SECURE = True SESSION_COOKIE_HTTPONLY = True CSRF_COOKIE_SECURE = True ``` ### Caching ```python CACHES = { 'default': { 'BACKEND': 'django.core.cache.backends.redis.RedisCache', 'LOCATION': env('REDIS_URL'), } } # Usage from django.views.decorators.cache import cache_page @cache_page(60 * 15) # 15 minutes def my_view(request): ... ``` ### Health Checks ```python from django.http import JsonResponse from django.db import connection def health_check(request): return JsonResponse({'status': 'healthy'}) def ready_check(request): try: connection.ensure_connection() return JsonResponse({'status': 'ready', 'database': 'connected'}) except Exception as e: return JsonResponse({'status': 'not ready', 'error': str(e)}, status=503) ``` ### Gunicorn Configuration ```python # gunicorn.conf.py import multiprocessing workers = multiprocessing.cpu_count() * 2 + 1 worker_class = 'uvicorn.workers.UvicornWorker' # For async bind = '0.0.0.0:8000' max_requests = 1000 timeout = 30 ``` ### Testing ```python import pytest from django.test import Client @pytest.fixture def authenticated_client(django_user_model): user = django_user_model.objects.create_user( username='test', password='test123' ) client = Client() client.force_login(user) return client @pytest.mark.django_db class TestUserAPI: def test_create_user(self, api_client): response = api_client.post('/api/users/', { 'name': 'John', 'email': 'john@example.com' }, content_type='application/json') assert response.status_code == 201 ``` ### Monitoring Metrics | Metric | Target | |--------|--------| | Response time (p99) | < 200ms | | Error rate (5xx) | < 0.1% | | Database connections | < pool size | | Cache hit ratio | > 80% | ### Checklist - [ ] DEBUG=False in production - [ ] Security headers enabled - [ ] HTTPS enforced (SSL redirect) - [ ] Database connection pooling - [ ] Redis caching configured - [ ] Structured JSON logging - [ ] Health/readiness endpoints - [ ] Gunicorn with workers - [ ] Static files on CDN - [ ] pytest with fixtures ## Reference Documentation - [Models & ORM](quick-ref/models.md) - [Views Patterns](quick-ref/views.md)