API Reference¶

Complete API documentation for debug-toolbar.

Core¶

Configuration¶

class debug_toolbar.core.config.DebugToolbarConfig¶

Base configuration for the debug toolbar.

Parameters:

enabled (bool) – Enable/disable the toolbar (default: True)
exclude_paths (list[str]) – Paths to exclude from toolbar (default: [“/_debug_toolbar”, “/static”])
max_request_history (int) – Maximum requests to store (default: 50)
panels (list[str]) – List of panel class paths to enable
extra_panels (list[str]) – Additional panels to add
exclude_panels (list[str]) – Panels to exclude

Panel Base Class¶

class debug_toolbar.core.panel.Panel¶

Base class for debug toolbar panels.

Variables:

panel_id – Unique identifier for the panel
title – Display title
template – Template name for rendering
has_content – Whether panel has expandable content

async generate_stats(context: RequestContext) → dict[str, Any]¶: Generate statistics for this panel.

generate_server_timing(context: RequestContext) → str¶: Generate Server-Timing header value.

Request Context¶

class debug_toolbar.core.context.RequestContext¶

Request-scoped context using contextvars.

Parameters:

request_id (UUID) – Unique request identifier
start_time (float) – Request start timestamp

classmethod get_current() → RequestContext | None¶: Get the current request context.

classmethod set_current(context: RequestContext) → None¶: Set the current request context.

Storage¶

class debug_toolbar.core.storage.RequestStorage¶

LRU storage for request history.

Parameters:: max_size (int) – Maximum number of requests to store

store(request_id: UUID, data: dict) → None¶: Store request data.

get(request_id: UUID) → dict | None¶: Retrieve request data by ID.

list_requests() → list[dict]¶: List all stored requests (newest first).

Litestar Integration¶

Plugin¶

class debug_toolbar.litestar.plugin.DebugToolbarPlugin¶

Litestar plugin for the debug toolbar.

Parameters:: config (LitestarDebugToolbarConfig) – Toolbar configuration

Example:

from litestar import Litestar
from debug_toolbar.litestar import DebugToolbarPlugin, LitestarDebugToolbarConfig

config = LitestarDebugToolbarConfig(enabled=True)
app = Litestar(plugins=[DebugToolbarPlugin(config)])

Configuration¶

class debug_toolbar.litestar.config.LitestarDebugToolbarConfig¶

Litestar-specific configuration extending DebugToolbarConfig.

Parameters:

show_toolbar_callback (Callable[[Request], bool] | None) – Callable to determine if toolbar should show
intercept_redirects (bool) – Intercept redirects to show toolbar

Middleware¶

class debug_toolbar.litestar.middleware.DebugToolbarMiddleware¶: ASGI middleware that injects the toolbar into HTML responses.

Built-in Panels¶

Timer Panel¶

class debug_toolbar.core.panels.timer.TimerPanel¶

Displays request timing information.

Stats:

total_time: Total request duration (ms)
user_cpu_time: User CPU time
system_cpu_time: System CPU time

Request Panel¶

class debug_toolbar.core.panels.request.RequestPanel¶

Displays HTTP request information.

Stats:

method: HTTP method
path: Request path
query_params: Query string parameters
headers: Request headers
cookies: Request cookies

Response Panel¶

class debug_toolbar.core.panels.response.ResponsePanel¶

Displays HTTP response information.

Stats:

status_code: Response status
headers: Response headers
content_length: Response size

Headers Panel¶

class debug_toolbar.core.panels.headers.HeadersPanel¶

Categorized display of HTTP headers with security analysis.

Categories:

Security headers (CSP, HSTS, X-Frame-Options)
Caching headers
CORS headers
Authentication headers (redacted)

Logging Panel¶

class debug_toolbar.core.panels.logging.LoggingPanel¶

Captures log records during request processing.

Stats:

records: List of log records with level, message, timestamp

Profiling Panel¶

class debug_toolbar.core.panels.profiling.ProfilingPanel¶

CPU profiling with cProfile or pyinstrument.

Variables:: profiler_backend – “cprofile” or “pyinstrument”

Alerts Panel¶

class debug_toolbar.core.panels.alerts.AlertsPanel¶

Proactive issue detection panel.

Detection Categories:

Security: Missing headers, insecure cookies, CSRF issues
Performance: Large responses, slow queries
Database: N+1 patterns, query optimization
Configuration: Debug mode in production

Stats:

alerts: List of detected alerts with severity and suggestions
total_alerts: Total alert count
by_severity: Counts by severity level
by_category: Counts by category

Memory Panel¶

class debug_toolbar.core.panels.memory.MemoryPanel¶

Memory profiling with multiple backend support.

Backends:

tracemalloc: Built-in Python tracer (default)
memray: Advanced profiler (Linux/macOS, requires install)

Stats:

memory_before: Memory at request start
memory_after: Memory at request end
memory_delta: Memory change during request
top_allocations: Largest allocations by file/line

SQLAlchemy Panel¶

class debug_toolbar.extras.advanced_alchemy.panel.SQLAlchemyPanel¶

Tracks SQLAlchemy queries with timing and EXPLAIN support.

Stats:

queries: List of executed queries
total_queries: Query count
total_time: Total query time
duplicate_queries: Detected duplicate queries
n_plus_one_groups: Detected N+1 query patterns

Features:

Query timing
Parameter display
Duplicate detection
N+1 query detection with fix suggestions
EXPLAIN query plans (PostgreSQL, SQLite, MySQL, MariaDB)

Litestar-Specific Panels¶

Routes Panel¶

class debug_toolbar.litestar.panels.routes.RoutesPanel¶

Displays all registered routes in the Litestar application.

Stats:

routes: List of all routes with methods and handlers
current_route: The matched route for this request

Events Panel¶

class debug_toolbar.litestar.panels.events.EventsPanel¶

Tracks Litestar lifecycle events and hooks.

Stats:

lifecycle_hooks: on_startup, on_shutdown handlers
request_hooks: before_request, after_request, after_response handlers
exception_handlers: Registered exception handlers
executed_hooks: Hooks that ran during this request

Module Reference¶

`debug_toolbar.core.config`	Configuration system for the debug toolbar.
`debug_toolbar.core.panel`	Base panel class for debug toolbar panels.
`debug_toolbar.core.context`	Request context management using contextvars for async-safe data propagation.
`debug_toolbar.core.storage`	Storage backend for toolbar request history using LRU cache.
`debug_toolbar.core.toolbar`	Main debug toolbar manager class.
`debug_toolbar.core.panels`	Built-in panels for the async debug toolbar.
`debug_toolbar.litestar.plugin`	Debug toolbar plugin for Litestar.
`debug_toolbar.litestar.config`	Litestar-specific configuration for the debug toolbar.
`debug_toolbar.litestar.middleware`	Debug toolbar middleware for Litestar.
`debug_toolbar.litestar.panels`	Litestar-specific panels for the debug toolbar.