django-devbar 0.1.0__tar.gz

django_devbar-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: django-devbar
+Version: 0.1.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, and response time.
+
+![devbar example](docs/devbar-example.svg)
+
+## Installation
+
+```bash
+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
+
+```python
+# Position: bottom-right, bottom-left, top-right, top-left (default: bottom-right)
+DEVBAR_POSITION = "top-left"
+
+# Show HTML overlay (default: DEBUG)
+DEVBAR_SHOW_BAR = True
+
+# Add X-DevBar-* response headers (default: False)
+DEVBAR_SHOW_HEADERS = True
+```
+
+## 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 thresholds (e.g., fail CI if query count exceeds a limit)
+- **Monitoring tools** that can capture and aggregate header values
+
+Headers included:
+
+| Header | Description |
+|--------|-------------|
+| `X-DevBar-Query-Count` | Number of database queries executed |
+| `X-DevBar-Query-Duration` | Total time spent in database queries (ms) |
+| `X-DevBar-Response-Time` | Total request-response cycle time (ms) |
+| `X-DevBar-Has-Duplicates` | Present (value `1`) if duplicate queries detected |

django_devbar-0.1.0/README.md

@@ -0,0 +1,51 @@
+# django-devbar
+
+Lightweight performance devbar for Django. Shows DB query count, query duration, and response time.
+
+![devbar example](docs/devbar-example.svg)
+
+## Installation
+
+```bash
+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
+
+```python
+# Position: bottom-right, bottom-left, top-right, top-left (default: bottom-right)
+DEVBAR_POSITION = "top-left"
+
+# Show HTML overlay (default: DEBUG)
+DEVBAR_SHOW_BAR = True
+
+# Add X-DevBar-* response headers (default: False)
+DEVBAR_SHOW_HEADERS = True
+```
+
+## 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 thresholds (e.g., fail CI if query count exceeds a limit)
+- **Monitoring tools** that can capture and aggregate header values
+
+Headers included:
+
+| Header | Description |
+|--------|-------------|
+| `X-DevBar-Query-Count` | Number of database queries executed |
+| `X-DevBar-Query-Duration` | Total time spent in database queries (ms) |
+| `X-DevBar-Response-Time` | Total request-response cycle time (ms) |
+| `X-DevBar-Has-Duplicates` | Present (value `1`) if duplicate queries detected |

django_devbar-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "django-devbar"
+version = "0.1.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.1.0/src/django_devbar/__init__.py

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

django_devbar-0.1.0/src/django_devbar/conf.py

@@ -0,0 +1,21 @@
+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_position():
+    key = getattr(settings, "DEVBAR_POSITION", "bottom-right")
+    return POSITIONS.get(key, POSITIONS["bottom-right"])
+
+
+def get_show_bar():
+    return getattr(settings, "DEVBAR_SHOW_BAR", settings.DEBUG)
+
+
+def get_show_headers():
+    return getattr(settings, "DEVBAR_SHOW_HEADERS", False)

django_devbar-0.1.0/src/django_devbar/middleware.py

@@ -0,0 +1,89 @@
+import re
+from contextlib import ExitStack
+from time import perf_counter
+
+from django.db import connections
+
+from . import tracker
+from .conf import get_position, get_show_bar, get_show_headers
+
+DEVBAR_HTML = (
+    '<div id="django-devbar" style="position:fixed;{position};'
+    "background:rgba(0,0,0,0.7);color:rgba(255,255,255,0.85);"
+    "padding:4px 8px;margin:8px;"
+    "font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;"
+    "font-size:10px;line-height:1.3;font-weight:500;letter-spacing:0.02em;"
+    "z-index:99999;border-radius:3px;"
+    'backdrop-filter:blur(8px);-webkit-backdrop-filter:blur(8px)">'
+    '<span style="opacity:0.5">queries</span> {count}{duplicates} <span style="opacity:0.5">·</span> '
+    '<span style="opacity:0.5">db</span> {duration:.0f}ms <span style="opacity:0.5">·</span> '
+    '<span style="opacity:0.5">total</span> {response_time:.0f}ms</div>'
+)
+
+DUPLICATE_MARKER = (
+    ' <span style="color:#f59e0b" title="Duplicate queries detected">(d)</span>'
+)
+
+BODY_CLOSE_RE = re.compile(rb"</body\s*>", re.IGNORECASE)
+
+
+class DevBarMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        request_start = perf_counter()
+        tracker.reset()
+
+        with ExitStack() as stack:
+            for alias in connections:
+                stack.enter_context(
+                    connections[alias].execute_wrapper(tracker.tracking_wrapper)
+                )
+            response = self.get_response(request)
+
+        response_time = (perf_counter() - request_start) * 1000
+        stats = tracker.get_stats()
+
+        if get_show_headers():
+            self._add_headers(response, stats, response_time)
+
+        if get_show_bar() and self._can_inject(response):
+            self._inject_devbar(response, stats, response_time)
+
+        return response
+
+    def _add_headers(self, response, stats, response_time):
+        response["X-DevBar-Query-Count"] = str(stats["count"])
+        response["X-DevBar-Query-Duration"] = f"{stats['duration']:.1f}"
+        response["X-DevBar-Response-Time"] = f"{response_time:.1f}"
+        if stats["has_duplicates"]:
+            response["X-DevBar-Has-Duplicates"] = "1"
+
+    def _can_inject(self, response):
+        if getattr(response, "streaming", False):
+            return False
+        content_type = response.get("Content-Type", "").lower()
+        if "text/html" not in content_type:
+            return False
+        if response.get("Content-Encoding"):
+            return False
+        return hasattr(response, "content")
+
+    def _inject_devbar(self, response, stats, response_time):
+        content = response.content
+        matches = list(BODY_CLOSE_RE.finditer(content))
+        if not matches:
+            return
+
+        devbar_html = DEVBAR_HTML.format(
+            position=get_position(),
+            count=stats["count"],
+            duplicates=DUPLICATE_MARKER if stats["has_duplicates"] else "",
+            duration=stats["duration"],
+            response_time=response_time,
+        ).encode(response.charset or "utf-8")
+
+        idx = matches[-1].start()
+        response.content = content[:idx] + devbar_html + content[idx:]
+        response["Content-Length"] = str(len(response.content))

django_devbar-0.1.0/src/django_devbar/tracker.py

@@ -0,0 +1,54 @@
+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"
+)  # sql -> set of params hashes
+_has_duplicates: ContextVar[bool] = ContextVar("has_duplicates", default=False)
+
+
+def reset():
+    _query_count.set(0)
+    _query_duration.set(0.0)
+    _seen_queries.set({})
+    _has_duplicates.set(False)
+
+
+def get_stats():
+    return {
+        "count": _query_count.get(),
+        "duration": _query_duration.get(),
+        "has_duplicates": _has_duplicates.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()
+    if sql in seen:
+        params_hash = _hash_params(params)
+        if params_hash in seen[sql]:
+            _has_duplicates.set(True)
+        else:
+            seen[sql].add(params_hash)
+    else:
+        seen[sql] = {_hash_params(params)}
+
+
+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)