.cursorrules (deprecated)

1# Django REST Framework — Cursor Rules
2# Comprehensive rules for building APIs with Django and DRF
3 
4## Project Context
5You are working on a Django application with Django REST Framework (DRF) for building
6APIs. The project follows Django conventions, uses class-based views, and leverages
7DRF's serialization, authentication, and permission systems. The codebase is structured
8as a collection of Django apps with clear separation of concerns.
9 
10## Tech Stack
11- Python 3.11+
12- Django 5.0+
13- Django REST Framework 3.15+
14- PostgreSQL (recommended) or SQLite for development
15- Celery for background tasks (with Redis broker)
16- django-filter for queryset filtering
17- drf-spectacular for OpenAPI schema generation
18- pytest-django for testing
19 
20## Coding Style
21 
22### Naming Conventions
23- Django apps: short snake_case nouns (e.g., `users`, `orders`, `payments`)
24- Models: PascalCase singular (e.g., `User`, `Order`, `OrderItem`)
25- Serializers: PascalCase with `Serializer` suffix (e.g., `UserSerializer`, `OrderCreateSerializer`)
26- Views/ViewSets: PascalCase with `ViewSet` or `View` suffix (e.g., `UserViewSet`, `LoginView`)
27- URL patterns: kebab-case (e.g., `/api/order-items/`, `/api/user-profiles/`)
28- Template tags: snake_case (e.g., `{% user_avatar %}`)
29- Management commands: snake_case (e.g., `sync_products`, `send_reports`)
30- Signals: past tense (e.g., `order_created`, `payment_processed`)
31 
32### Project Structure
33```
34project/
35  config/                 # Project settings
36    settings/
37      base.py
38      local.py
39      production.py
40    urls.py
41    wsgi.py
42    celery.py
43  apps/
44    users/
45      models.py
46      serializers.py
47      views.py
48      urls.py
49      admin.py
50      signals.py
51      services.py         # Business logic (not in views or models)
52      tests/
53        test_models.py
54        test_views.py
55        test_services.py
56        factories.py      # Test data factories
57    orders/
58      ...
59  common/                 # Shared utilities
60    permissions.py
61    pagination.py
62    exceptions.py
63    mixins.py
64```
65 
66## Model Patterns
67 
68### Model Definition
69```python
70from django.db import models
71from django.utils import timezone
72 
73class Order(models.Model):
74    class Status(models.TextChoices):
75        PENDING = "pending", "Pending"
76        CONFIRMED = "confirmed", "Confirmed"
77        SHIPPED = "shipped", "Shipped"
78        DELIVERED = "delivered", "Delivered"
79        CANCELLED = "cancelled", "Cancelled"
80 
81    user = models.ForeignKey("users.User", on_delete=models.CASCADE, related_name="orders")
82    status = models.CharField(max_length=20, choices=Status.choices, default=Status.PENDING)
83    total = models.DecimalField(max_digits=10, decimal_places=2)
84    created_at = models.DateTimeField(auto_now_add=True)
85    updated_at = models.DateTimeField(auto_now=True)
86 
87    class Meta:
88        ordering = ["-created_at"]
89        indexes = [
90            models.Index(fields=["user", "status"]),
91            models.Index(fields=["-created_at"]),
92        ]
93 
94    def __str__(self):
95        return f"Order #{self.pk} - {self.user}"
96 
97    @property
98    def is_cancellable(self):
99        return self.status in (self.Status.PENDING, self.Status.CONFIRMED)
100```
101 
102### Model Rules
103- Keep models focused on data structure and simple properties
104- Use `TextChoices` / `IntegerChoices` for choice fields
105- Always define `__str__`, `Meta.ordering`, and relevant indexes
106- Use `related_name` on all ForeignKey and M2M fields
107- Move complex business logic to services, not model methods
108- Use `F()` and `Q()` objects for complex queries
109- Avoid `null=True` on string fields — use `blank=True` with default `""`
110 
111## Serializer Patterns
112 
113### Separate Read/Write Serializers
114```python
115class OrderListSerializer(serializers.ModelSerializer):
116    user = UserMinimalSerializer(read_only=True)
117    status_display = serializers.CharField(source="get_status_display", read_only=True)
118 
119    class Meta:
120        model = Order
121        fields = ["id", "user", "status", "status_display", "total", "created_at"]
122 
123class OrderCreateSerializer(serializers.ModelSerializer):
124    class Meta:
125        model = Order
126        fields = ["items", "shipping_address"]
127 
128    def validate_items(self, value):
129        if not value:
130            raise serializers.ValidationError("Order must have at least one item.")
131        return value
132 
133    def create(self, validated_data):
134        # Delegate complex creation logic to a service
135        return OrderService.create_order(
136            user=self.context["request"].user,
137            **validated_data,
138        )
139```
140 
141## ViewSet Patterns
142```python
143from rest_framework import viewsets, permissions, status
144from rest_framework.decorators import action
145from rest_framework.response import Response
146from django_filters.rest_framework import DjangoFilterBackend
147 
148class OrderViewSet(viewsets.ModelViewSet):
149    permission_classes = [permissions.IsAuthenticated]
150    filter_backends = [DjangoFilterBackend, filters.OrderingFilter]
151    filterset_fields = ["status"]
152    ordering_fields = ["created_at", "total"]
153    ordering = ["-created_at"]
154 
155    def get_queryset(self):
156        return Order.objects.filter(user=self.request.user).select_related("user")
157 
158    def get_serializer_class(self):
159        if self.action == "create":
160            return OrderCreateSerializer
161        return OrderListSerializer
162 
163    @action(detail=True, methods=["post"])
164    def cancel(self, request, pk=None):
165        order = self.get_object()
166        if not order.is_cancellable:
167            return Response({"error": "Order cannot be cancelled"}, status=status.HTTP_400_BAD_REQUEST)
168        OrderService.cancel_order(order)
169        return Response(OrderListSerializer(order).data)
170```
171 
172## Service Layer Pattern
173```python
174# services.py — keep business logic out of views and models
175class OrderService:
176    @staticmethod
177    def create_order(user, items, shipping_address):
178        with transaction.atomic():
179            order = Order.objects.create(user=user, total=0, shipping_address=shipping_address)
180            total = Decimal("0")
181            for item_data in items:
182                product = Product.objects.select_for_update().get(id=item_data["product_id"])
183                if product.stock < item_data["quantity"]:
184                    raise ValidationError(f"Insufficient stock for {product.name}")
185                OrderItem.objects.create(order=order, product=product, quantity=item_data["quantity"], price=product.price)
186                product.stock -= item_data["quantity"]
187                product.save()
188                total += product.price * item_data["quantity"]
189            order.total = total
190            order.save()
191        order_created.send(sender=Order, order=order)
192        return order
193```
194 
195## Error Handling
196- Use DRF's built-in exception handling (`ValidationError`, `NotFound`, `PermissionDenied`)
197- Create custom exception handler for consistent error format
198- Use `transaction.atomic()` for operations that must be all-or-nothing
199- Return structured error responses: `{"error": "message", "code": "ERROR_CODE"}`
200- Log exceptions with full context in production
201 
202## Security
203- Always set `permission_classes` on views — never leave them open
204- Use `select_related` / `prefetch_related` to prevent N+1 (and info leaks via lazy loading)
205- Filter querysets by the authenticated user — never trust URL params alone
206- Use `@action(permission_classes=[...])` for custom action permissions
207- Validate file uploads: size, type, and content
208- Use Django's CSRF protection for session-based auth
209- Throttle API endpoints with DRF's `throttle_classes`
210 
211## Testing
212```python
213import pytest
214from rest_framework.test import APIClient
215from apps.users.tests.factories import UserFactory
216 
217@pytest.fixture
218def api_client():
219    return APIClient()
220 
221@pytest.fixture
222def authenticated_client(api_client):
223    user = UserFactory()
224    api_client.force_authenticate(user=user)
225    return api_client, user
226 
227@pytest.mark.django_db
228def test_create_order(authenticated_client):
229    client, user = authenticated_client
230    response = client.post("/api/orders/", {"items": [{"product_id": 1, "quantity": 2}]}, format="json")
231    assert response.status_code == 201
232    assert Order.objects.filter(user=user).count() == 1
233```
234 
235## Performance Guidelines
236- Use `select_related()` for ForeignKey joins, `prefetch_related()` for reverse/M2M
237- Use `only()` / `defer()` for large models when you need few fields
238- Implement cursor-based pagination for large datasets
239- Cache expensive queries with Django's cache framework
240- Use `bulk_create()` and `bulk_update()` for batch operations
241- Run slow tasks async with Celery
242- Use database indexes on filtered and ordered fields
243 
244## Common Pitfalls
245- N+1 queries from accessing related objects without `select_related`/`prefetch_related`
246- Not filtering querysets by user — returning other users' data
247- Fat views with business logic — extract to services
248- Using `ModelSerializer` for both reads and writes when they need different fields
249- Forgetting `@pytest.mark.django_db` on database tests
250- Not using `transaction.atomic()` for multi-step writes
251- Overriding `get_queryset()` but not calling `super()` when needed
252- Exposing sensitive fields (password hash, tokens) in serializers
253