django

name	django
description	[Applies to: **/*.py] Definitive guidelines for writing maintainable, performant, and secure Django applications, emphasizing modern best practices, clear code organization, and efficient patterns.
source	cursor_mdc

django Best Practices

This guide outlines the definitive best practices for developing Django applications, ensuring maintainability, performance, and security. Adhere to these rules for consistent, high-quality code.

1. Code Organization & Project Structure

Adopt the src-layout for clear separation of concerns. Keep apps focused on a single domain.

• Project Layout (src-layout):

  .
  ├── manage.py
  ├── src/
  │   ├── config/             # Project-level settings, URLs, WSGI/ASGI
  │   │   ├── __init__.py
  │   │   ├── settings/
  │   │   │   ├── __init__.py
  │   │   │   ├── base.py
  │   │   │   ├── development.py
  │   │   │   └── production.py
  │   │   └── urls.py
  │   ├── apps/               # Domain-driven Django apps
  │   │   ├── users/
  │   │   │   ├── models.py
  │   │   │   ├── views.py
  │   │   │   └── tests/
  │   │   ├── products/
  │   │   └── ...
  │   └── common/             # Reusable utilities, abstract base models, etc.
  └── requirements.txt
  

• Split Settings: Use django-environ for environment-specific settings. Never commit secrets.

  ❌ BAD: Hardcoding secrets, single settings.py

  # config/settings.py
  DEBUG = True
  SECRET_KEY = 'super-secret-dev-key'
  DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': BASE_DIR / 'db.sqlite3'}}
  

  ✅ GOOD: Environment variables, split files

  # src/config/settings/base.py
  import environ
  env = environ.Env()
  environ.Env.read_env() # reads .env file
  
  SECRET_KEY = env('SECRET_KEY')
  DEBUG = env.bool('DEBUG', default=False)
  ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=[])
  
  # src/config/settings/development.py
  from .base import *
  DEBUG = True
  DATABASES = {'default': env.db('DATABASE_URL', default='sqlite:///db.sqlite3')}
  
  # .env file (not committed to VCS)
  SECRET_KEY=your_actual_secret_key
  DEBUG=True
  DATABASE_URL=postgres://user:pass@host:port/dbname
  

• Model Naming: Models are singular nouns. related_name for reverse relationships is plural.

  ❌ BAD:

  class Users(models.Model): pass
  owner = models.ForeignKey(Owner, related_name='item')
  

  ✅ GOOD:

  class User(models.Model): pass
  owner = models.ForeignKey(Owner, related_name='items', on_delete=models.CASCADE)
  

2. Common Patterns & Anti-patterns

• Fat Models, Skinny Views: Business logic belongs in models or dedicated service layers, not views. Views orchestrate, models/services execute.

  ❌ BAD: Logic in view

  # apps/orders/views.py
  def create_order_view(request):
      # ... validation ...
      product = Product.objects.get(id=product_id)
      if product.stock < quantity:
          raise ValidationError("Not enough stock")
      order = Order.objects.create(user=request.user, product=product, quantity=quantity)
      product.stock -= quantity
      product.save()
      # ...
  

  ✅ GOOD: Logic in model/service

  # apps/orders/models.py
  class Order(models.Model):
      # ... fields ...
      @classmethod
      def create_with_stock_check(cls, user, product, quantity):
          if product.stock < quantity:
              raise ValidationError("Not enough stock")
          order = cls.objects.create(user=user, product=product, quantity=quantity)
          product.stock -= quantity
          product.save()
          return order
  
  # apps/orders/views.py
  def create_order_view(request):
      # ... validation ...
      order = Order.create_with_stock_check(request.user, product, quantity)
      # ...
  

3. Performance Considerations

• Optimize ORM Queries: Avoid N+1 queries.

  ❌ BAD: N+1 query

  # Iterates over users, then queries profile for each
  users = User.objects.all()
  for user in users:
      print(user.profile.bio)
  

  ✅ GOOD: select_related (one-to-one, foreign key)

  users = User.objects.select_related('profile').all()
  for user in users:
      print(user.profile.bio)
  

  ✅ GOOD: prefetch_related (many-to-many, reverse foreign key)

  # For a list of books, prefetch all authors for each book
  books = Book.objects.prefetch_related('authors').all()
  for book in books:
      print([author.name for author in book.authors.all()])
  

• Database Indexes: Add db_index=True to frequently filtered/ordered fields.

  class MyModel(models.Model):
      name = models.CharField(max_length=100, db_index=True) # Indexed
      created_at = models.DateTimeField(auto_now_add=True, db_index=True)
  

• Async ORM: Use sync_to_async for blocking ORM calls in async views, or the native async ORM (Django 4.1+).

  # In an async view
  from asgiref.sync import sync_to_async
  
  async def ():
      
      user =  sync_to_async(User.objects.get)(=request.user.)
      
      
       JsonResponse({: user.username})
  

4. Security Best Practices

• Secrets Management: Never commit secrets to VCS. Use environment variables (see Split Settings).

• Permissions (DRF): Implement role-based permissions using DRF's permission_classes.

  ❌ BAD: Manual checks in view

  class MyView(APIView):
      def get(self, request):
          if not request.user.is_staff:
              return Response(status=403)
          # ...
  

  ✅ GOOD: DRF Permission Classes

  from rest_framework.permissions import IsAdminUser
  
  class MyView(APIView):
      permission_classes = [IsAdminUser] # Only staff can access
      def get(self, request):
          # ...
  

• Static & Media Files: Serve static files with ManifestStaticFilesStorage and media files from cloud storage (e.g., S3, GCS).

  # config/settings/production.py
  STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
  DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage' # e.g., django-storages
  

5. API Design (DRF)

• ViewSets & Routers: Use ModelViewSet for CRUD operations to reduce boilerplate.

  ❌ BAD: Separate views for list and detail

  class ProductListView(APIView): pass
  class ProductDetailView(APIView): pass
  # urls.py: path('products/', ProductListView.as_view()), path('products/<int:pk>/', ProductDetailView.as_view())
  

  ✅ GOOD: ModelViewSet with Router

  # apps/products/views.py
  from rest_framework import viewsets
  from .models import Product
  from .serializers import ProductSerializer
  
  class ProductViewSet(viewsets.ModelViewSet):
      queryset = Product.objects.all()
      serializer_class = ProductSerializer
  
  # src/config/urls.py
  from rest_framework.routers import DefaultRouter
  from apps.products.views import ProductViewSet
  
  router = DefaultRouter()
  router.register(r'products', ProductViewSet)
  urlpatterns = [
      # ...
      path('api/', include(router.urls)),
  ]
  

6. Type Hints

Always use type hints for improved readability, maintainability, and static analysis with mypy.

❌ BAD: Untyped function

def calculate_total(price, quantity):
    return price * quantity

✅ GOOD: Typed function

def calculate_total(price: float, quantity: int) -> float:
    return price * quantity

# For models:
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from django.db.models import QuerySet

class Product(models.Model):
    name: str = models.CharField(max_length=255)
    price: float = models.DecimalField(max_digits=10, decimal_places=2)

    def get_related_products(self) -> "QuerySet[Product]":
        # ...
        return Product.objects.filter(...)