pagebar 0.1.0__tar.gz

pagebar-0.1.0/.builds/alpine.yml

@@ -0,0 +1,26 @@
+image: alpine/latest
+packages:
+  - uv
+  - gcc
+  - python3-dev
+
+secrets:
+  - b88a4c2c-944c-42a6-9fbb-7483049c458a
+
+sources:
+  - git@git.sr.ht:~sfermigier/pagebar
+
+tasks:
+  - install: |
+      cd pagebar
+      uv sync
+  - test: |
+      cd pagebar
+      uv run pytest -q --tb=short
+  - lint: |
+      cd pagebar
+      uv run ruff check
+      uv run ty check src
+  - nox: |
+      cd pagebar
+      uvx nox

pagebar-0.1.0/.builds/ubuntu-2404.yml

@@ -0,0 +1,37 @@
+# Copyright (c) 2024, Abilian SAS
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+image: ubuntu/24.04
+
+secrets:
+  - b88a4c2c-944c-42a6-9fbb-7483049c458a
+
+
+packages:
+  # Build tools
+  - software-properties-common
+  - build-essential
+  # Python is 3.12
+  - python3-dev
+  - python3-pip
+  # Extra
+  - nodejs
+
+tasks:
+  - setup: |
+      echo "Building on Ubuntu 2404"
+      sudo pip install --break-system-packages -U uv nox
+      cd pagebar
+      uv sync
+
+  - test: |
+      cd pagebar
+      uv run pytest -q --tb=short
+  - lint: |
+      cd pagebar
+      uv run ruff check
+      # uv run ty check src
+  - nox: |
+      cd pagebar
+      uvx nox

pagebar-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI (nox)
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install uv and nox
+        run: pip install uv nox
+      - name: Run checks (lint, format, typecheck)
+        run: nox -s check -P 3.12
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv and nox
+        run: pip install uv nox
+      - name: Run tests
+        run: nox -s test -p ${{ matrix.python-version }}

pagebar-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+
+# Virtual environments
+.venv
+.python-version
+
+# Local / secrets / tmp
+.envrc
+/sandbox/

pagebar-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+
+- repo: https://github.com/charliermarsh/ruff-pre-commit
+  rev: 'v0.14.11'
+  hooks:
+    - id: ruff
+    - id: ruff-format
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+    # Generic
+    - id: check-added-large-files
+    - id: fix-byte-order-marker
+    - id: check-case-conflict
+    - id: check-executables-have-shebangs
+    - id: check-merge-conflict
+    - id: check-symlinks
+    # Basic syntax checks
+    - id: check-ast
+    - id: check-json
+    - id: check-toml
+    - id: check-xml
+    - id: check-yaml
+    # Security
+    - id: detect-private-key
+    # Whitespace
+    - id: end-of-file-fixer
+    - id: mixed-line-ending
+    - id: trailing-whitespace
+    # Misc Python
+    - id: debug-statements
+    - id: check-docstring-first

pagebar-0.1.0/CHANGES.md

@@ -0,0 +1,12 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [VERSION] - DATE
+
+### Changed
+
+### Fixed
+
+### Documentation

pagebar-0.1.0/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.

pagebar-0.1.0/Makefile

@@ -0,0 +1,35 @@
+.PHONY: all test build format check lint clean
+
+all: test lint
+
+check: lint
+
+lint:
+	uv run --active ruff check
+	uv run --active ruff format --check
+	uv run --active ty check src
+	uv run --active pyrefly check src
+	uv run --active mypy src
+	# uv run --active mypy --strict src
+
+format:
+	uv run --active ruff format src tests
+	uv run --active ruff check src tests --fix
+	uv run --active ruff format src tests
+
+test:
+	uv run pytest
+
+test-cov:
+	uv run pytest --cov=pagebar --cov-report=html --cov-report=term tests
+
+clean:
+	rm -rf .pytest_cache .ruff_cache dist build __pycache__ .mypy_cache \
+		.coverage htmlcov .coverage.* *.egg-info
+	adt clean
+
+build: clean
+	uv build
+
+publish: build
+	uv publish

pagebar-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,134 @@
+# 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/demo/README.md

@@ -0,0 +1,40 @@
+# pagebar demo
+
+A 90-line Starlette app exercising every pagebar feature.
+
+## Run
+
+```sh
+cd sandbox/pagebar
+uv sync --group demo
+uv run uvicorn demo.app:app --reload
+```
+
+Then open <http://127.0.0.1:8000>.
+
+## What it shows
+
+| Route       | What's happening                                                       |
+|-------------|------------------------------------------------------------------------|
+| `/`         | One SQL query — the baseline                                           |
+| `/list`     | 21 SQL queries (intentional N+1) — watch the counter climb             |
+| `/heavy`    | 10 queries — over the `query_budget=5`, check the server log for the WARNING |
+| `/api/json` | JSON endpoint — bar is hidden via `enabled=` callback                  |
+
+## Unsafe mode
+
+Run with `DEBUG=1` to flip `unsafe=True`:
+
+```sh
+DEBUG=1 uv run uvicorn demo.app:app --reload
+```
+
+A red `UNSAFE` badge appears in the pill, and the panel now lists each SQL statement with parameters + ms timing. Don't run this in prod.
+
+Click the pill bottom-right to open the panel. Press <kbd>Esc</kbd> or click the pill again to close. State persists across navigation via `localStorage`.
+
+## What to inspect
+
+- `demo/app.py:73` — `enabled=` callable filters out `/api/*`
+- `demo/app.py:74` — `query_budget=5` triggers WARNING on `/heavy`
+- View source on any page — note the single inlined `<style>` + `<script>`, no external assets, no leaked SQL text

pagebar-0.1.0/demo/app.py

@@ -0,0 +1,108 @@
+"""Minimal Starlette demo: SQLite + SQLAlchemy + pagebar.
+
+Run it::
+
+    cd sandbox/pagebar
+    uv run --group demo uvicorn demo.app:app --reload
+
+Then open http://127.0.0.1:8000.
+"""
+
+from __future__ import annotations
+
+import os
+from html import escape
+
+from sqlalchemy import create_engine, text
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.responses import HTMLResponse
+from starlette.routing import Route
+
+from pagebar import PagebarMiddleware, pagebar_html
+
+# In-memory DB seeded once so the demo has something to query.
+ENGINE = create_engine("sqlite:///:memory:")
+with ENGINE.begin() as conn:
+    conn.execute(text("CREATE TABLE widget (id INTEGER PRIMARY KEY, name TEXT)"))
+    conn.execute(
+        text("INSERT INTO widget (name) VALUES (:n)"),
+        [{"n": f"widget {i}"} for i in range(20)],
+    )
+
+
+PAGE = """<!doctype html>
+<html><head><meta charset="utf-8"><title>pagebar demo — {title}</title>
+<style>
+body{{font:14px/1.5 system-ui,sans-serif;max-width:640px;margin:2rem auto;padding:0 1rem}}
+a{{margin-right:1rem}} ul{{margin-top:1rem}}
+</style></head><body>
+<h1>{title}</h1>
+<nav>
+  <a href="/">Home (1 query)</a>
+  <a href="/list">List (N queries)</a>
+  <a href="/heavy">Heavy (over budget)</a>
+  <a href="/api/json">JSON (no bar)</a>
+</nav>
+{body}
+{bar}
+</body></html>
+"""
+
+
+def _render(title: str, body: str) -> HTMLResponse:
+    return HTMLResponse(PAGE.format(title=title, body=body, bar=pagebar_html()))
+
+
+async def home(_request):
+    with ENGINE.connect() as c:
+        n = c.execute(text("SELECT count(*) FROM widget")).scalar()
+    return _render("Home", f"<p>{n} widgets in DB. Click the pill bottom-right.</p>")
+
+
+async def list_widgets(_request):
+    # Intentionally noisy: one query per row to show the SQL counter climb.
+    with ENGINE.connect() as c:
+        ids = [r[0] for r in c.execute(text("SELECT id FROM widget"))]
+        rows = [
+            c.execute(text("SELECT name FROM widget WHERE id = :i"), {"i": i}).scalar()
+            for i in ids
+        ]
+    items = "".join(f"<li>{escape(r)}</li>" for r in rows)
+    return _render("List", f"<ul>{items}</ul>")
+
+
+async def heavy(_request):
+    # Trip the query_budget WARNING (set to 5 below).
+    with ENGINE.connect() as c:
+        for _ in range(10):
+            c.execute(text("SELECT 1"))
+    return _render("Heavy", "<p>Just ran 10 queries — check the server log.</p>")
+
+
+async def api_json(_request):
+    # JSON endpoints get the bar hidden via `enabled`.
+    return HTMLResponse('{"ok": true}', media_type="application/json")
+
+
+def _show_bar(scope: dict) -> bool:
+    return not scope["path"].startswith("/api/")
+
+
+app = Starlette(
+    routes=[
+        Route("/", home),
+        Route("/list", list_widgets),
+        Route("/heavy", heavy),
+        Route("/api/json", api_json),
+    ],
+    middleware=[
+        Middleware(
+            PagebarMiddleware,
+            package="pagebar",
+            enabled=_show_bar,
+            unsafe=bool(os.getenv("DEBUG")),
+            query_budget=5,
+        )
+    ],
+)