User Rules for Cursor - Django Rest Framework Project

.cursorrules-django

AI Behavior
- Always verify information before presenting it. Do not make assumptions or speculate without clear evidence.
- Make changes file by file and give me a chance to spot mistakes.
- Never use apologies.
- Avoid giving feedback about understanding in comments or documentation.
- Don’t ask for confirmation of information already provided in the context.
- Don’t ask the user to verify implementations that are visible in the provided context.
- Don’t suggest updates or changes to files when there are no actual modifications needed.
- Don’t invent changes other than what's explicitly requested.
- Provide all edits in a single chunk instead of multiple-step instructions or explanations for the same file.
- Don’t summarize changes made.
- Don’t show or discuss the current implementation unless specifically requested.
- Always check the context generated file for the current file contents and implementations.
- Always provide links to the real files, not the context generated file.

Django and Django Rest Framework Best Practices

Project Structure
- Use the src-directory layout with `src/your_project/`.
- Place tests in a `tests/` directory parallel to `src/`.
- Keep configuration in `config/` or manage it through environment variables using Django settings.
- Place static files in `static/` directory.
- Use `templates/` for Jinja2 templates (or Django templates).
- Group apps logically, each with their own directories.

Code Style
- Follow PEP 8 naming conventions:
  - snake_case for functions and variables
  - PascalCase for classes
  - UPPER_CASE for constants
- Use `black` to format code.
- Use `isort` for import sorting.
- Maintain a maximum line length of 88 characters (Black default).
- Use absolute imports for clarity.

Type Hints
- Use type hints for function parameters and returns.
- Prefer `Optional[Type]` instead of `Type | None` (for Python < 3.10).
- Use `TypeVar` for generic types.
- Define custom types in a `types.py` file.
- Use `Protocol` from `typing` for duck typing where applicable.

Django REST Framework (DRF) Structure
- Use Django's factory pattern for creating apps.
- Organize views with Django Rest Framework's viewsets, serializers, and routers.
- Keep views and serializers separate for clarity.
- Use API viewsets with serializers and pagination.
- Always validate request data using DRF serializers and validation methods.
- Implement permissions with DRF's built-in or custom permissions.
- Use view decorators or mixins for common functionality (e.g., `@action` decorator, `IsAuthenticated`).

Database
- Use Django's ORM for database interactions.
- Define models in `models.py`, using clear and concise names.
- Define relationships (e.g., ForeignKey, ManyToMany) as needed.
- Use Django migrations for schema changes.
- Optimize database queries using `select_related` and `prefetch_related`.
- Add indexes on frequently queried fields.
- Use database transactions for multi-step updates.

Authentication and Authorization
- Use Django's built-in authentication system.
- For token-based authentication, use DRF's `TokenAuthentication` or JWT authentication.
- Use `django-rest-framework-simplejwt` for JWT authentication in a scalable way.
- Implement proper session management using `django.contrib.sessions`.
- Use Django's built-in permissions or create custom ones for role-based access control.
- Secure sensitive data like passwords with `bcrypt` or `pbkdf2_sha256`.

API Design
- Use DRF's `APIView` or `ModelViewSet` for standard CRUD operations.
- Define API endpoints using routers to keep the code DRY.
- Use `permissions` to control access to API endpoints.
- Handle errors properly using DRF's `ValidationError` and `ApiException`.
- Implement proper response formats (e.g., JSON) and use DRF's `Response` object.
- Use `pagination` for APIs that may return large datasets.
- Consider rate-limiting APIs for abuse prevention.
- Use HTTP status codes correctly: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), etc.

Testing
- Use Django's built-in testing tools (`TestCase`, `Client`).
- Write unit tests for each view and serializer.
- Test edge cases and error handling.
- Use `pytest-django` for advanced testing capabilities.
- Mock external APIs when necessary with `unittest.mock`.
- Write tests for model validation and query optimizations.
- Ensure high test coverage for critical components.

Error Handling
- Create custom exception classes for application-specific errors.
- Use `try-except` blocks where appropriate and log exceptions.
- Ensure all exceptions return proper HTTP status codes (e.g., 400 for validation errors, 500 for server errors).
- Use DRF's `ValidationError` for input validation.
- Log all errors in a consistent format using Django's logging framework.

Security
- Always use HTTPS in production.
- Configure CORS using `django-cors-headers` for cross-origin resource sharing.
- Sanitize all user inputs and use Django’s built-in form and model field validation.
- Use Django’s `csrf_exempt` only when absolutely necessary, and implement CSRF protection for all forms.
- Secure sensitive data using environment variables and Django’s settings.
- Use Django's built-in mechanisms for password hashing.
- Regularly update Django and dependencies to patch vulnerabilities.
- Use Django's `secure cookie` settings for sessions and cookies.

Performance
- Use Django's caching framework (`cache_page`, `django-redis`, etc.) for optimizing response times.
- Optimize database queries with `select_related`, `prefetch_related`, and database indexes.
- Use asynchronous views for IO-bound operations (e.g., `async def` in Django 3.1+).
- Use background jobs for long-running tasks (e.g., Celery or Django Q).
- Monitor application performance with Django Debug Toolbar or similar tools.
- Handle large datasets and pagination efficiently to avoid memory overloads.

Documentation
- Use docstrings following the Google-style or NumPy-style format.
- Document all public APIs and endpoints clearly.
- Keep `README.md` up to date with project information.
- Generate API documentation using tools like `drf-yasg` or `Swagger`.
- Document environment setup and dependencies clearly.

Development Workflow
- Use virtual environments (`venv`) for project isolation.
- Implement pre-commit hooks for code quality checks.
- Follow proper Git workflow and commit message conventions.
- Use `semantic versioning` for releases.
- Implement CI/CD pipelines using GitHub Actions, GitLab CI, or similar tools.
- Implement proper logging using Django's built-in `logging` framework.
- Separate development and production dependencies in `requirements-dev.txt` and `requirements.txt`.

Dependencies
- Pin dependency versions using `pip freeze` or `pyproject.toml`.
- Regularly update Django and third-party libraries.
- Check for security vulnerabilities in dependencies using `safety` or `bandit`.
- Separate production and development dependencies.