pagebar 0.1.0__py3-none-any.whl

pagebar/__init__.py

@@ -0,0 +1,10 @@
+"""pagebar — a tiny prod-safe perf footer for ASGI apps.
+
+Public surface lives in :mod:`pagebar._core`; this module just re-exports it.
+"""
+
+from __future__ import annotations
+
+from pagebar._core import PagebarMiddleware, __version__, pagebar_html
+
+__all__ = ["PagebarMiddleware", "__version__", "pagebar_html"]

pagebar/_core.py

@@ -0,0 +1,392 @@
+"""pagebar implementation. Public surface is re-exported from ``pagebar``.
+
+Drop ``PagebarMiddleware`` into the ASGI stack, drop ``pagebar_html()`` into
+the host's base template. Per-request state lives in ``ContextVar``\\ s so
+the helper can read what the middleware wrote without threading anything
+through.
+
+The full set of surfaced fields is fixed by the README — adding to it is a
+security review, not a feature request.
+"""
+
+from __future__ import annotations
+
+import gc
+import logging
+import os
+import re
+import sys
+import threading
+import time
+from contextvars import ContextVar
+from html import escape
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger("pagebar")
+
+# Time units, named so PLR2004 (magic-value-comparison) is honest.
+_MS_PER_SEC = 1000
+_SEC_PER_MIN = 60
+_SEC_PER_HOUR = 3600
+_SEC_PER_DAY = 86400
+_BYTES_PER_MIB = 1024 * 1024
+_SQL_TEXT_MAX = 500
+_SQL_PARAMS_MAX = 200
+
+# Process uptime baseline. Captured at import — fine for the worker-lifetime
+# view; on multi-worker setups each worker has its own.
+_BOOT_TIME = time.monotonic()
+
+# Per-request state. ContextVars are the simplest way to hand data from
+# middleware to the template helper without coupling them.
+_start: ContextVar[float] = ContextVar("pagebar_start", default=0.0)
+_queries: ContextVar[int] = ContextVar("pagebar_queries", default=0)
+_method: ContextVar[str] = ContextVar("pagebar_method", default="")
+_path: ContextVar[str] = ContextVar("pagebar_path", default="")
+_version: ContextVar[str] = ContextVar("pagebar_version", default="dev")
+
+# Unsafe mode — opt-in surfacing of SQL text + params. Default off.
+_unsafe: ContextVar[bool] = ContextVar("pagebar_unsafe", default=False)
+_sql_log: ContextVar[list] = ContextVar("pagebar_sql_log")  # set per request
+
+
+# Optional SQLAlchemy listener. Registered globally — same pattern as every
+# other tracing/perf tool. +1 to an int per cursor execute. If SQLAlchemy
+# isn't installed the counter just stays at zero.
+def _on_query(
+    _c: Any, _cur: Any, statement: str, parameters: Any, _ctx: Any, _many: Any
+) -> None:
+    _queries.set(_queries.get() + 1)
+    if _unsafe.get():
+        _sql_log.get().append({
+            "sql": statement,
+            "params": parameters,
+            "_t0": time.perf_counter(),
+        })
+
+
+def _on_query_done(*_args: Any, **_kwargs: Any) -> None:
+    if _unsafe.get():
+        log = _sql_log.get()
+        if log and "_t0" in log[-1]:
+            log[-1]["ms"] = (time.perf_counter() - log[-1].pop("_t0")) * 1000
+
+
+def _register_sqlalchemy_listener() -> None:
+    """Hook the SQL counter into SQLAlchemy if it's importable.
+
+    Keeps the imports local so ty doesn't see a module-level name typed both
+    as ``type[Engine]`` and ``None``.
+    """
+    try:
+        from sqlalchemy import event  # noqa: PLC0415
+        from sqlalchemy.engine import Engine  # noqa: PLC0415
+    except ImportError:  # pragma: no cover
+        return
+    event.listens_for(Engine, "before_cursor_execute")(_on_query)
+    event.listens_for(Engine, "after_cursor_execute")(_on_query_done)
+
+
+_register_sqlalchemy_listener()
+
+
+_BOT_RE = re.compile(r"bot|crawler|spider|googlebot|bingbot", re.IGNORECASE)
+
+
+def _is_bot(scope: dict) -> bool:
+    for name, val in scope.get("headers", ()):
+        if name == b"user-agent":
+            return bool(_BOT_RE.search(val.decode("latin-1", "replace")))
+    return False
+
+
+def _resolve_version(package: str, explicit: str) -> str:
+    if explicit:
+        return explicit
+    if not package:
+        return "dev"
+    try:
+        return _pkg_version(package)
+    except PackageNotFoundError:
+        logger.warning(
+            "pagebar: distribution %r not installed; falling back to 'dev'", package
+        )
+        return "dev"
+
+
+class PagebarMiddleware:
+    """ASGI middleware: timer + bot/disable gate + SQL log under unsafe."""
+
+    def __init__(  # noqa: PLR0913 — config-heavy by design
+        self,
+        app: Any,
+        *,
+        package: str = "",
+        version: str = "",
+        enabled: bool | Callable[[dict], bool] = True,
+        unsafe: bool | Callable[[dict], bool] = False,
+        query_budget: int = 0,
+    ) -> None:
+        self.app = app
+        self.package = package
+        self.version = _resolve_version(package, version)
+        self.enabled = enabled
+        self.unsafe = unsafe
+        self.query_budget = query_budget
+
+    @classmethod
+    def bound(cls, **kwargs: Any) -> type[PagebarMiddleware]:
+        """Return a subclass with config kwargs baked in.
+
+        Litestar (and similar frameworks) instantiate middleware as
+        ``mw_cls(app)`` with no further kwargs. Use this when you can't
+        thread keyword args through:
+
+            middleware=[
+                PagebarMiddleware.bound(package="my-app", unsafe=app.debug),
+                ...,
+            ]
+
+        For Starlette/FastAPI, prefer the plain
+        ``Middleware(PagebarMiddleware, package=..., unsafe=...)`` form —
+        no wrapper needed.
+        """
+
+        # ty rejects ``type[Self]`` as a class base; cast to ``Any``.
+        base: Any = cls
+
+        class _Bound(base):
+            def __init__(self, app: Any) -> None:
+                super().__init__(app, **kwargs)
+
+        _Bound.__name__ = f"{cls.__name__}Bound"
+        _Bound.__qualname__ = _Bound.__name__
+        return _Bound
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        on = self.enabled(scope) if callable(self.enabled) else self.enabled
+        if not on or _is_bot(scope):
+            await self.app(scope, receive, send)
+            return
+
+        _start.set(time.perf_counter())
+        _queries.set(0)
+        _method.set(scope.get("method", ""))
+        _path.set(scope.get("path", ""))
+        _version.set(self.version)
+        _unsafe.set(self.unsafe(scope) if callable(self.unsafe) else self.unsafe)
+        _sql_log.set([])
+
+        await self.app(scope, receive, send)
+
+        if self.query_budget > 0 and _queries.get() > self.query_budget:
+            logger.warning(
+                "pagebar: SQL budget exceeded: %s %s — %d queries "
+                "(budget=%d, elapsed=%.3fs)",
+                _method.get(),
+                _path.get(),
+                _queries.get(),
+                self.query_budget,
+                time.perf_counter() - _start.get(),
+            )
+
+
+# Bottom-right pill. Single dark color; opens upward into a small panel.
+_STYLE = """\
+.pagebar {
+    position: fixed;
+    bottom: 8px;
+    right: 8px;
+    z-index: 2147483647;
+    font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+    background: #1f2937;
+    color: #e5e7eb;
+    border-radius: 6px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, .2);
+    padding: 4px 10px;
+    cursor: pointer;
+    user-select: none;
+    max-width: 90vw;
+}
+.pagebar-panel {
+    margin-top: 6px;
+    padding: 8px 10px;
+    background: #111827;
+    border-radius: 4px;
+    display: none;
+}
+.pagebar.--open .pagebar-panel {
+    display: block;
+}
+.pagebar-row {
+    display: flex;
+    justify-content: space-between;
+    gap: 1em;
+    margin: 2px 0;
+    white-space: nowrap;
+}
+.pagebar-row span:last-child {
+    color: #9ca3af;
+}
+.pagebar-sql {
+    margin-top: 8px;
+    padding-top: 8px;
+    border-top: 1px solid #374151;
+    max-height: 40vh;
+    overflow: auto;
+}
+.pagebar-sql-item {
+    margin: 4px 0;
+    padding: 4px;
+    background: #0b1220;
+    border-radius: 3px;
+}
+.pagebar-sql-meta {
+    color: #f59e0b;
+    font-size: 11px;
+}
+.pagebar-sql-text {
+    white-space: pre-wrap;
+    word-break: break-word;
+    margin-top: 2px;
+}
+.pagebar-sql-params {
+    color: #9ca3af;
+    font-size: 11px;
+    margin-top: 2px;
+}
+.pagebar-unsafe-tag {
+    color: #fca5a5;
+    font-size: 10px;
+    margin-left: 4px;
+    background: #7f1d1d;
+    padding: 1px 4px;
+    border-radius: 3px;
+}
+"""
+
+# Closes on click outside the panel; ESC closes too. State in localStorage.
+_SCRIPT = """\
+(() => {
+    const bar = document.currentScript.previousElementSibling;
+    const KEY = 'pagebar.open';
+    const apply = () => {
+        bar.classList.toggle('--open', localStorage.getItem(KEY) === '1');
+    };
+
+    bar.addEventListener('click', (e) => {
+        if (e.target.closest('.pagebar-panel')) return;
+        const next = bar.classList.contains('--open') ? '0' : '1';
+        localStorage.setItem(KEY, next);
+        apply();
+    });
+
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape') {
+            localStorage.setItem(KEY, '0');
+            apply();
+        }
+    });
+
+    apply();
+})();
+"""
+
+
+def _fmt_elapsed(seconds: float) -> str:
+    ms = seconds * _MS_PER_SEC
+    if ms < _MS_PER_SEC:
+        return f"{ms:.0f}ms"
+    return f"{ms / _MS_PER_SEC:.2f}s"
+
+
+def _fmt_uptime(seconds: float) -> str:
+    if seconds < _SEC_PER_MIN:
+        return f"{seconds:.0f}s"
+    if seconds < _SEC_PER_HOUR:
+        return f"{seconds / _SEC_PER_MIN:.0f}m"
+    if seconds < _SEC_PER_DAY:
+        return f"{seconds / _SEC_PER_HOUR:.1f}h"
+    return f"{seconds / _SEC_PER_DAY:.1f}d"
+
+
+def _rss_mib() -> str:
+    """Process resident set size in MiB, or '—' if unavailable (Windows)."""
+    try:
+        import resource  # noqa: PLC0415
+
+        rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    except ImportError:  # Windows: no `resource` module
+        return "—"
+    # ru_maxrss is bytes on macOS, kibibytes on Linux/BSD.
+    bytes_ = rss if sys.platform == "darwin" else rss * 1024
+    return f"{bytes_ / _BYTES_PER_MIB:.1f} MiB"
+
+
+def _render_sql_log() -> str:
+    log = _sql_log.get()
+    if not log:
+        return ""
+    items = []
+    for i, e in enumerate(log, 1):
+        sql = escape(str(e.get("sql", "")))[:_SQL_TEXT_MAX]
+        params = escape(repr(e.get("params", "")))[:_SQL_PARAMS_MAX]
+        ms = e.get("ms")
+        meta = f"#{i} · {ms:.1f}ms" if ms is not None else f"#{i}"
+        items.append(
+            f'<div class="pagebar-sql-item">'
+            f'<div class="pagebar-sql-meta">{meta}</div>'
+            f'<div class="pagebar-sql-text">{sql}</div>'
+            f'<div class="pagebar-sql-params">{params}</div>'
+            f"</div>"
+        )
+    return f'<div class="pagebar-sql">{"".join(items)}</div>'
+
+
+def pagebar_html(*, nonce: str = "") -> str:
+    """Return the bar's HTML fragment. Safe to inject as-is."""
+    elapsed = time.perf_counter() - _start.get() if _start.get() else 0.0
+    q = _queries.get()
+    method = escape(_method.get())
+    path = escape(_path.get())
+    ver = escape(_version.get())
+    unsafe = _unsafe.get()
+
+    rows = (
+        ("Version", ver),
+        ("Time", _fmt_elapsed(elapsed)),
+        ("SQL", f"{q} quer{'y' if q == 1 else 'ies'}"),
+        ("Request", f"{method} {path}"),
+        ("Memory", _rss_mib()),
+        ("Uptime", _fmt_uptime(time.monotonic() - _BOOT_TIME)),
+        ("Threads", str(threading.active_count())),
+        ("GC", "/".join(str(n) for n in gc.get_count())),
+        ("Python", f"{sys.version_info.major}.{sys.version_info.minor}"),
+        ("PID", str(os.getpid())),
+    )
+    rows_html = "".join(
+        f'<div class="pagebar-row"><span>{k}</span><span>{v}</span></div>'
+        for k, v in rows
+    )
+    sql_html = _render_sql_log() if unsafe else ""
+    unsafe_tag = '<span class="pagebar-unsafe-tag">UNSAFE</span>' if unsafe else ""
+    n = f' nonce="{escape(nonce)}"' if nonce else ""
+    pill = f"{ver} · {_fmt_elapsed(elapsed)} · {q} SQL · {method} {path}"
+    return (
+        f"<style{n}>{_STYLE}</style>"
+        f'<div class="pagebar">'
+        f"<span>{pill}{unsafe_tag}</span>"
+        f'<div class="pagebar-panel">{rows_html}{sql_html}</div>'
+        f"</div>"
+        f"<script{n}>{_SCRIPT}</script>"
+    )

pagebar-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pagebar
+Version: 0.1.0
+Summary: A tiny prod-safe perf footer & toolbar for ASGI apps.
+Author-email: Stéfane Fermigier <sf@fermigier.com>
+License: MIT
+License-File: LICENSE
+Keywords: asgi,footer,monitoring,performance,sql
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# pagebar
+
+A tiny prod-safe perf footer for ASGI apps. One line at the bottom of every page, click to expand. No SQL text, no env vars, no stack traces — nothing that could leak.
+
+```
+v2026.6.19 · 22ms · 4 SQL · GET /editeurs · 200
+```
+
+## Install
+
+```sh
+pip install pagebar              # core only
+pip install pagebar[sqlalchemy]  # with SQL query counter
+```
+
+## Use
+
+### Starlette / FastAPI
+
+```python
+from pagebar import PagebarMiddleware, pagebar_html
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+
+app = Starlette(
+    middleware=[Middleware(PagebarMiddleware, package="my-app")],
+    routes=[...],
+)
+```
+
+### Litestar (and other `mw_cls(app)`-style frameworks)
+
+Litestar instantiates middleware as `cls(app)` with no further kwargs, so config has to be baked in. Use `PagebarMiddleware.bound(...)`:
+
+```python
+from litestar import Litestar
+from pagebar import PagebarMiddleware
+
+app = Litestar(
+    middleware=[
+        PagebarMiddleware.bound(package="my-app", unsafe=False),
+    ],
+    route_handlers=[...],
+)
+```
+
+`.bound(**kwargs)` returns a thin subclass with the kwargs baked into `__init__`. Same fields as the regular constructor.
+
+### Template
+
+In your base template, anywhere inside `<body>`:
+
+```html
+{{ pagebar_html() | safe }}
+</body>
+```
+
+That's it. One name for the middleware, one for the helper.
+
+## What's on screen
+
+| Field   | Source                                                            |
+|---------|-------------------------------------------------------------------|
+| Version | `importlib.metadata.version(package)` — or explicit `version=`    |
+| Time    | `time.perf_counter()` delta                                       |
+| SQL     | SQLAlchemy `before_cursor_execute` listener (if installed)        |
+| Request | method + path                                                     |
+| Memory  | `resource.getrusage().ru_maxrss` — RSS in MiB                     |
+| Uptime  | `time.monotonic()` since worker import                            |
+| Threads | `threading.active_count()`                                        |
+| GC      | `gc.get_count()` — gen0/gen1/gen2 pending                         |
+| Python  | `sys.version_info`                                                |
+| PID     | `os.getpid()`                                                     |
+
+No SQL text. No params. No env. No traces. That's the whole surface.
+
+## Knobs
+
+```python
+PagebarMiddleware(
+    app,
+    package="my-app",     # distribution name (PyPI / pyproject.toml)
+    version="",           # escape hatch: bypass importlib.metadata lookup
+    enabled=True,         # bool or callable(scope) -> bool
+    unsafe=False,         # bool or callable(scope) -> bool — see below
+    query_budget=20,      # >0 → log a WARNING when SQL count exceeds this
+)
+```
+
+## Unsafe mode
+
+In dev, you usually *want* to see the SQL text. Flip `unsafe=True` and the bar adds, per request: each statement (truncated), bound parameters, and per-statement timing. A red `UNSAFE` badge in the pill makes the mode obvious.
+
+```python
+import os
+PagebarMiddleware(app, package="my-app", unsafe=bool(os.getenv("DEBUG")))
+# or framework-driven
+PagebarMiddleware(app, package="my-app", unsafe=app.debug)
+```
+
+`unsafe` defaults to `False` and **only** takes its value from constructor wiring — no URL parameter, no header, no cookie. The host's deploy config is the authority.
+
+`enabled` lets you hide the bar from JSON endpoints, healthchecks, or admin routes:
+
+```python
+def show(scope):
+    return not scope["path"].startswith(("/api/", "/health"))
+
+Middleware(PagebarMiddleware, package="my-app", enabled=show)
+```
+
+Bots are skipped automatically (`User-Agent` matching `bot|crawler|spider|googlebot|bingbot`).
+
+## CSP
+
+`pagebar_html()` accepts a `nonce` keyword that's applied to the inline `<style>` and `<script>`:
+
+```html
+{{ pagebar_html(nonce=csp_nonce) | safe }}
+```
+
+Otherwise the host needs `'unsafe-inline'` for both directives. No external assets, no third-party requests.
+
+## Why not the Django/Flask/Litestar debug toolbars?
+
+They reveal SQL text, environment, settings, request bodies, stack traces — fine in dev, unacceptable in production. pagebar surfaces a fixed, public-safe set of fields. The shape is the security model.
+
+## Non-goals
+
+No panels system, no plugins, no per-framework adapters, no APM, no time series, no SQL EXPLAIN, no profiler. Pure ASGI middleware + one helper function in one file.
+
+## License
+
+MIT.

pagebar-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pagebar/__init__.py,sha256=Gb-s-v6ESCbq4IYeE3LmBKzxslLXyRGZvqSZNOQrZ0Y,314
+pagebar/_core.py,sha256=ckTQcvF_H7NezL3rdTPAqomoH96yH9h-fUPNiAUy8c0,11955
+pagebar-0.1.0.dist-info/METADATA,sha256=UlKixCnAOk5dcoihpZ2e9KJTUsLvAq6u9uPnxrDJD4E,5354
+pagebar-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pagebar-0.1.0.dist-info/licenses/LICENSE,sha256=vUkf6nsiiAu8kQuDkDVPwiP3XBYOrTmN7hiJFKiC0Lc,1089
+pagebar-0.1.0.dist-info/RECORD,,

pagebar-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pagebar-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stéfane Fermigier / Abilian SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.