Opinionated Django development toolkit with Ninja API, Unfold admin, pytest, Dynaconf, uv, and Docker patterns

version
1.0.0
GitHub stars
16

Install

/plugin install django-dev@bershadsky-claude-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sergio-bershadsky/ai.

Contents

Discovered from source

Skills 4

Django Ninja API Development

Opinionated Django Ninja patterns with single-endpoint-per-file organization.

Core Principles

  1. One endpoint = one file - Each endpoint lives in its own file
  2. Logical grouping - Endpoints grouped in subpackages by domain
  3. Router per group - Each group has its own router
  4. Schemas in separate package - Pydantic models in schemas/
  5. Services for logic - Business logic in services, not endpoints

API Structure

myapp/
├── api/
│   ├── __init__.py           # Main NinjaAPI instance
│   ├── users/
│   │   ├── __init__.py       # Router: users_router
│   │   ├── list.py           # GET /users/
│   │   ├── detail.py         # GET /users/{id}
│   │   ├── create.py         # POST /users/
│   │   ├── update.py         # PUT /users/{id}
│   │   └── delete.py         # DELETE /users/{id}
│   ├── products/
│   │   ├── __init__.py
│   │   ├── list.py
│   │   ├── detail.py
│   │   └── search.py
│   └── auth/
│       ├── __init__.py
│       ├── login.py
│       ├── logout.py
│       └── refresh.py
└── schemas/
    ├── __init__.py
    ├── user.py               # UserIn, UserOut, UserPatch
    ├── product.py
    └── common.py             # Pagination, errors

Main API Setup

In api/__init__.py:

from ninja import NinjaAPI
from ninja.security import HttpBearer

from .users import router as users_router
from .products import router as products_router
from .auth import router as auth_router


class AuthBearer(HttpBearer):
    def authenticate(self, request, token):
        # Token validation logic
        from ..services.auth import AuthService
        return AuthService.validate_token(token)


api = NinjaAPI(
    title="My API",
    version="1.0.0",
    description="API documentation",
    auth=AuthBearer(),
)

# Register routers
api.add_router("/users", users_router, tags=["Users"])
api.add_router("/products", products_router, tags=["Products"])
api.add_router("/auth", auth_router, tags=["Authentication"], auth=None)

Router Setup

Each group has a router in __init__.py:

# api/users/__init__.py
from ninja import Router

from .list import router as list_router
from .detail import router as detail_router
from .create import router as create_router
from .update import router as update_router
from .delete import router as delete_router

router = Router()

# Merge endpoint routers
router.add_router("", list_router)
router.add_router("", detail_router)
router.add_router("", create_router)
router.add_router("", update_router)
router.add_router("", delete_router)

Endpoint File Template

Each endpoint in its own file:

# api/users/create.py
from ninja import Router
from django.http import HttpRequest

from ...schemas.user import UserIn, UserOut
from ...services.user import UserService

router = Router()


@router.post("/", response={201: UserOut})
def create_user(request: HttpRequest, payload: UserIn) -> UserOut:
    """Create a new user."""
    user = UserService.create(payload)
    return user

Schema Organization

Pydantic schemas in schemas/ package:

# schemas/user.py
from uuid import UUID
from datetime import datetime
from pydantic import BaseModel, EmailStr, Field


class UserBase(BaseModel):
    """Shared user fields."""
    email: EmailStr
    name: str = Field(max_length=255)


class UserIn(UserBase):
    """Input schema for creating users."""
    password: str = Field(min_length=8)


class UserPatch(BaseModel):
    """Partial update schema."""
    email: EmailStr | None = None
    name: str | None = Field(None, max_length=255)


class UserOut(UserBase):
    """Output schema for users."""
    id: UUID
    is_active: bool
    created_at: datetime

    class Config:
        from_attributes = True

Common Patterns

Pagination

# schemas/common.py
from typing import Generic, TypeVar, List
from pydantic import BaseModel

T = TypeVar("T")


class PaginatedResponse(BaseModel, Generic[T]):
    items: List[T]
    total: int
    page: int
    per_page: int
    pages: int
# api/users/list.py
from ninja import Router, Query
from ...schemas.user import UserOut
from ...schemas.common import PaginatedResponse

router = Router()


@router.get("/", response=PaginatedResponse[UserOut])
def list_users(
    request,
    page: int = Query(1, ge=1),
    per_page: int = Query(20, ge=1, le=100),
):
    """List users with pagination."""
    from ...services.user import UserService
    return UserService.list_paginated(page, per_page)

Error Handling

# schemas/common.py
class ErrorResponse(BaseModel):
    detail: str
    code: str | None = None


class ValidationErrorResponse(BaseModel):
    detail: list[dict]
# api/users/detail.py
from ninja import Router
from django.http import Http404
from ...schemas.user import UserOut
from ...schemas.common import ErrorResponse

router = Router()


@router.get("/{user_id}", response={200: UserOut, 404: ErrorResponse})
def get_user(request, user_id: UUID):
    """Get user by ID."""
    from ...services.user import UserService

    user = UserService.get_by_id(user_id)
    if not user:
        return 404, {"detail": "User not found", "code": "USER_NOT_FOUND"}
    return user

File Upload

# api/files/upload.py
from ninja import Router, File, UploadedFile
from ...schemas.file import FileOut

router = Router()


@router.post("/upload", response=FileOut)
def upload_file(request, file: UploadedFile = File(...)):
    """Upload a file."""
    from ...services.file import FileService
    return FileService.save(file)

URL Configuration

Register API in urls.py:

# config/urls.py
from django.urls import path
from apps.myapp.api import api

urlpatterns = [
    path("api/", api.urls),
]

Authentication Patterns

See references/endpoints.md for detailed authentication patterns including:

  • JWT authentication
  • API key authentication
  • Session authentication
  • Permission decorators

Additional Resources

Reference Files

  • references/endpoints.md - Detailed endpoint patterns, authentication, permissions
  • references/routers.md - Router organization, versioning, OpenAPI customization

Related Skills

  • django-dev - Core Django patterns and model organization
  • django-dev-test - Testing API endpoints with pytest

Django Testing Patterns

pytest-django testing with factory_boy for fixture management.

Core Principles

  1. pytest only - Never use Django's TestCase
  2. factory_boy - Use factories for all test data
  3. Mirror structure - Tests mirror app structure
  4. Isolation - Each test fully isolated
  5. Fast fixtures - Prefer @pytest.fixture over setUp

Installation

pip install pytest pytest-django factory-boy pytest-cov

Configuration

pytest.ini or pyproject.toml:

# pyproject.toml
[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "config.settings"
python_files = ["test_*.py", "*_test.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = [
    "--strict-markers",
    "-ra",
    "--tb=short",
]
markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
]

Test Structure

tests/
├── conftest.py              # Shared fixtures
├── factories/
│   ├── __init__.py
│   ├── user.py              # UserFactory
│   ├── product.py           # ProductFactory
│   └── order.py             # OrderFactory
├── unit/
│   ├── models/
│   │   ├── test_user.py
│   │   └── test_product.py
│   └── services/
│       └── test_user_service.py
├── integration/
│   └── api/
│       ├── test_users.py
│       └── test_products.py
└── e2e/
    └── test_checkout.py

Conftest Setup

tests/conftest.py:

import pytest
from django.test import Client
from ninja.testing import TestClient

from apps.myapp.api import api


@pytest.fixture
def client():
    """Django test client."""
    return Client()


@pytest.fixture
def api_client():
    """Django Ninja test client."""
    return TestClient(api)


@pytest.fixture
def authenticated_client(api_client, user):
    """API client with authentication."""
    api_client.headers["Authorization"] = f"Bearer {user.get_token()}"
    return api_client


@pytest.fixture
def user(user_factory):
    """Default test user."""
    return user_factory()


@pytest.fixture
def admin_user(user_factory):
    """Admin test user."""
    return user_factory(is_staff=True, is_superuser=True)

Factory Pattern

Base factory in factories/__init__.py:

import factory
from factory.django import DjangoModelFactory


class BaseFactory(DjangoModelFactory):
    """Base factory with common patterns."""

    class Meta:
        abstract = True

    @classmethod
    def _create(cls, model_class, *args, **kwargs):
        """Override to handle soft-deleted models."""
        obj = super()._create(model_class, *args, **kwargs)
        return obj

User factory in factories/user.py:

import factory
from factory import fuzzy
from apps.users.models import User
from . import BaseFactory


class UserFactory(BaseFactory):
    """Factory for User model."""

    class Meta:
        model = User
        skip_postgeneration_save = True

    email = factory.LazyAttribute(
        lambda obj: f"{obj.name.lower().replace(' ', '.')}@example.com"
    )
    name = factory.Faker("name")
    is_active = True

    @factory.post_generation
    def password(obj, create, extracted, **kwargs):
        password = extracted or "testpass123"
        obj.set_password(password)
        if create:
            obj.save(update_fields=["password"])

    @classmethod
    def _create(cls, model_class, *args, **kwargs):
        """Create with explicit password handling."""
        password = kwargs.pop("password", None)
        user = super()._create(model_class, *args, **kwargs)
        if password:
            user.set_password(password)
            user.save(update_fields=["password"])
        return user

Order factory with relationships (factories/order.py):

import factory
from decimal import Decimal
from apps.orders.models import Order, OrderItem
from . import BaseFactory
from .user import UserFactory
from .product import ProductFactory


class OrderFactory(BaseFactory):
    """Factory for Order model."""

    class Meta:
        model = Order

    user = factory.SubFactory(UserFactory)
    status = "pending"
    total = factory.LazyAttribute(lambda obj: Decimal("0.00"))

    @factory.post_generation
    def items(obj, create, extracted, **kwargs):
        if not create:
            return

        if extracted:
            for item in extracted:
                OrderItemFactory(order=obj, **item)
        else:
            # Create 1-3 random items
            import random
            for _ in range(random.randint(1, 3)):
                OrderItemFactory(order=obj)

        # Update total
        obj.total = sum(item.subtotal for item in obj.items.all())
        obj.save(update_fields=["total"])


class OrderItemFactory(BaseFactory):
    """Factory for OrderItem model."""

    class Meta:
        model = OrderItem

    order = factory.SubFactory(OrderFactory)
    product = factory.SubFactory(ProductFactory)
    quantity = factory.fuzzy.FuzzyInteger(1, 5)
    unit_price = factory.LazyAttribute(lambda obj: obj.product.price)

Register Fixtures

In conftest.py:

from tests.factories.user import UserFactory
from tests.factories.product import ProductFactory
from tests.factories.order import OrderFactory


@pytest.fixture
def user_factory():
    return UserFactory


@pytest.fixture
def product_factory():
    return ProductFactory


@pytest.fixture
def order_factory():
    return OrderFactory

Test Patterns

Model Tests

# tests/unit/models/test_user.py
import pytest
from apps.users.models import User


@pytest.mark.django_db
class TestUserModel:
    def test_create_user(self, user_factory):
        user = user_factory(email="test@example.com", name="Test User")

        assert user.email == "test@example.com"
        assert user.name == "Test User"
        assert user.is_active is True
        assert user.id is not None

    def test_soft_delete(self, user_factory):
        user = user_factory()
        user.delete()

        assert user.is_deleted is True
        assert User.objects.filter(id=user.id).exists()

    def test_display_name(self, user_factory):
        user = user_factory(name="John Doe")
        assert user.display_name == "John Doe"

        user_no_name = user_factory(name="", email="jane@example.com")
        assert user_no_name.display_name == "jane"

Service Tests

# tests/unit/services/test_user_service.py
import pytest
from unittest.mock import patch, MagicMock
from apps.users.services import UserService


@pytest.mark.django_db
class TestUserService:
    def test_create_user(self, user_factory):
        user = UserService.create(
            email="new@example.com",
            name="New User",
            password="securepass123",
        )

        assert user.email == "new@example.com"
        assert user.check_password("securepass123")

    def test_create_user_duplicate_email(self, user_factory):
        user_factory(email="existing@example.com")

        with pytest.raises(ValueError, match="already registered"):
            UserService.create(
                email="existing@example.com",
                name="Another User",
                password="password123",
            )

    @patch("apps.users.services.email.send_welcome_email")
    def test_create_user_sends_email(self, mock_send, user_factory):
        user = UserService.create(
            email="new@example.com",
            name="New User",
            password="password123",
        )

        mock_send.assert_called_once_with(user)

API Tests

# tests/integration/api/test_users.py
import pytest


@pytest.mark.django_db
class TestUsersAPI:
    def test_list_users_requires_auth(self, api_client):
        response = api_client.get("/users/")
        assert response.status_code == 401

    def test_list_users(self, authenticated_client, user_factory):
        user_factory.create_batch(5)

        response = authenticated_client.get("/users/")

        assert response.status_code == 200
        data = response.json()
        assert len(data["items"]) >= 5

    def test_create_user(self, authenticated_client):
        response = authenticated_client.post("/users/", json={
            "email": "new@example.com",
            "name": "New User",
            "password": "securepass123",
        })

        assert response.status_code == 201
        assert response.json()["email"] == "new@example.com"

    def test_get_user(self, authenticated_client, user_factory):
        user = user_factory()

        response = authenticated_client.get(f"/users/{user.id}")

        assert response.status_code == 200
        assert response.json()["id"] == str(user.id)

    def test_get_user_not_found(self, authenticated_client):
        import uuid
        fake_id = uuid.uuid4()

        response = authenticated_client.get(f"/users/{fake_id}")

        assert response.status_code == 404

Fixtures

See references/fixtures.md for advanced fixture patterns including:

  • Database transactions
  • File uploads
  • External service mocking
  • Time freezing

Additional Resources

Reference Files

  • references/fixtures.md - Advanced fixture patterns, mocking, parametrization

Related Skills

  • django-dev - Core Django patterns
  • django-dev-ninja - API patterns being tested

Unfold Admin Development

Django Unfold admin patterns with modern UI and HTMX customization.

Core Principles

  1. One admin = one file - Each ModelAdmin in its own file
  2. Unfold base classes - Extend UnfoldAdmin classes
  3. HTMX for dynamics - Use HTMX for interactive features
  4. Dashboard first - Custom dashboards for data visualization
  5. Tailwind styling - Consistent Tailwind CSS classes

Installation

pip install django-unfold

Configuration

# config/settings.py (with Dynaconf)
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.filters",
    "unfold.contrib.forms",
    "unfold.contrib.inlines",
    "unfold.contrib.import_export",  # Optional
    "django.contrib.admin",
    # ... other apps
]

# Unfold configuration
UNFOLD = {
    "SITE_TITLE": "My Admin",
    "SITE_HEADER": "My Admin",
    "SITE_URL": "/",
    "SITE_SYMBOL": "speed",  # Material Symbols icon
    "SHOW_HISTORY": True,
    "SHOW_VIEW_ON_SITE": True,
    "ENVIRONMENT": "config.settings.environment_callback",
    "COLORS": {
        "primary": {
            "50": "250 245 255",
            "100": "243 232 255",
            "200": "233 213 255",
            "300": "216 180 254",
            "400": "192 132 252",
            "500": "168 85 247",
            "600": "147 51 234",
            "700": "126 34 206",
            "800": "107 33 168",
            "900": "88 28 135",
            "950": "59 7 100",
        },
    },
    "SIDEBAR": {
        "show_search": True,
        "show_all_applications": True,
        "navigation": [
            {
                "title": "Navigation",
                "items": [
                    {
                        "title": "Dashboard",
                        "icon": "dashboard",
                        "link": reverse_lazy("admin:index"),
                    },
                    {
                        "title": "Users",
                        "icon": "people",
                        "link": reverse_lazy("admin:users_user_changelist"),
                    },
                ],
            },
        ],
    },
}


def environment_callback(request):
    """Show environment badge in admin."""
    from config.settings import settings
    env = settings.current_env
    if env == "production":
        return ["Production", "danger"]
    elif env == "staging":
        return ["Staging", "warning"]
    return ["Development", "info"]

Admin Structure

myapp/
└── admin/
    ├── __init__.py           # Register all admins
    ├── base.py               # Base admin classes
    ├── user.py               # UserAdmin
    ├── product.py            # ProductAdmin
    └── order.py              # OrderAdmin

Base Admin Classes

In admin/base.py:

from django.contrib import admin
from unfold.admin import ModelAdmin


class BaseModelAdmin(ModelAdmin):
    """Base admin with common configuration."""

    list_per_page = 25
    show_full_result_count = False

    # Unfold features
    compressed_fields = True
    warn_unsaved_form = True

    def get_queryset(self, request):
        """Exclude soft-deleted by default."""
        qs = super().get_queryset(request)
        if hasattr(self.model, "deleted_at"):
            qs = qs.filter(deleted_at__isnull=True)
        return qs


class ReadOnlyModelAdmin(BaseModelAdmin):
    """Admin for read-only models."""

    def has_add_permission(self, request):
        return False

    def has_change_permission(self, request, obj=None):
        return False

    def has_delete_permission(self, request, obj=None):
        return False

ModelAdmin Template

Each admin in its own file (admin/user.py):

from django.contrib import admin
from django.utils.html import format_html
from unfold.admin import ModelAdmin
from unfold.decorators import display

from ..models import User
from .base import BaseModelAdmin


@admin.register(User)
class UserAdmin(BaseModelAdmin):
    list_display = ["email", "name", "display_status", "created_at"]
    list_filter = ["is_active", "created_at"]
    search_fields = ["email", "name"]
    ordering = ["-created_at"]

    readonly_fields = ["id", "created_at", "updated_at"]

    fieldsets = [
        (None, {
            "fields": ["id", "email", "name"],
        }),
        ("Status", {
            "fields": ["is_active"],
            "classes": ["collapse"],
        }),
        ("Timestamps", {
            "fields": ["created_at", "updated_at"],
            "classes": ["collapse"],
        }),
    ]

    @display(
        description="Status",
        label={
            True: "success",
            False: "danger",
        },
    )
    def display_status(self, obj):
        return obj.is_active

Admin Init

Register all admins in admin/__init__.py:

from .user import UserAdmin
from .product import ProductAdmin
from .order import OrderAdmin

__all__ = [
    "UserAdmin",
    "ProductAdmin",
    "OrderAdmin",
]

Display Decorators

Unfold provides display decorators for styled output:

from unfold.decorators import display


@display(
    description="Status",
    label={
        "active": "success",
        "pending": "warning",
        "cancelled": "danger",
    },
)
def display_status(self, obj):
    return obj.status


@display(
    description="Amount",
    ordering="total_amount",
)
def display_amount(self, obj):
    return f"${obj.total_amount:,.2f}"


@display(
    description="Actions",
    header=True,  # Show in header row
)
def display_actions(self, obj):
    return format_html(
        '<a href="{}" class="btn btn-sm btn-primary">View</a>',
        obj.get_absolute_url(),
    )

Filters

Unfold filter types:

from unfold.contrib.filters.admin import (
    RangeDateFilter,
    RangeDateTimeFilter,
    SingleNumericFilter,
    RangeNumericFilter,
    SliderNumericFilter,
    DropdownFilter,
    ChoicesDropdownFilter,
    RelatedDropdownFilter,
    AutocompleteSelectFilter,
)


@admin.register(Order)
class OrderAdmin(BaseModelAdmin):
    list_filter = [
        ("created_at", RangeDateFilter),
        ("total_amount", RangeNumericFilter),
        ("status", ChoicesDropdownFilter),
        ("user", RelatedDropdownFilter),
    ]

Inline Admin

from unfold.admin import TabularInline, StackedInline


class OrderItemInline(TabularInline):
    model = OrderItem
    extra = 0
    readonly_fields = ["subtotal"]

    def subtotal(self, obj):
        return obj.quantity * obj.unit_price


@admin.register(Order)
class OrderAdmin(BaseModelAdmin):
    inlines = [OrderItemInline]

HTMX Actions

See references/customization.md for HTMX patterns including:

  • Dynamic field updates
  • Inline actions
  • Modal dialogs
  • Live search

Dashboard

Custom dashboard in admin/dashboard.py. See references/customization.md.

Additional Resources

Reference Files

  • references/customization.md - HTMX patterns, dashboard setup, custom widgets

Related Skills

  • django-dev - Core Django patterns
  • django-dev-test - Testing admin functionality

Django Development Patterns

Opinionated Django development toolkit enforcing consistent, production-ready patterns.

Core Principles

  1. One file = one model/form - Each model and form lives in its own file
  2. Consistent prefixes - Abstract (Base*), virtual (Virtual*), proxy (Proxy*)
  3. UUID primary keys - All models use UUID instead of auto-increment
  4. Timestamps everywhere - All models inherit created_at/updated_at
  5. Soft delete by default - Use deleted_at instead of hard deletes
  6. Dynaconf for config - Never use plain settings.py
  7. uv + pyproject.toml - Use uv for package management with split deps
  8. Class member ordering - Strict ordering for readability
  9. Docker in /docker - All Docker artifacts in /docker folder

Project Setup (uv + pyproject.toml)

Always use uv for package management with split dependencies:

# Initialize project
uv init myproject
cd myproject

# Add dependencies by group
uv add django dynaconf django-unfold django-ninja
uv add --group dev ruff mypy django-stubs
uv add --group test pytest pytest-django factory-boy pytest-cov

pyproject.toml:

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "django>=5.0",
    "dynaconf[toml]>=3.2",
    "django-unfold>=0.30",
    "django-ninja>=1.0",
    "psycopg[binary]>=3.1",
    "whitenoise>=6.6",
]

[dependency-groups]
dev = [
    "ruff>=0.3",
    "mypy>=1.8",
    "django-stubs>=4.2",
    "ipython>=8.0",
]
test = [
    "pytest>=8.0",
    "pytest-django>=4.8",
    "factory-boy>=3.3",
    "pytest-cov>=4.1",
    "freezegun>=1.4",
]

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.mypy]
plugins = ["mypy_django_plugin.main"]
strict = true

Project Structure

Standard Django project layout:

project/
├── pyproject.toml           # Dependencies (uv)
├── uv.lock                  # Lock file
├── docker/
│   ├── Dockerfile           # Main Dockerfile
│   ├── Dockerfile.dev       # Development Dockerfile
│   ├── docker-compose.yml   # Main compose
│   ├── docker-compose.dev.yml
│   ├── nginx/
│   │   └── nginx.conf
│   └── scripts/
│       ├── entrypoint.sh
│       └── wait-for-it.sh
├── config/
│   ├── __init__.py
│   ├── settings.py          # Dynaconf integration
│   ├── .secrets.toml        # Gitignored secrets
│   └── settings.toml        # Environment config
├── apps/
│   └── myapp/
│       ├── models/          # Package, not single file
│       │   ├── __init__.py
│       │   ├── base.py      # Base classes
│       │   └── user.py      # One model per file
│       ├── forms/
│       │   ├── __init__.py
│       │   └── user.py
│       ├── managers/
│       │   ├── __init__.py
│       │   └── user.py
│       ├── api/             # Django Ninja (see django-dev-ninja)
│       └── admin/           # Unfold admin (see django-dev-unfold)
├── tests/                   # See django-dev-test
└── manage.py

Docker Configuration

All Docker artifacts in /docker folder:

# docker/Dockerfile
FROM python:3.12-slim

WORKDIR /app

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Install dependencies
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Copy application
COPY . .

# Collect static files
RUN uv run python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["uv", "run", "gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]
# docker/docker-compose.yml
services:
  web:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    ports:
      - "8000:8000"
    environment:
      - DJANGO_ENV=production
    env_file:
      - ../.env
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=myproject
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${DB_PASSWORD}

volumes:
  postgres_data:

Model Organization

Base Classes

Create base classes in models/base.py:

import uuid
from django.db import models
from django.utils import timezone


class BaseTimeStamped(models.Model):
    """Adds created_at and updated_at timestamps."""
    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True
        get_latest_by = "created_at"


class BaseSoftDelete(models.Model):
    """Adds soft delete capability with deleted_at field."""
    deleted_at = models.DateTimeField(null=True, blank=True, db_index=True)

    class Meta:
        abstract = True

    def delete(self, using=None, keep_parents=False):
        self.deleted_at = timezone.now()
        self.save(update_fields=["deleted_at"])

    def hard_delete(self):
        super().delete()

    @property
    def is_deleted(self) -> bool:
        return self.deleted_at is not None


class BaseUUID(models.Model):
    """Uses UUID as primary key instead of auto-increment."""
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)

    class Meta:
        abstract = True


class BaseModel(BaseUUID, BaseTimeStamped, BaseSoftDelete):
    """Standard base model with UUID, timestamps, and soft delete."""

    class Meta:
        abstract = True

Naming Conventions

PrefixTypeExample
Base*Abstract base classBaseTimeStamped, BaseModel
Virtual*In-memory only (not persisted)VirtualCart, VirtualSession
Proxy*Proxy modelProxyActiveUser, ProxyAdmin
(none)Regular modelUser, Product, Order

Class Member Ordering

All classes follow strict member ordering:

  1. class Meta - ALWAYS FIRST in the class
  2. Fields - Class attributes (model fields)
  3. Managers - objects = Manager()
  4. Properties (@property) - Alphabetical order
  5. Private/dunder methods (_method, __str__) - Alphabetical order
  6. Public methods - Alphabetical order
class User(BaseModel):
    """User account model."""

    # 1. class Meta - ALWAYS FIRST
    class Meta:
        db_table = "users"
        ordering = ["-created_at"]

    # 2. Fields
    email = models.EmailField(unique=True)
    name = models.CharField(max_length=255)
    is_active = models.BooleanField(default=True)

    # 3. Manager
    objects = UserManager()

    # 4. Properties (alphabetical)
    @property
    def display_name(self) -> str:
        return self.name or self.email.split("@")[0]

    @property
    def is_verified(self) -> bool:
        return self.email_verified_at is not None

    # 5. Private/dunder methods (alphabetical)
    def __repr__(self) -> str:
        return f"<User {self.email}>"

    def __str__(self) -> str:
        return self.email

    def _calculate_score(self) -> int:
        return len(self.orders.all())

    def _validate_status(self) -> bool:
        return self.is_active

    # 6. Public methods (alphabetical)
    def activate(self) -> None:
        self.is_active = True
        self.save(update_fields=["is_active"])

    def can_place_order(self) -> bool:
        return self.is_active and not self.is_deleted

    def deactivate(self) -> None:
        self.is_active = False
        self.save(update_fields=["is_active"])

Model File Template

Each model in its own file (models/user.py):

from django.db import models
from .base import BaseModel
from ..managers.user import UserManager


class User(BaseModel):
    """User account model."""

    # 1. class Meta - ALWAYS FIRST
    class Meta:
        db_table = "users"
        verbose_name = "User"
        verbose_name_plural = "Users"
        ordering = ["-created_at"]

    # 2. Fields
    email = models.EmailField(unique=True)
    name = models.CharField(max_length=255)
    is_active = models.BooleanField(default=True)

    # 3. Manager
    objects = UserManager()

    # 4. Properties
    @property
    def display_name(self) -> str:
        return self.name or self.email.split("@")[0]

    # 5. Private/dunder methods
    def __str__(self) -> str:
        return self.email

Model Package Init

Re-export all models in models/__init__.py:

from .base import BaseModel, BaseTimeStamped, BaseSoftDelete, BaseUUID
from .user import User
from .product import Product

__all__ = [
    "BaseModel",
    "BaseTimeStamped",
    "BaseSoftDelete",
    "BaseUUID",
    "User",
    "Product",
]

Custom Managers

Place managers in managers/ package:

# managers/user.py
from django.db import models


class UserQuerySet(models.QuerySet):
    def active(self):
        return self.filter(is_active=True, deleted_at__isnull=True)

    def by_email(self, email: str):
        return self.filter(email__iexact=email)


class UserManager(models.Manager):
    def get_queryset(self) -> UserQuerySet:
        return UserQuerySet(self.model, using=self._db)

    def active(self):
        return self.get_queryset().active()

    def by_email(self, email: str):
        return self.get_queryset().by_email(email)

Dynaconf Configuration

Always use Dynaconf for Django settings. See references/dynaconf.md for complete setup.

Quick setup:

pip install dynaconf
dynaconf init -f toml

Update config/settings.py:

from dynaconf import Dynaconf

settings = Dynaconf(
    envvar_prefix="DJANGO",
    settings_files=["settings.toml", ".secrets.toml"],
    environments=True,
    env_switcher="DJANGO_ENV",
)

Form Organization

Forms follow the same 1-file-per-form pattern. See references/forms.md for details.

# forms/user.py
from django import forms
from ..models import User


class UserForm(forms.ModelForm):
    class Meta:
        model = User
        fields = ["email", "name"]

Creating a New App

To create a new Django app with proper structure:

  1. Create app directory with packages:
mkdir -p apps/myapp/{models,forms,managers,api,admin}
touch apps/myapp/__init__.py
touch apps/myapp/{models,forms,managers,api,admin}/__init__.py
  1. Create base classes in models/base.py
  2. Add app to INSTALLED_APPS using Dynaconf
  3. Create initial models following conventions

Additional Resources

Reference Files

For detailed patterns and setup guides:

  • references/models.md - Advanced model patterns, relationships, constraints
  • references/forms.md - Form organization, validation, widgets
  • references/dynaconf.md - Complete Dynaconf setup and environment configuration

Related Skills

  • django-dev-ninja - API development with Django Ninja
  • django-dev-unfold - Admin customization with Unfold
  • django-dev-test - Testing with pytest and factories

Agents 1

You are a Django code reviewer specializing in opinionated Django development patterns. Your role is to ensure code follows strict conventions for maintainability and consistency.

Your Core Responsibilities:

  1. Review model organization (1 file = 1 model)
  2. Verify naming conventions (Base*, Virtual*, Proxy* prefixes)
  3. Check class member ordering
  4. Validate API structure (1 endpoint = 1 file)
  5. Ensure proper configuration (Dynaconf, uv, Docker)
  6. Identify security issues

Review Checklist:

Models

  • Each model in its own file in models/ package
  • Abstract models prefixed with Base
  • Virtual (in-memory) models prefixed with Virtual
  • Proxy models prefixed with Proxy
  • All models inherit from BaseModel (UUID + timestamps + soft delete)
  • Custom managers in managers/ package
  • Class member ordering: Meta (FIRST) → Fields → Managers → @property → _private/dunder → public (all alphabetical)

Forms

  • Each form in its own file in forms/ package
  • Forms inherit from BaseModelForm or BaseForm
  • Same class member ordering as models

API (Django Ninja)

  • Each endpoint in its own file
  • Endpoints grouped in api/<logical_group>/ subpackages
  • One router per group in __init__.py
  • Pydantic schemas in schemas/ package
  • Business logic in services, not endpoints

Admin (Unfold)

  • Each ModelAdmin in its own file in admin/ package
  • Admins extend UnfoldModelAdmin or BaseModelAdmin

Configuration

  • Dynaconf used for settings (not plain settings.py)
  • uv + pyproject.toml for dependencies
  • Dependencies split: main, dev, test groups
  • Docker files in /docker folder

Security

  • No hardcoded secrets
  • Proper authentication on endpoints
  • No raw SQL without parameterization
  • CSRF protection where needed

Analysis Process:

  1. Identify the type of code being reviewed (model, form, API, admin, config)
  2. Read the relevant files using Glob and Read tools
  3. Check each applicable convention from the checklist
  4. Categorize issues as:
    • Critical: Security issues, missing authentication
    • Convention: Naming, file organization, class ordering
    • Suggestion: Improvements, optimizations
  5. Provide specific line numbers and fix recommendations

Output Format:

## Django Code Review

### Summary
- Files reviewed: X
- Critical issues: X
- Convention violations: X
- Suggestions: X

### Critical Issues
1. **[File:Line]** Issue description
   - Current: `code`
   - Fix: `corrected code`

### Convention Violations
1. **[File:Line]** Issue description
   - Rule: [which convention]
   - Fix: [how to fix]

### Suggestions
1. **[File]** Suggestion description

### Compliant
- [List of things done correctly]

Edge Cases:

  • Legacy code: Note but don't require refactoring unless asked
  • Third-party integrations: Skip external package conventions
  • Test files: Apply pytest conventions, not model conventions
  • Migration files: Skip review (auto-generated)

Sponsors

Details

Marketplace
sergio-bershadsky/ai
Source
plugins/django-dev
Category
Development

More from sergio-bershadsky/ai

All 13