smartdump 0.1.0__tar.gz

smartdump-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: smartdump
+Version: 0.1.0
+Summary: Real-time variable dumper for FastAPI — inspired by Laradumps
+License: MIT
+Keywords: fastapi,debug,dump,developer-tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# ⚡ SmartDebugger
+
+Real-time variable dump viewer for FastAPI — inspired by [Laradumps](https://laradumps.dev).
+
+Call `sd(variable)` anywhere in your FastAPI app and see it appear instantly in the browser.
+
+---
+
+## Quick start
+
+### 1. Install dependencies
+
+```bash
+pip install fastapi uvicorn requests
+```
+
+### 2. Start the debugger server
+
+```bash
+python run.py
+```
+
+Open **http://localhost:8765** in your browser.
+
+### 3. Use `sd()` in your FastAPI app
+
+```python
+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
+
+```python
+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:
+
+```python
+return sd(result, "final result")
+```
+
+### Configuration
+
+```python
+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)
+
+```bash
+# 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
+
+```python
+import os
+from client import configure
+
+configure(enabled=os.getenv("DEBUG", "false").lower() == "true")
+```

smartdump-0.1.0/README.md

@@ -0,0 +1,156 @@
+# ⚡ SmartDebugger
+
+Real-time variable dump viewer for FastAPI — inspired by [Laradumps](https://laradumps.dev).
+
+Call `sd(variable)` anywhere in your FastAPI app and see it appear instantly in the browser.
+
+---
+
+## Quick start
+
+### 1. Install dependencies
+
+```bash
+pip install fastapi uvicorn requests
+```
+
+### 2. Start the debugger server
+
+```bash
+python run.py
+```
+
+Open **http://localhost:8765** in your browser.
+
+### 3. Use `sd()` in your FastAPI app
+
+```python
+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
+
+```python
+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:
+
+```python
+return sd(result, "final result")
+```
+
+### Configuration
+
+```python
+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)
+
+```bash
+# 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
+
+```python
+import os
+from client import configure
+
+configure(enabled=os.getenv("DEBUG", "false").lower() == "true")
+```

smartdump-0.1.0/client/__init__.py

@@ -0,0 +1,3 @@
+from .sd import sd, configure
+
+__all__ = ["sd", "configure"]

smartdump-0.1.0/client/sd.py

@@ -0,0 +1,156 @@
+"""
+SmartDebugger client — ds() function.
+
+Usage:
+    from client import sd
+
+    sd(my_var)
+    sd(my_var, label="user object")
+    sd(my_var, label="error", level="error")
+
+Works in both sync and async FastAPI routes. Non-blocking.
+"""
+import inspect
+import json
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+import requests
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+_config = {
+    "server_url": "http://localhost:8765",
+    "timeout": 1.0,   # seconds — kept short so it never blocks
+    "enabled": True,
+}
+
+def configure(
+    server_url: str = "http://localhost:8765",
+    timeout: float = 1.0,
+    enabled: bool = True,
+) -> None:
+    """Override default ds() configuration."""
+    _config["server_url"] = server_url.rstrip("/")
+    _config["timeout"] = timeout
+    _config["enabled"] = enabled
+    
+# ---------------------------------------------------------------------------
+# Serialisation helpers
+# ---------------------------------------------------------------------------
+
+def _safe_serialize(obj: Any) -> Any:
+    """
+    Recursively convert an arbitrary Python object into something JSON-safe.
+    Falls back to repr() for unrecognised types.
+    """
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+
+    if isinstance(obj, dict):
+        return {str(k): _safe_serialize(v) for k, v in obj.items()}
+
+    if isinstance(obj, (list, tuple, set, frozenset)):
+        return [_safe_serialize(item) for item in obj]
+
+    if isinstance(obj, bytes):
+        try:
+            return obj.decode("utf-8")
+        except UnicodeDecodeError:
+            return obj.hex()
+
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+
+    if isinstance(obj, BaseException):
+        return {
+            "__exception__": type(obj).__name__,
+            "message": str(obj),
+            "args": [_safe_serialize(a) for a in obj.args],
+        }
+
+    # Dataclasses, Pydantic models, plain objects
+    if hasattr(obj, "__dict__"):
+        return {
+            "__type__": type(obj).__qualname__,
+            **{k: _safe_serialize(v) for k, v in obj.__dict__.items()
+               if not k.startswith("_")},
+        }
+
+    # Anything else → safe string
+    return repr(obj)
+
+
+def _build_payload(
+    data: Any,
+    label: Optional[str],
+    level: str,
+    caller_frame,
+) -> dict:
+    filename = caller_frame.f_code.co_filename
+    return {
+        "id": str(uuid.uuid4()),
+        "label": label,
+        "level": level,
+        "type": type(data).__name__,
+        "data": _safe_serialize(data),
+        "meta": {
+            "file": filename,
+            "line": caller_frame.f_lineno,
+            "function": caller_frame.f_code.co_name,
+        },
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Background sender (daemon thread → never blocks the request lifecycle)
+# ---------------------------------------------------------------------------
+
+def _send_to_server(payload: dict) -> None:
+    try:
+        requests.post(
+            f"{_config['server_url']}/dump",
+            json=payload,
+            timeout=_config["timeout"],
+        )
+    except Exception:
+        # Silently ignore — server may not be running; never crash the app
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def sd(
+    data: Any,
+    label: Optional[str] = None,
+    level: str = "info",
+) -> Any:
+    """
+    SmartDebugger — send *data* to the SmartDebugger viewer.
+
+    Args:
+        data:   Any Python value to inspect.
+        label:  Optional human-readable label shown in the UI.
+        level:  One of "info" | "debug" | "warning" | "error".
+
+    Returns:
+        *data* unchanged, so you can inline the call:
+        ``return sd(result, "final result")``
+    """
+    if not _config["enabled"]:
+        return data
+
+    # Capture the caller's frame *before* spawning a thread
+    caller_frame = inspect.currentframe().f_back
+    payload = _build_payload(data, label, level, caller_frame)
+
+    # Fire-and-forget on a daemon thread — works in sync and async contexts
+    threading.Thread(target=_send_to_server, args=(payload,), daemon=True).start()
+
+    return data

smartdump-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smartdump"
+version = "0.1.0"
+description = "Real-time variable dumper for FastAPI — inspired by Laradumps"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["fastapi", "debug", "dump", "developer-tools"]
+
+dependencies = [
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.29.0",
+    "requests>=2.31.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "httpx>=0.27.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+smart-debugger = "run:main"
+smartdebug = "run:cli"
+
+[tool.setuptools.packages.find]
+include = ["client*", "server*"]
+exclude = ["example*", "tests*"]

smartdump-0.1.0/server/app.py

@@ -0,0 +1,95 @@
+"""
+SmartDebugger server.
+
+Endpoints:
+  POST /dump        — receive a dump from the client library
+  GET  /dumps       — return all stored dumps (newest first)
+  GET  /dumps/clear — clear all stored dumps
+  WS   /ws          — real-time WebSocket feed for the UI
+  GET  /            — serve the web UI
+  GET  /health      — health check
+"""
+
+import json
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from .manager import ConnectionManager
+
+# ---------------------------------------------------------------------------
+# App setup
+# ---------------------------------------------------------------------------
+
+app = FastAPI(title="SmartDebugger Server", docs_url=None, redoc_url=None)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# In-memory store — keep the 200 most recent dumps
+MAX_DUMPS = 200
+_dumps: deque[dict] = deque(maxlen=MAX_DUMPS)
+
+manager = ConnectionManager()
+
+STATIC_DIR = Path(__file__).parent.parent / "static"
+
+
+# ---------------------------------------------------------------------------
+# Routes
+# ---------------------------------------------------------------------------
+
+@app.get("/health")
+async def health() -> dict:
+    return {"status": "ok", "clients": manager.client_count, "dumps": len(_dumps)}
+
+
+@app.post("/dump")
+async def receive_dump(payload: dict) -> dict:
+    """Accept a dump from the client library and broadcast it to all UI tabs."""
+    _dumps.appendleft(payload)
+    await manager.broadcast({"event": "dump", "payload": payload})
+    return {"ok": True}
+
+
+@app.get("/dumps")
+async def get_dumps() -> list:
+    """Return all stored dumps, newest first."""
+    return list(_dumps)
+
+
+@app.delete("/dumps")
+async def clear_dumps() -> dict:
+    """Clear all stored dumps and notify connected clients."""
+    _dumps.clear()
+    await manager.broadcast({"event": "clear"})
+    return {"ok": True}
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(ws: WebSocket) -> None:
+    await manager.connect(ws)
+    try:
+        while True:
+            # Keep connection alive; client doesn't need to send anything
+            await ws.receive_text()
+    except WebSocketDisconnect:
+        manager.disconnect(ws)
+
+
+@app.get("/")
+async def serve_ui() -> FileResponse:
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+# Mount static files (JS, CSS) under /static
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")

smartdump-0.1.0/server/manager.py

@@ -0,0 +1,43 @@
+"""
+WebSocket connection manager.
+Keeps track of every connected browser tab and broadcasts payloads to all.
+"""
+
+import asyncio
+import json
+from typing import Set
+
+from fastapi import WebSocket
+
+
+class ConnectionManager:
+    def __init__(self) -> None:
+        self._clients: Set[WebSocket] = set()
+
+    async def connect(self, ws: WebSocket) -> None:
+        await ws.accept()
+        self._clients.add(ws)
+
+    def disconnect(self, ws: WebSocket) -> None:
+        self._clients.discard(ws)
+
+    async def broadcast(self, payload: dict) -> None:
+        """Send *payload* to every connected client, removing dead connections."""
+        if not self._clients:
+            return
+
+        message = json.dumps(payload)
+        dead: list[WebSocket] = []
+
+        for client in list(self._clients):
+            try:
+                await client.send_text(message)
+            except Exception:
+                dead.append(client)
+
+        for ws in dead:
+            self._clients.discard(ws)
+
+    @property
+    def client_count(self) -> int:
+        return len(self._clients)

smartdump-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smartdump-0.1.0/smartdump.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: smartdump
+Version: 0.1.0
+Summary: Real-time variable dumper for FastAPI — inspired by Laradumps
+License: MIT
+Keywords: fastapi,debug,dump,developer-tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# ⚡ SmartDebugger
+
+Real-time variable dump viewer for FastAPI — inspired by [Laradumps](https://laradumps.dev).
+
+Call `sd(variable)` anywhere in your FastAPI app and see it appear instantly in the browser.
+
+---
+
+## Quick start
+
+### 1. Install dependencies
+
+```bash
+pip install fastapi uvicorn requests
+```
+
+### 2. Start the debugger server
+
+```bash
+python run.py
+```
+
+Open **http://localhost:8765** in your browser.
+
+### 3. Use `sd()` in your FastAPI app
+
+```python
+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
+
+```python
+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:
+
+```python
+return sd(result, "final result")
+```
+
+### Configuration
+
+```python
+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)
+
+```bash
+# 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
+
+```python
+import os
+from client import configure
+
+configure(enabled=os.getenv("DEBUG", "false").lower() == "true")
+```

smartdump-0.1.0/smartdump.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+client/__init__.py
+client/sd.py
+server/__init__.py
+server/app.py
+server/manager.py
+smartdump.egg-info/PKG-INFO
+smartdump.egg-info/SOURCES.txt
+smartdump.egg-info/dependency_links.txt
+smartdump.egg-info/entry_points.txt
+smartdump.egg-info/requires.txt
+smartdump.egg-info/top_level.txt

smartdump-0.1.0/smartdump.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

smartdump-0.1.0/smartdump.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+smart-debugger = run:main
+smartdebug = run:cli

smartdump-0.1.0/smartdump.egg-info/requires.txt

@@ -0,0 +1,8 @@
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+requests>=2.31.0
+
+[dev]
+httpx>=0.27.0
+pytest>=8.0.0
+pytest-asyncio>=0.23.0

smartdump-0.1.0/smartdump.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+client
+server