litestar-debug-toolbar 0.2.0__py3-none-any.whl

debug_toolbar/__init__.py

@@ -0,0 +1,35 @@
+"""Debug Toolbar - Async-native debug toolbar for Python ASGI applications.
+
+This package provides a framework-agnostic debug toolbar with optional integrations
+for popular frameworks like Litestar.
+
+Basic usage with core components:
+    from debug_toolbar import DebugToolbar, DebugToolbarConfig
+
+For Litestar integration:
+    from debug_toolbar.litestar import DebugToolbarPlugin, LitestarDebugToolbarConfig
+"""
+
+from __future__ import annotations
+
+from debug_toolbar.core import (
+    DebugToolbar,
+    DebugToolbarConfig,
+    Panel,
+    RequestContext,
+    ToolbarStorage,
+    get_request_context,
+    set_request_context,
+)
+
+__all__ = [
+    "DebugToolbar",
+    "DebugToolbarConfig",
+    "Panel",
+    "RequestContext",
+    "ToolbarStorage",
+    "get_request_context",
+    "set_request_context",
+]
+
+__version__ = "0.1.0"

debug_toolbar/core/__init__.py

@@ -0,0 +1,19 @@
+"""Core debug toolbar components - Framework-agnostic."""
+
+from __future__ import annotations
+
+from debug_toolbar.core.config import DebugToolbarConfig
+from debug_toolbar.core.context import RequestContext, get_request_context, set_request_context
+from debug_toolbar.core.panel import Panel
+from debug_toolbar.core.storage import ToolbarStorage
+from debug_toolbar.core.toolbar import DebugToolbar
+
+__all__ = [
+    "DebugToolbar",
+    "DebugToolbarConfig",
+    "Panel",
+    "RequestContext",
+    "ToolbarStorage",
+    "get_request_context",
+    "set_request_context",
+]

debug_toolbar/core/config.py

@@ -0,0 +1,71 @@
+"""Configuration system for the debug toolbar."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from debug_toolbar.core.panel import Panel
+
+
+@dataclass
+class DebugToolbarConfig:
+    """Configuration for the debug toolbar.
+
+    Attributes:
+        enabled: Whether the toolbar is enabled. Defaults to True.
+        panels: List of panel classes or import paths to include.
+        intercept_redirects: Whether to intercept redirects for debugging.
+        show_toolbar_callback: Optional callback to determine if toolbar should be shown.
+        insert_before: HTML tag to insert toolbar before. Defaults to "</body>".
+        max_request_history: Maximum number of requests to store in history.
+        api_path: URL path prefix for toolbar API endpoints.
+        static_path: URL path prefix for static assets.
+        allowed_hosts: List of allowed hosts. Empty list means all hosts.
+        extra_panels: Additional panels to add beyond defaults.
+        exclude_panels: Panel names to exclude from defaults.
+        memory_backend: Memory profiling backend. "auto" selects best available.
+        panel_display_depth: Max depth for nested data rendering. Defaults to 10.
+        panel_display_max_items: Max items to show in arrays/objects. Defaults to 100.
+        panel_display_max_string: Max string length before truncation. Defaults to 1000.
+    """
+
+    enabled: bool = True
+    panels: Sequence[str | type[Panel]] = field(
+        default_factory=lambda: [
+            "debug_toolbar.core.panels.timer.TimerPanel",
+            "debug_toolbar.core.panels.request.RequestPanel",
+            "debug_toolbar.core.panels.response.ResponsePanel",
+            "debug_toolbar.core.panels.logging.LoggingPanel",
+            "debug_toolbar.core.panels.versions.VersionsPanel",
+        ]
+    )
+    intercept_redirects: bool = False
+    show_toolbar_callback: Callable[..., bool] | None = None
+    insert_before: str = "</body>"
+    max_request_history: int = 50
+    api_path: str = "/_debug_toolbar"
+    static_path: str = "/_debug_toolbar/static"
+    allowed_hosts: Sequence[str] = field(default_factory=list)
+    extra_panels: Sequence[str | type[Panel]] = field(default_factory=list)
+    exclude_panels: Sequence[str] = field(default_factory=list)
+    memory_backend: Literal["tracemalloc", "memray", "auto"] = "auto"
+    panel_display_depth: int = 10
+    panel_display_max_items: int = 100
+    panel_display_max_string: int = 1000
+
+    def get_all_panels(self) -> list[str | type[Panel]]:
+        """Get all panels including extras, excluding excluded panels."""
+        all_panels = list(self.panels) + list(self.extra_panels)
+        if not self.exclude_panels:
+            return all_panels
+
+        excluded = set(self.exclude_panels)
+        return [
+            p
+            for p in all_panels
+            if (isinstance(p, str) and p.split(".")[-1] not in excluded)
+            or (isinstance(p, type) and p.__name__ not in excluded)
+        ]

debug_toolbar/core/context.py

@@ -0,0 +1,104 @@
+"""Request context management using contextvars for async-safe data propagation."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import UUID, uuid4
+
+_request_context: ContextVar[RequestContext | None] = ContextVar("request_context", default=None)
+
+
+@dataclass
+class RequestContext:
+    """Request-scoped context for debug toolbar data collection.
+
+    This context is stored in a contextvar and is accessible throughout the
+    request lifecycle without passing it explicitly through the call stack.
+
+    Attributes:
+        request_id: Unique identifier for this request.
+        panel_data: Dictionary of data collected by panels, keyed by panel_id.
+        timing_data: Dictionary of timing measurements.
+        metadata: Additional metadata about the request.
+    """
+
+    request_id: UUID = field(default_factory=uuid4)
+    panel_data: dict[str, dict[str, Any]] = field(default_factory=dict)
+    timing_data: dict[str, float] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def store_panel_data(self, panel_id: str, key: str, value: Any) -> None:
+        """Store data for a specific panel.
+
+        Args:
+            panel_id: The panel's identifier.
+            key: The data key.
+            value: The data value.
+        """
+        if panel_id not in self.panel_data:
+            self.panel_data[panel_id] = {}
+        self.panel_data[panel_id][key] = value
+
+    def get_panel_data(self, panel_id: str) -> dict[str, Any]:
+        """Get all data for a specific panel.
+
+        Args:
+            panel_id: The panel's identifier.
+
+        Returns:
+            Dictionary of panel data, or empty dict if no data exists.
+        """
+        return self.panel_data.get(panel_id, {})
+
+    def record_timing(self, name: str, duration: float) -> None:
+        """Record a timing measurement.
+
+        Args:
+            name: The name of the timing measurement.
+            duration: The duration in seconds.
+        """
+        self.timing_data[name] = duration
+
+    def get_timing(self, name: str) -> float | None:
+        """Get a timing measurement.
+
+        Args:
+            name: The name of the timing measurement.
+
+        Returns:
+            The duration in seconds, or None if not recorded.
+        """
+        return self.timing_data.get(name)
+
+
+def get_request_context() -> RequestContext | None:
+    """Get the current request context.
+
+    Returns:
+        The current RequestContext, or None if no context is set.
+    """
+    return _request_context.get()
+
+
+def set_request_context(context: RequestContext | None) -> None:
+    """Set the current request context.
+
+    Args:
+        context: The RequestContext to set, or None to clear.
+    """
+    _request_context.set(context)
+
+
+def ensure_request_context() -> RequestContext:
+    """Get or create a request context.
+
+    Returns:
+        The current RequestContext, creating a new one if none exists.
+    """
+    ctx = get_request_context()
+    if ctx is None:
+        ctx = RequestContext()
+        set_request_context(ctx)
+    return ctx

debug_toolbar/core/panel.py

@@ -0,0 +1,147 @@
+"""Base panel class for debug toolbar panels."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from debug_toolbar.core.context import RequestContext
+    from debug_toolbar.core.toolbar import DebugToolbar
+
+
+class Panel(ABC):
+    """Abstract base class for debug toolbar panels.
+
+    Panels are responsible for collecting and displaying specific types of
+    debug information. Each panel should override the abstract methods to
+    provide its functionality.
+
+    Class Attributes:
+        panel_id: Unique identifier for the panel. Defaults to class name.
+        title: Display title shown in the toolbar.
+        template: Template name for rendering the panel content.
+        has_content: Whether this panel has detailed content.
+        nav_title: Short title for the toolbar navigation.
+        nav_subtitle: Subtitle shown in the toolbar navigation.
+    """
+
+    panel_id: ClassVar[str] = ""
+    title: ClassVar[str] = ""
+    template: ClassVar[str] = ""
+    has_content: ClassVar[bool] = True
+    nav_title: ClassVar[str] = ""
+    nav_subtitle: ClassVar[str] = ""
+
+    __slots__ = ("_enabled", "_toolbar")
+
+    def __init__(self, toolbar: DebugToolbar) -> None:
+        """Initialize the panel.
+
+        Args:
+            toolbar: The parent DebugToolbar instance.
+        """
+        self._toolbar = toolbar
+        self._enabled = True
+
+    @classmethod
+    def get_panel_id(cls) -> str:
+        """Get the panel's unique identifier.
+
+        Returns:
+            The panel_id class variable, or the class name if not set.
+        """
+        return cls.panel_id or cls.__name__
+
+    @property
+    def enabled(self) -> bool:
+        """Check if the panel is enabled."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        """Set whether the panel is enabled."""
+        self._enabled = value
+
+    @abstractmethod
+    async def generate_stats(self, context: RequestContext) -> dict[str, Any]:
+        """Generate statistics for this panel.
+
+        This method is called during request processing to collect data.
+
+        Args:
+            context: The current request context.
+
+        Returns:
+            Dictionary of statistics data.
+        """
+        ...
+
+    async def process_request(self, context: RequestContext) -> None:
+        """Process the request phase.
+
+        Override this to perform actions at the start of request processing.
+
+        Args:
+            context: The current request context.
+        """
+
+    async def process_response(self, context: RequestContext) -> None:
+        """Process the response phase.
+
+        Override this to perform actions at the end of request processing.
+
+        Args:
+            context: The current request context.
+        """
+
+    def get_stats(self, context: RequestContext) -> dict[str, Any]:
+        """Get stored stats from context.
+
+        Args:
+            context: The current request context.
+
+        Returns:
+            Dictionary of panel stats.
+        """
+        return context.get_panel_data(self.get_panel_id())
+
+    def record_stats(self, context: RequestContext, stats: dict[str, Any]) -> None:
+        """Record stats to the context.
+
+        Args:
+            context: The current request context.
+            stats: Dictionary of stats to store.
+        """
+        panel_id = self.get_panel_id()
+        for key, value in stats.items():
+            context.store_panel_data(panel_id, key, value)
+
+    def generate_server_timing(self, context: RequestContext) -> dict[str, float]:
+        """Generate Server-Timing header data.
+
+        Override this to contribute to the Server-Timing header.
+
+        Args:
+            context: The current request context.
+
+        Returns:
+            Dictionary mapping metric names to durations in seconds.
+        """
+        return {}
+
+    def get_nav_title(self) -> str:
+        """Get the navigation title.
+
+        Returns:
+            The nav_title class variable, or title if not set.
+        """
+        return self.nav_title or self.title
+
+    def get_nav_subtitle(self) -> str:
+        """Get the navigation subtitle.
+
+        Returns:
+            The nav_subtitle class variable.
+        """
+        return self.nav_subtitle

debug_toolbar/core/panels/__init__.py

@@ -0,0 +1,31 @@
+"""Built-in panels for the async debug toolbar."""
+
+from __future__ import annotations
+
+from debug_toolbar.core.panels.alerts import AlertsPanel
+from debug_toolbar.core.panels.cache import CachePanel
+from debug_toolbar.core.panels.headers import HeadersPanel
+from debug_toolbar.core.panels.logging import LoggingPanel
+from debug_toolbar.core.panels.memory import MemoryPanel
+from debug_toolbar.core.panels.profiling import ProfilingPanel
+from debug_toolbar.core.panels.request import RequestPanel
+from debug_toolbar.core.panels.response import ResponsePanel
+from debug_toolbar.core.panels.settings import SettingsPanel
+from debug_toolbar.core.panels.templates import TemplatesPanel
+from debug_toolbar.core.panels.timer import TimerPanel
+from debug_toolbar.core.panels.versions import VersionsPanel
+
+__all__ = [
+    "AlertsPanel",
+    "CachePanel",
+    "HeadersPanel",
+    "LoggingPanel",
+    "MemoryPanel",
+    "ProfilingPanel",
+    "RequestPanel",
+    "ResponsePanel",
+    "SettingsPanel",
+    "TemplatesPanel",
+    "TimerPanel",
+    "VersionsPanel",
+]