lightlogger 0.1.0__py3-none-any.whl

lightlogger/__init__.py

@@ -0,0 +1,249 @@
+"""lightlogger: a live web dashboard for your Python logs. Zero dependencies."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+import webbrowser
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from lightlogger.buffer import LogBuffer, LogRecord, _current_group_id, capture_caller
+from lightlogger.handler import LightloggerHandler
+from lightlogger.server import LightloggerServer, create_server, serve_in_background
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "start",
+    "stop",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "var",
+    "request",
+    "group",
+    "help",
+]
+
+_HELP_TEXT = """\
+lightlogger -- live web dashboard for your Python logs
+========================================================
+
+  pip install lightlogger
+
+Quickstart
+----------
+  import lightlogger
+  lightlogger.start()
+
+That's it. Open the printed URL (default http://127.0.0.1:4356) and watch
+your logs stream in live, in a dark, searchable dashboard.
+
+Public API
+----------
+
+  start(port=4356, host="127.0.0.1", max_logs=5000,
+        capture_logging=True, open_browser=False)
+      Starts the dashboard server on a background thread. Calling it again
+      while already running is a no-op, not an error.
+          lightlogger.start(port=8080, open_browser=True)
+
+  stop()
+      Stops the server and detaches the logging handler. Mostly useful for
+      tests and notebooks -- most scripts never need to call this.
+          lightlogger.stop()
+
+  debug(msg, data=None)
+      Logs a debug-level message (grey in the UI).
+          lightlogger.debug("cache miss", data={"key": "user:42"})
+
+  info(msg, data=None)
+      Logs an info-level message (blue in the UI).
+          lightlogger.info("user logged in")
+
+  warn(msg, data=None)
+      Logs a warn-level message (yellow in the UI).
+          lightlogger.warn("retrying after timeout")
+
+  error(msg, data=None)
+      Logs an error-level message (red in the UI).
+          lightlogger.error("payment failed", data={"order_id": 123})
+
+  var(name, value)
+      Logs any variable as an expandable JSON blob under `name`.
+          lightlogger.var("cart", cart_dict)
+
+  request(method, url, status, duration_ms)
+      Logs one HTTP request/response as a single formatted line.
+          lightlogger.request("GET", "/api/users", 200, 12.4)
+
+  group(name)
+      Context manager that groups related log lines into a collapsible
+      tree in the UI. Nests, and is safe across threads and asyncio tasks
+      (each gets its own independent group context).
+          with lightlogger.group("process_order #4821"):
+              lightlogger.info("validating cart")
+              lightlogger.info("charging payment", data={"amount": 49.99})
+              with lightlogger.group("send_notifications"):
+                  lightlogger.info("email sent")
+
+Capturing stdlib `logging`
+---------------------------
+start(capture_logging=True) is the default: it attaches a handler to the
+root logger, so your existing `logging` calls -- and third-party
+libraries' -- appear in the dashboard automatically, with zero code
+changes.
+
+Gotcha: Python's root logger defaults to level WARNING. A plain
+`logging.info(...)` call will NOT appear unless your app has already
+raised the level itself, e.g. `logging.basicConfig(level=logging.INFO)`.
+lightlogger deliberately never forces the root logger's level open --
+doing so would also unmute your app's OTHER existing handlers, which is
+more disruptive than "zero code changes" is meant to be. `.warning()` and
+above always show up out of the box; `.debug()`/`.info()` need that one
+extra line if you want them too.
+
+Not for production
+-------------------
+Binds to 127.0.0.1 only by default. This is a local development tool, not
+a production observability system.
+
+Docs & source
+-------------
+  https://github.com/Rahuwale123/lightlogger
+"""
+
+_buffer = LogBuffer(maxlen=5000)
+_httpd: LightloggerServer | None = None
+_thread: threading.Thread | None = None
+_logging_handler: LightloggerHandler | None = None
+
+
+def _emit(level: str, message: str, data: Any = None, *, logger_name: str = "lightlogger") -> None:
+    # skip=3: capture_caller's own frame, this frame, and the public
+    # debug/info/warn/error/var/request wrapper -> lands on the user's call site.
+    file, line = capture_caller(skip=3)
+    record: LogRecord = {
+        "time": time.time(),
+        "level": level,
+        "message": message,
+        "data": data,
+        "file": file,
+        "line": line,
+        "logger_name": logger_name,
+        "group_id": None,
+        "parent_group_id": _current_group_id.get(),
+    }
+    _buffer.add(record)
+
+
+def start(
+    port: int = 4356,
+    host: str = "127.0.0.1",
+    max_logs: int = 5000,
+    capture_logging: bool = True,
+    open_browser: bool = False,
+) -> None:
+    global _httpd, _thread, _logging_handler
+    if _httpd is not None:
+        return  # already running; start() is idempotent, not an error
+
+    _buffer.set_maxlen(max_logs)
+
+    if host == "0.0.0.0":  # noqa: S104
+        print(
+            "lightlogger WARNING: binding to 0.0.0.0 exposes your logs to your "
+            "whole network. Only do this if you mean it."
+        )
+
+    _httpd = create_server(_buffer, host, port)
+    _thread = serve_in_background(_httpd)
+    bound_port = _httpd.server_address[1]
+    print(f"lightlogger UI → http://{host}:{bound_port}")
+
+    if open_browser:
+        webbrowser.open(f"http://{host}:{bound_port}")
+
+    if capture_logging:
+        _logging_handler = LightloggerHandler(_buffer)
+        logging.getLogger().addHandler(_logging_handler)
+
+
+def stop() -> None:
+    global _httpd, _thread, _logging_handler
+    if _logging_handler is not None:
+        logging.getLogger().removeHandler(_logging_handler)
+        _logging_handler = None
+    if _httpd is None:
+        return
+    _httpd.shutdown()
+    _httpd.server_close()
+    _httpd = None
+    _thread = None
+
+
+def debug(msg: str, data: Any | None = None) -> None:
+    _emit("debug", msg, data)
+
+
+def info(msg: str, data: Any | None = None) -> None:
+    _emit("info", msg, data)
+
+
+def warn(msg: str, data: Any | None = None) -> None:
+    _emit("warn", msg, data)
+
+
+def error(msg: str, data: Any | None = None) -> None:
+    _emit("error", msg, data)
+
+
+def var(name: str, value: Any) -> None:
+    _emit("info", name, value)
+
+
+def request(method: str, url: str, status: int, duration_ms: float) -> None:
+    _emit(
+        "info",
+        f"{method} {url} {status} {duration_ms:.1f}ms",
+        {"method": method, "url": url, "status": status, "duration_ms": duration_ms},
+    )
+
+
+def help() -> None:
+    """Print a quick-reference cheatsheet of the public API to stdout."""
+    print(_HELP_TEXT)
+
+
+@contextmanager
+def group(name: str) -> Iterator[None]:
+    group_id = uuid.uuid4().hex
+    parent_group_id = _current_group_id.get()
+    # skip=3: capture_caller's own frame, this generator's frame (resumed by
+    # @contextmanager's __enter__ via next()), and contextlib's
+    # _GeneratorContextManager.__enter__ itself -> lands on the user's
+    # `with lightlogger.group(...):` call site. Verified empirically in
+    # tests/test_buffer.py (test_group_captures_caller_file_and_line).
+    file, line = capture_caller(skip=3)
+    record: LogRecord = {
+        "time": time.time(),
+        "level": "group",
+        "message": name,
+        "data": None,
+        "file": file,
+        "line": line,
+        "logger_name": "lightlogger",
+        "group_id": group_id,
+        "parent_group_id": parent_group_id,
+    }
+    _buffer.add(record)
+    token = _current_group_id.set(group_id)
+    try:
+        yield
+    finally:
+        _current_group_id.reset(token)

lightlogger/buffer.py

@@ -0,0 +1,89 @@
+"""Ring buffer and SSE client fan-out."""
+
+from __future__ import annotations
+
+import contextvars
+import sys
+import threading
+from collections import deque
+from queue import Queue
+from typing import Any, TypedDict
+
+
+class LogRecord(TypedDict):
+    time: float
+    level: str
+    message: str
+    data: Any
+    file: str
+    line: int
+    logger_name: str
+    group_id: str | None
+    parent_group_id: str | None
+
+
+def capture_caller(skip: int) -> tuple[str, int]:
+    # sys._getframe, not inspect.stack(): inspect.stack() reads source files
+    # off disk on every call, which is too slow for a logging hot path.
+    frame = sys._getframe(skip)
+    return frame.f_code.co_filename, frame.f_lineno
+
+
+# Holds "the current group id" per thread/async-task, not a plain module
+# global (which would leak across threads). Lives here rather than in
+# __init__.py because handler.py needs it too (so plain logging.info() calls
+# made inside a group() block nest correctly), and handler.py already
+# imports from buffer.py -- importing from __init__.py instead would risk a
+# circular import.
+_current_group_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "lightlogger_current_group_id", default=None
+)
+
+
+class LogBuffer:
+    """Bounded ring buffer of log records, with SSE client fan-out."""
+
+    def __init__(self, maxlen: int = 5000) -> None:
+        self._records: deque[LogRecord] = deque(maxlen=maxlen)
+        # One lock for records and subscribers alike: append() is atomic under
+        # the GIL on its own, but the subscriber set isn't, so a single lock
+        # keeps this simple rather than mixing locked and lock-free paths.
+        self._lock = threading.Lock()
+        self._subscribers: set[Queue[LogRecord]] = set()
+
+    def set_maxlen(self, maxlen: int) -> None:
+        # Rebuild in place rather than swap self._records for a fresh deque:
+        # deque(existing_deque, maxlen=N) already keeps only the newest N
+        # items, and callers who stashed a reference to this LogBuffer (e.g.
+        # future SSE subscribers) never observe a different object.
+        with self._lock:
+            self._records = deque(self._records, maxlen=maxlen)
+
+    def add(self, record: LogRecord) -> None:
+        with self._lock:
+            self._records.append(record)
+            subscribers = list(self._subscribers)
+        for subscriber in subscribers:
+            subscriber.put(record)
+
+    def snapshot(self) -> list[LogRecord]:
+        with self._lock:
+            return list(self._records)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._records.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._records)
+
+    def subscribe(self) -> Queue[LogRecord]:
+        subscriber: Queue[LogRecord] = Queue()
+        with self._lock:
+            self._subscribers.add(subscriber)
+        return subscriber
+
+    def unsubscribe(self, subscriber: Queue[LogRecord]) -> None:
+        with self._lock:
+            self._subscribers.discard(subscriber)

lightlogger/handler.py

@@ -0,0 +1,40 @@
+"""LightloggerHandler: logging.Handler subclass for capture_logging."""
+
+from __future__ import annotations
+
+import logging
+
+from lightlogger.buffer import LogBuffer, LogRecord, _current_group_id
+
+_LEVEL_NAMES = {
+    logging.DEBUG: "debug",
+    logging.INFO: "info",
+    logging.WARNING: "warn",
+    logging.ERROR: "error",
+    logging.CRITICAL: "error",  # only 4 UI colors exist; CRITICAL folds into "error"
+}
+
+
+class LightloggerHandler(logging.Handler):
+    """Mirrors stdlib `logging` records into a `LogBuffer` (and its SSE fan-out)."""
+
+    def __init__(self, buffer: LogBuffer) -> None:
+        super().__init__()
+        self._buffer = buffer
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            log_record: LogRecord = {
+                "time": record.created,
+                "level": _LEVEL_NAMES.get(record.levelno, "info"),
+                "message": record.getMessage(),
+                "data": None,
+                "file": record.pathname,
+                "line": record.lineno,
+                "logger_name": record.name,
+                "group_id": None,
+                "parent_group_id": _current_group_id.get(),
+            }
+            self._buffer.add(log_record)
+        except Exception:
+            self.handleError(record)

lightlogger/server.py

@@ -0,0 +1,147 @@
+"""ThreadingHTTPServer, daemon thread, and HTTP routes."""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+import sys
+import threading
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from queue import Empty
+from typing import Any
+
+from lightlogger import sse
+from lightlogger.buffer import LogBuffer
+
+# How long an /api/stream client blocks on its queue before it gets a
+# heartbeat comment instead. Also doubles as the heartbeat period.
+HEARTBEAT_INTERVAL_SECONDS = 15.0
+
+
+class LightloggerServer(ThreadingHTTPServer):
+    # SSE holds connections open indefinitely; without daemon threads per
+    # request, one slow client would starve every other route.
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def handle_error(self, request: Any, client_address: Any) -> None:
+        # An /api/stream client that goes away (tab closed, reconnect churn)
+        # can reset the connection at any point, including while a *later*,
+        # unrelated request is being read on a freshly accepted socket. The
+        # default handle_error() dumps a full traceback to stderr for that,
+        # which looks like a server bug when it's just a disconnected client
+        # -- same spirit as log_message() already staying quiet above.
+        exc_type = sys.exc_info()[0]
+        if exc_type is not None and issubclass(exc_type, (BrokenPipeError, ConnectionResetError)):
+            return
+        super().handle_error(request, client_address)
+
+
+def _make_handler(buffer: LogBuffer, heartbeat_interval: float) -> type[BaseHTTPRequestHandler]:
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, format: str, *args: object) -> None:
+            pass  # stay quiet on the user's stdout; they didn't ask for access logs
+
+        def do_GET(self) -> None:
+            if self.path == "/":
+                self._serve_index()
+            elif self.path == "/help":
+                self._serve_help()
+            elif self.path == "/api/logs":
+                self._serve_logs()
+            elif self.path == "/api/stream":
+                self._serve_stream()
+            else:
+                self.send_error(HTTPStatus.NOT_FOUND)
+
+        def do_POST(self) -> None:
+            if self.path == "/api/clear":
+                self._serve_clear()
+            else:
+                self.send_error(HTTPStatus.NOT_FOUND)
+
+        def _serve_clear(self) -> None:
+            buffer.clear()
+            self.send_response(HTTPStatus.OK)
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+
+        def _serve_index(self) -> None:
+            html = (importlib.resources.files("lightlogger") / "static" / "index.html").read_bytes()
+            self.send_response(HTTPStatus.OK)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(html)))
+            self.end_headers()
+            self.wfile.write(html)
+
+        def _serve_help(self) -> None:
+            html = (importlib.resources.files("lightlogger") / "static" / "help.html").read_bytes()
+            self.send_response(HTTPStatus.OK)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(html)))
+            self.end_headers()
+            self.wfile.write(html)
+
+        def _serve_logs(self) -> None:
+            # default=str: log `data` can be any Python object the caller passed in.
+            body = json.dumps(buffer.snapshot(), default=str).encode("utf-8")
+            self.send_response(HTTPStatus.OK)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _serve_stream(self) -> None:
+            self.send_response(HTTPStatus.OK)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-cache")
+            self.send_header("Connection", "keep-alive")
+            self.end_headers()
+
+            # BaseHTTPRequestHandler gives no clean "client closed the tab"
+            # signal for a response this long-lived, so disconnect is detected
+            # the standard way: attempt the write, and treat any failure
+            # (BrokenPipeError, ConnectionResetError, or a generic OSError) as
+            # the client having gone away. finally: unsubscribe() always runs,
+            # so a leaked subscriber queue can't accumulate per disconnect.
+            subscriber = buffer.subscribe()
+            try:
+                self.wfile.write(sse.format_retry())
+                self.wfile.flush()
+                while True:
+                    try:
+                        record = subscriber.get(timeout=heartbeat_interval)
+                    except Empty:
+                        payload = sse.format_heartbeat()
+                    else:
+                        payload = sse.format_event(record)
+                    self.wfile.write(payload)
+                    self.wfile.flush()
+            except (BrokenPipeError, ConnectionResetError, OSError):
+                pass
+            finally:
+                buffer.unsubscribe(subscriber)
+
+    return Handler
+
+
+def create_server(
+    buffer: LogBuffer,
+    host: str,
+    port: int,
+    heartbeat_interval: float = HEARTBEAT_INTERVAL_SECONDS,
+) -> LightloggerServer:
+    """Bind a server, auto-incrementing past `port` on OSError (port busy)."""
+    handler_cls = _make_handler(buffer, heartbeat_interval)
+    while True:
+        try:
+            return LightloggerServer((host, port), handler_cls)
+        except OSError:
+            port += 1
+
+
+def serve_in_background(httpd: LightloggerServer) -> threading.Thread:
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+    return thread

lightlogger/sse.py

@@ -0,0 +1,30 @@
+"""SSE framing helpers: exact wire format for text/event-stream responses.
+
+Kept separate from server.py so the wire format (double-newline framing,
+retry directive, heartbeat comment) is defined in exactly one place and can
+be unit-tested without spinning up a real HTTP server.
+"""
+
+from __future__ import annotations
+
+import json
+
+from lightlogger.buffer import LogRecord
+
+RETRY_MS = 3000
+
+
+def format_retry() -> bytes:
+    return f"retry: {RETRY_MS}\n\n".encode()
+
+
+def format_event(record: LogRecord) -> bytes:
+    # default=str: log `data` can be any Python object the caller passed in.
+    payload = json.dumps(record, default=str)
+    return f"data: {payload}\n\n".encode()
+
+
+def format_heartbeat() -> bytes:
+    # A comment line (leading colon) per the SSE spec: browsers/proxies ignore
+    # its content but the bytes on the wire keep the connection looking alive.
+    return b": ping\n\n"