django-devbar 0.3.0__tar.gz

django_devbar-0.3.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: django-devbar
+Version: 0.3.0
+Summary: Lightweight performance devbar for Django
+Keywords: django,debug,performance,monitoring,development
+Author: amureki
+Author-email: amureki <oss@amureki.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Topic :: Software Development
+Classifier: Intended Audience :: Developers
+Requires-Dist: django>=4.2
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/amureki/django-devbar
+Project-URL: Issues, https://github.com/amureki/django-devbar/issues
+Project-URL: Repository, https://github.com/amureki/django-devbar
+Description-Content-Type: text/markdown
+
+# django-devbar
+
+Lightweight performance devbar for Django. Shows DB query count, query duration, application time, and detects duplicate queries with visual severity indicators.
+
+![devbar example](https://github.com/amureki/django-devbar/raw/3c6118d4283c211a5d84510de52e1d5c3e5e46e4/docs/devbar-example.svg)
+
+![devbar warning example](https://github.com/amureki/django-devbar/raw/3c6118d4283c211a5d84510de52e1d5c3e5e46e4/docs/devbar-example-warning.svg)
+
+> **Note:** This package is experimental and may introduce breaking changes in minor versions.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add --dev django-devbar
+
+# Or using pip
+pip install django-devbar
+```
+
+Add to your middleware as early as possible, but after any middleware that encodes the response (e.g., `GZipMiddleware`):
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django_devbar.DevBarMiddleware",
+    # ...
+]
+```
+
+## Configuration
+
+All settings are optional. Configure via a `DEVBAR` dict in your Django settings:
+
+```python
+DEVBAR = {
+    'POSITION': 'bottom-right',  # bottom-right, bottom-left, top-right, top-left
+    'SHOW_BAR': None,            # None (default) = follows DEBUG, or True/False to override
+    'SHOW_HEADERS': False,       # Add DevBar-* headers to responses
+}
+```
+
+## Response Headers
+
+When `DEVBAR = {'SHOW_HEADERS': True}`, performance metrics are added as HTTP response headers. This is useful for:
+
+- **API endpoints** where the HTML overlay can't be displayed
+- **Automated testing** to assert performance metrics (e.g., fail CI if query count exceeds a limit)
+- **Monitoring tools** that can capture and aggregate header values
+
+Headers included:
+
+| Header | Example | Description |
+|--------|---------|-------------|
+| `DevBar-Query-Count` | `12` | Number of database queries executed |
+| `DevBar-DB-Time` | `87ms` | Total time spent in database queries |
+| `DevBar-App-Time` | `41ms` | Application time (total time minus DB time) |
+| `DevBar-Duplicates` | `3` | Number of duplicate queries detected (only present if duplicates found) |
+
+## Chrome Extension
+
+![Chrome DevTools extension](https://github.com/user-attachments/assets/4288f507-0bd5-4b8c-a3dc-0c4d5b93305f)
+
+View Django DevBar metrics directly in Chrome DevTools with the [official extension](https://chromewebstore.google.com/detail/django-devbar/fehcaaopchkbknbdhjadnmehiifdmeid).
+Requires `DEVBAR = {'SHOW_HEADERS': True}`.
+
+See [chrome-extension/README.md](chrome-extension/README.md) for more details.

django_devbar-0.3.0/README.md

@@ -0,0 +1,67 @@
+# django-devbar
+
+Lightweight performance devbar for Django. Shows DB query count, query duration, application time, and detects duplicate queries with visual severity indicators.
+
+![devbar example](https://github.com/amureki/django-devbar/raw/3c6118d4283c211a5d84510de52e1d5c3e5e46e4/docs/devbar-example.svg)
+
+![devbar warning example](https://github.com/amureki/django-devbar/raw/3c6118d4283c211a5d84510de52e1d5c3e5e46e4/docs/devbar-example-warning.svg)
+
+> **Note:** This package is experimental and may introduce breaking changes in minor versions.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add --dev django-devbar
+
+# Or using pip
+pip install django-devbar
+```
+
+Add to your middleware as early as possible, but after any middleware that encodes the response (e.g., `GZipMiddleware`):
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django_devbar.DevBarMiddleware",
+    # ...
+]
+```
+
+## Configuration
+
+All settings are optional. Configure via a `DEVBAR` dict in your Django settings:
+
+```python
+DEVBAR = {
+    'POSITION': 'bottom-right',  # bottom-right, bottom-left, top-right, top-left
+    'SHOW_BAR': None,            # None (default) = follows DEBUG, or True/False to override
+    'SHOW_HEADERS': False,       # Add DevBar-* headers to responses
+}
+```
+
+## Response Headers
+
+When `DEVBAR = {'SHOW_HEADERS': True}`, performance metrics are added as HTTP response headers. This is useful for:
+
+- **API endpoints** where the HTML overlay can't be displayed
+- **Automated testing** to assert performance metrics (e.g., fail CI if query count exceeds a limit)
+- **Monitoring tools** that can capture and aggregate header values
+
+Headers included:
+
+| Header | Example | Description |
+|--------|---------|-------------|
+| `DevBar-Query-Count` | `12` | Number of database queries executed |
+| `DevBar-DB-Time` | `87ms` | Total time spent in database queries |
+| `DevBar-App-Time` | `41ms` | Application time (total time minus DB time) |
+| `DevBar-Duplicates` | `3` | Number of duplicate queries detected (only present if duplicates found) |
+
+## Chrome Extension
+
+![Chrome DevTools extension](https://github.com/user-attachments/assets/4288f507-0bd5-4b8c-a3dc-0c4d5b93305f)
+
+View Django DevBar metrics directly in Chrome DevTools with the [official extension](https://chromewebstore.google.com/detail/django-devbar/fehcaaopchkbknbdhjadnmehiifdmeid).
+Requires `DEVBAR = {'SHOW_HEADERS': True}`.
+
+See [chrome-extension/README.md](chrome-extension/README.md) for more details.

django_devbar-0.3.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "django-devbar"
+version = "0.3.0"
+description = "Lightweight performance devbar for Django"
+readme = "README.md"
+license = "MIT"
+authors = [
+  { name = "amureki", email = "oss@amureki.com" },
+]
+requires-python = ">=3.10"
+dependencies = ["django>=4.2"]
+keywords = ["django", "debug", "performance", "monitoring", "development"]
+classifiers = [
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Framework :: Django",
+  "Framework :: Django :: 4.2",
+  "Framework :: Django :: 5.0",
+  "Framework :: Django :: 5.1",
+  "Framework :: Django :: 5.2",
+  "Framework :: Django :: 6.0",
+  "Topic :: Software Development",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://github.com/amureki/django-devbar"
+Repository = "https://github.com/amureki/django-devbar"
+Issues = "https://github.com/amureki/django-devbar/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.16,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+  "pytest",
+  "pytest-django",
+  "ruff",
+]
+
+[tool.pytest]
+pythonpath = ["src", "."]
+testpaths = ["tests"]
+norecursedirs = [".venv", ".git"]
+DJANGO_SETTINGS_MODULE = "tests.settings"

django_devbar-0.3.0/src/django_devbar/__init__.py

@@ -0,0 +1,3 @@
+from .middleware import DevBarMiddleware
+
+__all__ = ["DevBarMiddleware"]

django_devbar-0.3.0/src/django_devbar/conf.py

@@ -0,0 +1,33 @@
+from django.conf import settings
+
+POSITIONS = {
+    "bottom-right": "bottom:0;right:0",
+    "bottom-left": "bottom:0;left:0",
+    "top-right": "top:0;right:0",
+    "top-left": "top:0;left:0",
+}
+
+
+def get_config():
+    return {
+        "POSITION": "bottom-right",
+        "SHOW_BAR": None,  # None = use settings.DEBUG
+        "SHOW_HEADERS": False,
+        **getattr(settings, "DEVBAR", {}),
+    }
+
+
+def get_position():
+    config = get_config()
+    key = config["POSITION"]
+    return POSITIONS.get(key, POSITIONS["bottom-right"])
+
+
+def get_show_bar():
+    config = get_config()
+    show_bar = config["SHOW_BAR"]
+    return settings.DEBUG if show_bar is None else show_bar
+
+
+def get_show_headers():
+    return get_config()["SHOW_HEADERS"]

django_devbar-0.3.0/src/django_devbar/middleware.py

@@ -0,0 +1,123 @@
+import json
+import re
+from contextlib import ExitStack
+from pathlib import Path
+from time import perf_counter
+
+from django.db import connections
+from django.template import Context, Engine
+
+from . import tracker
+from .conf import (
+    get_position,
+    get_show_bar,
+    get_show_headers,
+)
+
+BODY_CLOSE_RE = re.compile(rb"</body\s*>", re.IGNORECASE)
+
+_template_engine = Engine(
+    dirs=[Path(__file__).parent / "templates"],
+    autoescape=True,
+)
+
+
+class DevBarMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        tracker.reset()
+        request_start = perf_counter()
+
+        with ExitStack() as stack:
+            for alias in connections:
+                stack.enter_context(
+                    connections[alias].execute_wrapper(tracker.tracking_wrapper)
+                )
+            response = self.get_response(request)
+
+        total_time = (perf_counter() - request_start) * 1000
+        stats = tracker.get_stats()
+
+        db_time = stats["duration"]
+        python_time = max(0, total_time - db_time)
+
+        stats["python_time"] = python_time
+        stats["total_time"] = total_time
+
+        level = "warn" if stats["has_duplicates"] else "ok"
+
+        if get_show_headers():
+            self._add_headers(response, stats)
+
+        if get_show_bar() and self._can_inject(response):
+            self._inject_devbar(response, stats, level)
+
+        return response
+
+    def _add_headers(self, response, stats):
+        response["DevBar-Query-Count"] = str(stats["count"])
+        response["DevBar-DB-Time"] = f"{stats['duration']:.0f}ms"
+        response["DevBar-App-Time"] = f"{stats['python_time']:.0f}ms"
+        if stats["has_duplicates"]:
+            response["DevBar-Duplicates"] = str(len(stats["duplicate_queries"]))
+
+        # Add comprehensive JSON data for browser DevTools extension
+        extension_data = {
+            "count": stats["count"],
+            "db_time": stats["duration"],
+            "app_time": stats["python_time"],
+            "total_time": stats["total_time"],
+            "has_duplicates": stats["has_duplicates"],
+        }
+        if stats.get("duplicate_queries"):
+            extension_data["duplicates"] = stats["duplicate_queries"]
+
+        response["DevBar-Data"] = json.dumps(extension_data)
+
+    def _can_inject(self, response):
+        if getattr(response, "streaming", False):
+            return False
+        content_type = response.get("Content-Type", "").lower()
+        if "html" not in content_type:
+            return False
+        if response.get("Content-Encoding"):
+            return False
+        return hasattr(response, "content")
+
+    def _inject_devbar(self, response, stats, level):
+        content = response.content
+        matches = list(BODY_CLOSE_RE.finditer(content))
+        if not matches:
+            return
+
+        duplicates_html = self._build_duplicates_html(
+            stats.get("duplicate_queries", [])
+        )
+
+        template = _template_engine.get_template("django_devbar/devbar.html")
+        html = template.render(
+            Context(
+                {
+                    "position": get_position(),
+                    "level": level,
+                    "db_time": stats["duration"],
+                    "app_time": stats["python_time"],
+                    "query_count": stats["count"],
+                    "duplicates_html": duplicates_html,
+                }
+            )
+        )
+
+        payload = html.encode(response.charset or "utf-8")
+
+        idx = matches[-1].start()
+        response.content = content[:idx] + payload + content[idx:]
+        response["Content-Length"] = str(len(response.content))
+
+    def _build_duplicates_html(self, duplicates):
+        if not duplicates:
+            return ""
+        template = _template_engine.get_template("django_devbar/duplicates.html")
+        return template.render(Context({"duplicates": duplicates}))

django_devbar-0.3.0/src/django_devbar/templates/django_devbar/devbar.html

@@ -0,0 +1,92 @@
+<style>
+#django-devbar {
+    position: fixed; {{ position }}; z-index: 999999999;
+    display: flex; align-items: center; gap: 5px;
+    font-family: -apple-system, system-ui, sans-serif;
+    font-size: 11px; font-weight: 500;
+    padding: 4px 8px; margin: 8px; border-radius: 4px;
+    backdrop-filter: blur(8px); -webkit-backdrop-filter: blur(8px);
+    box-shadow: 0 2px 8px rgba(0,0,0,0.15), 0 1px 2px rgba(0,0,0,0.2);
+    transition: all 0.2s ease;
+    cursor: default;
+    line-height: 1.3;
+    background: rgba(20, 20, 20, 0.92);
+    color: #f5f5f5;
+}
+#django-devbar.level-warn { border-left: 3px solid #f59e0b; }
+#django-devbar span { opacity: 0.7; }
+#django-devbar strong { opacity: 1; font-weight: 600; }
+#django-devbar details { display: inline; position: relative; }
+#django-devbar summary {
+    all: revert;
+    color: #f59e0b; font-weight: 600; cursor: pointer; list-style: none;
+}
+#django-devbar summary::-webkit-details-marker { display: none; }
+#django-devbar details[open] > .dup-list {
+    position: absolute; bottom: 100%; right: -8px; margin-bottom: 8px;
+    background: rgba(20, 20, 20, 0.92); border-radius: 4px; padding: 6px;
+    width: min(500px, 90vw); max-height: 200px; overflow-y: auto; overflow-x: hidden;
+    box-sizing: border-box;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.15), 0 1px 2px rgba(0,0,0,0.2);
+}
+#django-devbar .dup-list details {
+    display: block;
+    margin: 0 0 6px 0;
+    font-size: 11px;
+    color: #f5f5f5;
+}
+#django-devbar .dup-list details:last-child { margin-bottom: 0; }
+#django-devbar .dup-list summary {
+    all: revert;
+    cursor: pointer;
+    list-style: none;
+    padding: 6px 8px;
+    background: rgba(251, 191, 36, 0.1);
+    border-radius: 3px;
+    border-left: 2px solid #fbbf24;
+    transition: background 0.15s ease;
+}
+#django-devbar .dup-list summary:hover {
+    background: rgba(251, 191, 36, 0.2);
+}
+#django-devbar .dup-list summary code {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    display: inline-block;
+    max-width: 420px;
+    vertical-align: bottom;
+}
+#django-devbar .dup-list summary::before {
+    content: '▶ ';
+    display: inline-block;
+    transition: transform 0.15s ease;
+    color: #fbbf24;
+    font-size: 8px;
+    margin-right: 6px;
+}
+#django-devbar .dup-list details[open] > summary::before {
+    transform: rotate(90deg);
+}
+#django-devbar .dup-list code {
+    all: revert;
+    color: #fbbf24; font-family: 'SF Mono', Consolas, 'Liberation Mono', Menlo, monospace;
+    overflow-wrap: break-word;
+}
+#django-devbar .dup-list details[open] > code {
+    display: block;
+    padding: 8px;
+    background: rgba(0, 0, 0, 0.3);
+    border-radius: 3px;
+    margin-top: 6px;
+    white-space: pre-wrap;
+    line-height: 1.5;
+    font-size: 10px;
+}
+@media (max-width: 640px) { #django-devbar { display: none; } }
+</style>
+<div id="django-devbar" class="level-{{ level }}">
+<span>db</span> <strong>{{ db_time|floatformat:0 }}ms</strong> <span>·</span>
+<span>app</span> <strong>{{ app_time|floatformat:0 }}ms</strong> <span>·</span>
+<span>queries</span> <strong>{{ query_count }}</strong>{{ duplicates_html|safe }}
+</div>

django_devbar-0.3.0/src/django_devbar/templates/django_devbar/duplicates.html

@@ -0,0 +1 @@
+{% if duplicates %}<details><summary>({{ duplicates|length }}d)</summary><div class="dup-list">{% for dup in duplicates %}<details><summary><code>{{ dup.sql }}</code></summary><code>{{ dup.sql }}</code></details>{% endfor %}</div></details>{% endif %}

django_devbar-0.3.0/src/django_devbar/tracker.py

@@ -0,0 +1,61 @@
+from contextvars import ContextVar
+from time import perf_counter
+
+_query_count: ContextVar[int] = ContextVar("query_count", default=0)
+_query_duration: ContextVar[float] = ContextVar("query_duration", default=0.0)
+_seen_queries: ContextVar[dict] = ContextVar("seen_queries", default={})
+_duplicate_log: ContextVar[list] = ContextVar("duplicate_log", default=[])
+
+
+def reset():
+    _query_count.set(0)
+    _query_duration.set(0.0)
+    _seen_queries.set({})
+    _duplicate_log.set([])
+
+
+def get_stats():
+    return {
+        "count": _query_count.get(),
+        "duration": _query_duration.get(),
+        "has_duplicates": bool(_duplicate_log.get()),
+        "duplicate_queries": _duplicate_log.get(),
+    }
+
+
+def _hash_params(params):
+    try:
+        return hash(tuple(params)) if params else 0
+    except TypeError:
+        return hash(str(params))
+
+
+def _record(sql, params, duration):
+    _query_count.set(_query_count.get() + 1)
+    _query_duration.set(_query_duration.get() + duration)
+
+    seen = _seen_queries.get()
+    params_hash = _hash_params(params)
+
+    if sql in seen:
+        if params_hash in seen[sql]:
+            param_str = str(params)
+            if len(param_str) > 200:
+                param_str = param_str[:200] + "..."
+
+            duplicates = _duplicate_log.get()
+            duplicates.append(
+                {"sql": sql, "params": param_str, "duration": round(duration, 2)}
+            )
+        else:
+            seen[sql].add(params_hash)
+    else:
+        seen[sql] = {params_hash}
+
+
+def tracking_wrapper(execute, sql, params, many, context):
+    start = perf_counter()
+    try:
+        return execute(sql, params, many, context)
+    finally:
+        _record(sql, params, (perf_counter() - start) * 1000)