django-chassis 1.0.20

A declarative, fully typed chassis for building polished Django Admin applications.

Documentation · Quick start · API reference · Changelog

Django-Chassis gives a project a structured AdminSite, composable ModelAdmin options, custom pages, dashboard contracts, and a complete template overlay. Domain models and business rules stay in the project; Chassis provides the reusable Admin application layer around them.

Features

• Declarative configuration — compose the Admin with ChassisAdminSiteMixin, ChassisAdminMixin, and immutable options.
• A polished changelist — search, filters, date hierarchy, tabs, badges, pretty JSON, and decimal-amount presentation without ad-hoc template forks.
• Row, list, and object actions — permission-aware buttons, confirmation, and condition methods.
• Related data — independently paginated tables and typed repeatable inputs with native or application-owned form-data processing.
• Custom pages — permission-aware pages, personal pages, information pages, and timelines.
• Dashboard contracts — metrics, charts, alerts, actions, a four-column grid, and live refresh at dashboard/live/.
• Import/export — JSON/XML in, JSON/XML/CSV/XLSX out, preview/apply, history, a shared worker protocol with optional Celery/Dramatiq providers.
• Users and security — profiles, sessions, login-attempt limits, GeoIP country detection, and an Admin audit journal.
• Fully typed — ships py.typed and is checked with Pyrefly in strict mode.

Installation

pip install django-chassis

Version 1.0.20 requires Python 3.13 or 3.14 and Django 6.0+.

Put 'django_chassis' before 'django.contrib.admin' so package templates overlay the stock Admin:

INSTALLED_APPS = [
    'django_chassis',
    'django.contrib.admin',
    # ...
]

Background import/export is optional:

pip install 'django-chassis[dramatiq]'
# or
pip install 'django-chassis[celery]'

For WSGI projects, Chassis provides an optional Gunicorn management command:

pip install 'django-chassis[gunicorn]'
python manage.py run_gunicorn --port=8000 --workers=2

For ASGI projects, use the optional Uvicorn command:

pip install 'django-chassis[uvicorn,dramatiq]'
python manage.py run_uvicorn --host 127.0.0.1 --port 8000 --workers 1 --reload

run_uvicorn resolves ASGI_APPLICATION or an explicit --app; it does not require a project-specific server command. Extras can be combined. django-chassis[all] installs Gunicorn, Uvicorn, Dramatiq and Celery. The base package installs none of these optional runtimes. Selecting an extra installs its dependencies; the application still configures its worker broker and database. For PostgreSQL jobs, install and configure the chosen PostgreSQL broker and driver in the application. Installing an extra does not enable import/export or start workers.

Quick start

Create a Chassis AdminSite, register a model, and mount the site in urls.py:

from django.contrib.admin import AdminSite, ModelAdmin
from django.urls import path
from django.utils.translation import gettext_lazy as _

from django_chassis.mixins import ChassisAdminMixin, ChassisAdminSiteMixin
from django_chassis.options import RowActionsOption, SearchOption

from catalog.models import Book


class CustomAdminSite(ChassisAdminSiteMixin, AdminSite):
    chassis_brand_name = _('My project')
    chassis_brand_logo_static_path = 'img/logo.png'


admin_site = CustomAdminSite(name='admin')


class BookAdmin(ChassisAdminMixin, ModelAdmin):
    options = [SearchOption(fields=['title', 'isbn']), RowActionsOption()]


admin_site.register(Book, BookAdmin)

urlpatterns = [path('admin/', admin_site.urls)]

ChassisAdminSiteMixin and ChassisAdminMixin must come before their Django classes in the MRO.

Documentation

Read the full guides, architecture notes, option reference, and dashboard contracts at django-chassis.rdd-lab.com.

Testing

uv sync --group dev
uv run pytest

License

Distributed under the MIT License.

Support the project