django-kaleidoscope 0.0.12

A debug toolbar for Django.

Overview

The kaleidoscope toolbar records what a request did and renders it as a set of panels over the page. There are twelve panels by default, covering SQL, templates, cache calls, signals, static files, settings, versions, timing, memory, the request itself, and two profilers. This is useful for finding N+1 queries, slow views, and template rendering costs during development.

The toolbar installs as a single middleware and mounts into a shadow root, so the page it inspects cannot restyle it and its own stylesheet cannot reach the page.

Prerequisites

• Django 4.2+
• Python 3.11+
• DEBUG must be True, unless KALEIDOSCOPE_SHOW_CALLBACK is set

Installation

pip install django-kaleidoscope

Add the app, the middleware, and your address to your Django settings:

INSTALLED_APPS = [
    'kaleidoscope'
]

MIDDLEWARE = [
    'kaleidoscope.middleware.KaleidoscopeMiddleware'
]

INTERNAL_IPS = ['127.0.0.1']

The middleware belongs after GZipMiddleware. A compressed response carries a Content-Encoding and the injector refuses it, so a toolbar loaded first never appears. A system check reports the ordering at startup.

Configuration

There are eight system checks at startup, reporting a missing middleware, a middleware registered twice, a middleware ordered before GZipMiddleware, an empty INTERNAL_IPS with no callback, a panel path that will not import, a panel that is not a Panel subclass, a KALEIDOSCOPE_PANELS that is not a list, and a KALEIDOSCOPE_IGNORE_PATHS that is not a list of path prefixes.

Panels

The panels are toggled at runtime from the strip, which persists the panel order, side, active panel, and collapsed state in localStorage.

Example Project

The example/ directory holds a Django project written to be slow. The columns carry no db_index, the model properties open a query each time they are read, and the aggregates are folded in Python instead of the database. Each page names the mistakes it is making.

The /books/optimized/ page renders the same sixty rows as /books/ using select_related, prefetch_related, and Count and Avg annotations, which is the difference between 882 queries and 4.

just install
just reset
just run-server

The just screenshot recipe captures each panel into example/screenshot/ and accepts a filter, such as just screenshot queries.