smartdump 0.1.0

Real-time variable dumper for FastAPI — inspired by Laradumps

⚡ SmartDebugger

Real-time variable dump viewer for FastAPI — inspired by Laradumps.

Call sd(variable) anywhere in your FastAPI app and see it appear instantly in the browser.

---

Quick start

1. Install dependencies

pip install fastapi uvicorn requests

2. Start the debugger server

python run.py

Open http://localhost:8765 in your browser.

3. Use sd() in your FastAPI app

from client import ds

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = db.get_user(user_id)
    sd(user, label="user from DB")          # dumps to the UI, non-blocking
    return user

---

Project structure

smart_debugger/
├── client/          # Python client library (the sd() function)
│   ├── __init__.py
│   └── ds.py
├── server/          # FastAPI dump server
│   ├── __init__.py
│   ├── app.py       # Routes: POST /dump, GET /dumps, WS /ws
│   └── manager.py   # WebSocket connection manager
├── static/          # Web UI (vanilla JS, no build step)
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── example/
│   └── app.py       # Demo FastAPI app
├── run.py           # Server launcher
└── pyproject.toml

---

sd() reference

sd(data, label=None, level="info")

Parameter	Type	Default	Description
data	any	—	Any Python value to inspect
label	str	None	Human-readable name shown in the UI
level	str	"info"	One of info, debug, warning, error

Returns data unchanged, so you can inline the call:

return sd(result, "final result")

Configuration

from client import configure

configure(
    server_url="http://localhost:8765",  # default
    timeout=1.0,                         # seconds — kept short
    enabled=True,                        # set False in production
)

---

UI features

• Real-time WebSocket feed
• Collapsible JSON tree viewer (auto-collapses at depth 3)
• Level badges: info / debug / warning / error
• Filter by level and free-text search (label, file, value)
• Sort newest / oldest
• Copy-to-clipboard button
• File + line number + function name for every dump
• Dark mode by default

---

Example routes (demo app)

# Start server
python run.py

# Start demo app in another terminal
uvicorn example.app:app --port 8000 --reload

# Hit the routes and watch the UI
curl http://localhost:8000/
curl http://localhost:8000/users/42
curl http://localhost:8000/error
curl -X POST http://localhost:8000/items \
     -H "Content-Type: application/json" \
     -d '{"name": "widget", "price": 9.99}'
curl http://localhost:8000/products

---

How it works

FastAPI app          SmartDebugger server        Browser
    │                        │                      │
    │  sd(data)              │                      │
    │─── POST /dump ────────>│                      │
    │   (daemon thread)      │── WS broadcast ─────>│
    │                        │                      │ (live update)
    │  (request continues)   │                      │

1. sd() captures the caller's file/line/function via inspect.
2. It serialises the value and fires a POST request on a daemon thread — completely non-blocking.
3. The server stores the dump in a deque(maxlen=200) and broadcasts it to all connected WebSocket clients.
4. The browser receives the payload and renders it as a collapsible JSON tree.

If the server is not running, sd() silently does nothing — it never crashes your app.

---

Disabling in production

import os
from client import configure

configure(enabled=os.getenv("DEBUG", "false").lower() == "true")