django-conventions

Django Conventions

This skill encodes the conventions used across modern Django projects (Django 4.x / 5.x). Apply alongside python-foundation:python-conventions (language idioms) and django-plugin:django-orm-patterns (model/query patterns) when implementing features.

1. Detection

Before writing code, read:

• manage.py — confirms this is a Django project.
• settings.py or settings/base.py — check DJANGO_VERSION, INSTALLED_APPS, REST_FRAMEWORK dict (DRF present?), AUTH_USER_MODEL.
• The project urls.py — understand the existing URL hierarchy and namespace conventions.
• requirements.txt or pyproject.toml — note the exact Django version and whether DRF, django-environ, django-filter, pytest-django, etc. are present.

2. Project and app layout

Prefer a dedicated apps/ directory for application modules and a config/ directory for project-level config. New apps are registered in INSTALLED_APPS using their AppConfig dotted path.

myproject/
  manage.py
  config/
    settings/
      base.py
      local.py
      production.py
    urls.py
    wsgi.py
    asgi.py
  apps/
    users/
      migrations/
      models.py
      views.py
      serializers.py
      urls.py
      admin.py
      apps.py
      signals.py
    orders/
      migrations/
      models.py
      views.py
      serializers.py
      urls.py
      admin.py
      apps.py

apps.py for each application:

from django.apps import AppConfig

class OrdersConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'apps.orders'
    verbose_name = 'Orders'

    def ready(self) -> None:
        import apps.orders.signals  # noqa: F401 — registers signal handlers

3. Settings split

Production settings must never contain DEBUG = True or a hardcoded SECRET_KEY.

# config/settings/base.py
import environ

env = environ.Env()

SECRET_KEY = env('SECRET_KEY')
DEBUG = env.bool('DEBUG', default=False)
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS')

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'corsheaders',
    'apps.users',
    'apps.orders',
]

DATABASES = {
    'default': env.db('DATABASE_URL'),
}