
django-dev
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-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add sergio-bershadsky/ai.
Contents
Discovered from sourceSkills 4
Django Ninja API Development
Opinionated Django Ninja patterns with single-endpoint-per-file organization.
Core Principles
- One endpoint = one file - Each endpoint lives in its own file
- Logical grouping - Endpoints grouped in subpackages by domain
- Router per group - Each group has its own router
- Schemas in separate package - Pydantic models in
schemas/ - 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, permissionsreferences/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
- pytest only - Never use Django's TestCase
- factory_boy - Use factories for all test data
- Mirror structure - Tests mirror app structure
- Isolation - Each test fully isolated
- Fast fixtures - Prefer
@pytest.fixtureover 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
- One admin = one file - Each ModelAdmin in its own file
- Unfold base classes - Extend UnfoldAdmin classes
- HTMX for dynamics - Use HTMX for interactive features
- Dashboard first - Custom dashboards for data visualization
- 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
- One file = one model/form - Each model and form lives in its own file
- Consistent prefixes - Abstract (
Base*), virtual (Virtual*), proxy (Proxy*) - UUID primary keys - All models use UUID instead of auto-increment
- Timestamps everywhere - All models inherit created_at/updated_at
- Soft delete by default - Use deleted_at instead of hard deletes
- Dynaconf for config - Never use plain settings.py
- uv + pyproject.toml - Use uv for package management with split deps
- Class member ordering - Strict ordering for readability
- Docker in /docker - All Docker artifacts in
/dockerfolder
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
| Prefix | Type | Example |
|---|---|---|
Base* | Abstract base class | BaseTimeStamped, BaseModel |
Virtual* | In-memory only (not persisted) | VirtualCart, VirtualSession |
Proxy* | Proxy model | ProxyActiveUser, ProxyAdmin |
| (none) | Regular model | User, Product, Order |
Class Member Ordering
All classes follow strict member ordering:
class Meta- ALWAYS FIRST in the class- Fields - Class attributes (model fields)
- Managers -
objects = Manager() - Properties (
@property) - Alphabetical order - Private/dunder methods (
_method,__str__) - Alphabetical order - 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:
- 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
- Create base classes in
models/base.py - Add app to
INSTALLED_APPSusing Dynaconf - Create initial models following conventions
Additional Resources
Reference Files
For detailed patterns and setup guides:
references/models.md- Advanced model patterns, relationships, constraintsreferences/forms.md- Form organization, validation, widgetsreferences/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:
- Review model organization (1 file = 1 model)
- Verify naming conventions (Base*, Virtual*, Proxy* prefixes)
- Check class member ordering
- Validate API structure (1 endpoint = 1 file)
- Ensure proper configuration (Dynaconf, uv, Docker)
- 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
BaseModelFormorBaseForm - 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
UnfoldModelAdminorBaseModelAdmin
Configuration
- Dynaconf used for settings (not plain settings.py)
- uv + pyproject.toml for dependencies
- Dependencies split: main, dev, test groups
- Docker files in
/dockerfolder
Security
- No hardcoded secrets
- Proper authentication on endpoints
- No raw SQL without parameterization
- CSRF protection where needed
Analysis Process:
- Identify the type of code being reviewed (model, form, API, admin, config)
- Read the relevant files using Glob and Read tools
- Check each applicable convention from the checklist
- Categorize issues as:
- Critical: Security issues, missing authentication
- Convention: Naming, file organization, class ordering
- Suggestion: Improvements, optimizations
- 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