Metadata-Version: 2.4
Name: pagebar
Version: 0.2.0
Summary: A tiny prod-safe perf footer & toolbar for ASGI apps.
Keywords: asgi,performance,monitoring,footer,sql
Author: Stéfane Fermigier
Author-email: Stéfane Fermigier <sf@fermigier.com>
License-Expression: MIT
License-File: 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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Framework :: AsyncIO
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: flask>=2 ; extra == 'flask'
Requires-Dist: sqlalchemy>=2.0 ; extra == 'sqlalchemy'
Requires-Python: >=3.10
Project-URL: Homepage, https://pagebar.lab.abilian.com/
Provides-Extra: flask
Provides-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
```

![pagebar's footer pill](docs/src/images/pill.png)

Click it to expand the full panel:

![The expanded pagebar panel](docs/src/images/panel-expanded.png)

The text is selectable, and the copy icon in the pill puts every field on the clipboard. Browsers only expose the clipboard on https and localhost, so the icon is hidden elsewhere.

## Install

```sh
pip install pagebar              # core only
pip install pagebar[sqlalchemy]  # with SQL query counter
pip install pagebar[flask]       # Flask (WSGI) integration
```

## 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.

### Flask (WSGI)

Flask isn't ASGI, so there's no middleware — the `pagebar[flask]` extra ships a small extension that wires the same data collection into Flask's request lifecycle:

```python
from flask import Flask
from pagebar.flask import Pagebar

app = Flask(__name__)
Pagebar(app, package="my-app", unsafe=app.debug)
```

Same knobs as `PagebarMiddleware`. `pagebar_html` is registered as a Jinja global, so the template usage below works unchanged. `enabled`/`unsafe` callables receive the Flask `request` (the ASGI versions get the connection scope).

### 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 cursor-execute listeners (if installed): count, total time, share of Time |
| Other   | Time minus SQL time; flagged `⚠` from 500ms, in the pill too      |
| Request | method + path                                                     |
| Peak memory | `resource.getrusage().ru_maxrss` — highest RSS so far in MiB, not current |
| 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.

**Other** is what makes a slow page legible without SQL to blame: `Time: 2.31s`, `SQL: 16 queries, 7ms (<1%)`, `Other: 2.30s ⚠` says at a glance to stop reading the SQL report.

SQL time stops when `execute` returns, so time spent fetching rows counts under **Other**. That's usually small with drivers that load the whole result during `execute`, such as psycopg's default cursor. SQLite and server-side cursors do the work during the fetch, so a slow query there can show almost no SQL time.

## 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
    time_budget=1.0,  # >0 → log a WARNING when a request takes longer (seconds)
)
```

## Unsafe mode

In dev, you usually *want* to see the SQL text. Flip `unsafe=True` and the panel gains a SQL summary with a **SQL details** button. That opens a full-screen modal with two sections: a **grouped N+1 report** (each unique statement with its repeat count and total time, repeats flagged in red — the panel also shows how many queries were redundant), and the **full list** of every query in order with bound parameters and per-statement timing. The modal text is selectable, and a **Copy report** button puts a self-contained N+1 summary on the clipboard — request line, totals, and each unique statement with its call count — ready to paste into a bug report:

```
pagebar SQL report — GET /widgets
21 queries, 2 unique, 19 redundant (possible N+1)

20×  0.0ms  SELECT name FROM widget WHERE id = ?
 1×  0.1ms  SELECT id FROM widget
```

![The expanded panel in unsafe mode, with the SQL summary and details button](docs/src/images/panel-unsafe.png)

![The unsafe-mode SQL modal: grouped N+1 report above a collapsible full-query list](docs/src/images/sql-modal.png)

Unsafe mode also samples stacks while the request runs, every 10ms, so a slow page names the code responsible. When **Other** is flagged, the panel shows the most frequent stacks, keeping the innermost frame and the application frames above it, with Jinja frames on their template line. **Loop blocked** appears when the event loop couldn't run anything else, the difference between one slow request and a frozen server:

```
Time: 2.15s
SQL: 16 queries, 7ms (<1%)
Other: 2.14s ⚠
Loop blocked: 2.14s ⚠

97% of samples in obstore/store.py:281 head
  ← front_app/storage.py:217 _exists
  ← front_app/storage.py:121 logo_url
  ← templates/pages/solutions/detail.html:55 block_content
```

The copy icon includes these stacks, and `time_budget` adds them to its log line. The sampling thread only exists while a sampled request is in flight. Concurrent requests see each other's stacks. If no code was running, the panel says the time went to an await.

A red `UNSAFE` badge in the pill makes the mode obvious.

![The pill in unsafe mode, with a red UNSAFE badge](docs/src/images/pill-unsafe.png)

```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`). On a skipped request, `pagebar_html()` returns an empty string, so the template needs no condition. It does the same if the middleware isn't installed.

## 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 full profiler. One ASGI middleware, one helper function and an optional Flask extension.

## License

MIT.
