.cursorrules (deprecated)

1# Python Django 5+ with DRF — Cursor Rules
2 
3You are an expert Python developer building web applications with Django 5+ and Django REST Framework, following Django best practices.
4 
5## Code Style
6 
7- Use Python 3.11+ features where appropriate: type hints, `match` statements, `StrEnum`.
8- Type-annotate function signatures for public functions and methods. Use `django-stubs` for Django type support.
9- Use `snake_case` for functions, variables, and modules. `PascalCase` for classes. `UPPER_SNAKE_CASE` for settings.
10- Follow Django naming conventions: models are singular (`User`, `Article`), apps are plural or descriptive (`users`, `articles`).
11- Line length: 88 characters (Black default). Use Black for formatting, Ruff for linting.
12- Import order: stdlib, Django, third-party, local. Use `isort` with Django profile.
13- Prefer f-strings for string formatting.
14- Write docstrings for all models, views, and serializers explaining their purpose.
15 
16## Django Project Structure
17 
18- One app per domain concept. Keep apps focused and loosely coupled.
19- Use `apps.py` to configure app metadata and signal connections.
20- Place URL patterns in each app's `urls.py`, include them in the root `urls.py` with a namespace.
21- Use `settings/` package for environment-specific configs: `base.py`, `development.py`, `production.py`, `testing.py`.
22- Store reusable utilities in a `core` or `common` app.
23 
24## Models
25 
26- Every model gets a docstring explaining its purpose and relationships.
27- Use explicit `related_name` on all ForeignKey and ManyToManyField relationships.
28- Define `__str__` on every model — it must return a meaningful human-readable string.
29- Use `Meta` class for ordering, constraints, indexes, verbose names, and permissions.
30- Prefer `UUIDField` for public-facing primary keys. Keep auto-incrementing `id` for internal use.
31- Use `TimeStampedModel` base class with `created_at` and `updated_at` fields for all models.
32- Use Django's built-in field types. Prefer `CharField` with `max_length` over `TextField` when length is bounded.
33- Define choices as `TextChoices` or `IntegerChoices` enums on the model class.
34- Add database indexes on fields used in frequent queries: `db_index=True` or `Meta.indexes`.
35- Use `constraints` in Meta for database-level validation (UniqueConstraint, CheckConstraint).
36 
37## Views and Serializers (DRF)
38 
39- Prefer `ModelViewSet` for full CRUD. Use `GenericAPIView` + mixins for partial CRUD.
40- Use `ModelSerializer` for standard serialization. Use `Serializer` for custom input/output shapes.
41- Define `read_only_fields` in serializer Meta. Never allow users to set `id`, `created_at`, `updated_at`.
42- Use separate serializers for create, update, list, and detail when field sets differ.
43- Override `get_queryset()` to scope queries to the current user or permissions.
44- Use `select_related` and `prefetch_related` in `get_queryset` to prevent N+1 queries.
45- Use `permission_classes` on every view. Default to `IsAuthenticated` — explicitly set `AllowAny` only when needed.
46- Use `@action` decorator for custom endpoints on viewsets: `@action(detail=True, methods=['post'])`.
47- Implement pagination: use `PageNumberPagination` or `CursorPagination` for large datasets.
48- Return consistent response shapes. Use DRF's built-in response formatting.
49 
50## URL Routing
51 
52- Use DRF `DefaultRouter` for viewset URL registration.
53- Use `path()` over `re_path()` unless regex is genuinely needed.
54- Namespace all app URLs: `app_name = 'users'` and `path('users/', include('users.urls', namespace='users'))`.
55- Use `reverse()` or `reverse_lazy()` for URL generation. Never hardcode URL paths.
56- Keep URL patterns RESTful: `users/`, `users/<int:pk>/`, `users/<int:pk>/activate/`.
57 
58## ORM Best Practices
59 
60- Use `QuerySet` methods for database operations. Never write raw SQL unless absolutely necessary.
61- Chain QuerySet methods for readability: `User.objects.filter(...).select_related(...).order_by(...)`.
62- Use `F()` expressions for database-level field references in queries and updates.
63- Use `Q()` objects for complex lookups (OR conditions, negations).
64- Use `annotate()` and `aggregate()` for computed fields and summaries.
65- Use `Subquery` and `OuterRef` instead of multiple queries for correlated lookups.
66- Avoid `QuerySet.all()` without pagination or limits — always scope your queries.
67- Use `bulk_create`, `bulk_update` for batch operations. Set `batch_size` for large datasets.
68- Use `transaction.atomic()` for operations that must succeed or fail together.
69 
70## Error Handling
71 
72- Use DRF exception handling. Raise `ValidationError`, `NotFound`, `PermissionDenied` from `rest_framework.exceptions`.
73- Create custom exception classes for domain-specific errors. Register them with `EXCEPTION_HANDLER` in settings.
74- Validate at the serializer level (field validation, object validation) and the model level (`clean()` method).
75- Log all unhandled exceptions with request context. Use `structlog` or Django's logging configuration.
76- Return consistent error response format: `{"detail": "message"}` or `{"field_name": ["error messages"]}`.
77- Never expose internal error details (tracebacks, SQL queries) in API responses.
78 
79## Authentication and Permissions
80 
81- Use `django-rest-framework-simplejwt` for JWT authentication, or session auth for browser-based apps.
82- Create custom permission classes for business logic authorization. Place them in `permissions.py` per app.
83- Use object-level permissions when access depends on the specific resource (e.g., owner-only access).
84- Implement role-based access with Django groups or a custom permission model.
85 
86## Testing
87 
88- Use `pytest-django` with `pytest`. Configure in `pytest.ini` or `pyproject.toml`.
89- Use `APIClient` for DRF endpoint tests. Test each endpoint: success, validation, auth, permissions, edge cases.
90- Use `baker` (model-bakery) or `factory_boy` for test data creation. Never use fixtures for dynamic test data.
91- Use `@pytest.mark.django_db` for tests that need database access.
92- Test model methods, validators, and signals in isolation.
93- Place tests in `tests/` directory per app: `tests/test_views.py`, `tests/test_models.py`, `tests/test_serializers.py`.
94- Use `override_settings` decorator for tests that need different settings.
95 
96## File Structure
97 
98```
99project/
100  config/
101    settings/
102      base.py
103      development.py
104      production.py
105    urls.py
106    wsgi.py
107    asgi.py
108  apps/
109    core/              — Shared models, utils, base classes
110      models.py        — TimeStampedModel, etc.
111    users/
112      models.py
113      serializers.py
114      views.py
115      urls.py
116      permissions.py
117      signals.py
118      admin.py
119      tests/
120        test_views.py
121        test_models.py
122    articles/
123      models.py
124      serializers.py
125      views.py
126      urls.py
127      filters.py
128      tests/
129  manage.py
130  requirements/
131    base.txt
132    development.txt
133    production.txt
134```
135 
136## Performance
137 
138- Always use `select_related` (ForeignKey, OneToOne) and `prefetch_related` (ManyToMany, reverse FK) in querysets.
139- Use Django Debug Toolbar in development to catch N+1 queries.
140- Cache expensive computations with Django's cache framework. Use `@cache_page` for view caching.
141- Use database indexes for frequently filtered and ordered fields.
142- Use `defer()` and `only()` to limit fields loaded from the database when you don't need all columns.
143- Paginate all list endpoints. Never return unbounded querysets.
144 
145## Security
146 
147- Keep `SECRET_KEY` in environment variables. Never commit it to version control.
148- Set `ALLOWED_HOSTS` explicitly in production. Never use `['*']`.
149- Use Django's CSRF protection. Do not disable it for API endpoints served to browsers.
150- Enable security middleware: `SecurityMiddleware`, HSTS, content type sniffing protection.
151- Validate and sanitize all user input through serializers. Escape output in templates.
152- Use `SECURE_SSL_REDIRECT = True` in production.
153- Regularly update Django and all dependencies for security patches.
154