lightlogger 0.1.0__tar.gz

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

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    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 package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src tests
+
+      - name: Check formatting with ruff
+        run: ruff format --check src tests
+
+      - name: Type check with mypy
+        run: mypy src/lightlogger
+
+      - name: Run tests with coverage
+        run: pytest -v --cov=lightlogger --cov-report=term-missing

lightlogger-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    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 build tool
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lightlogger-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / type-checking / linting caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

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

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

lightlogger-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Ideas (post-v1, not in scope for now)
+
+- Multiple UI layouts / themes beyond dark mode
+- AI-assisted log summarization
+- Auth/login for the dashboard
+- Flask/Django/FastAPI middleware integrations
+- Node.js port
+
+## [0.1.0] - 2026-09-09
+
+Initial release.
+
+### Added
+
+- `lightlogger.start()` / `stop()` — a `ThreadingHTTPServer` on a daemon thread, binding `127.0.0.1:4356` by default with automatic port fallback on conflict; `host="0.0.0.0"` is an explicit, loudly-warned opt-in.
+- `debug()` / `info()` / `warn()` / `error()` / `var()` / `request()` — write into a bounded in-memory ring buffer (`max_logs`, default 5000), with caller file/line captured via `sys._getframe` (never `inspect.stack()`).
+- `lightlogger.group(name)` — a context manager for nested log grouping, backed by `contextvars` for thread/async safety.
+- Zero-code `logging` capture: `start(capture_logging=True)` (the default) attaches a handler to the root logger, so existing and third-party `logging` calls appear automatically.
+- Live dashboard UI (`GET /`, single self-contained HTML file, no CDN): dark theme, level-colored rows, search box, level filter, pause/resume with no dropped records, click-to-expand detail panels, download-as-JSON, a collapsible group tree with per-group counts and a worst-level badge.
+- `GET /api/logs` (JSON backlog), `GET /api/stream` (Server-Sent Events, replacing polling), `POST /api/clear`.
+- `open_browser=True` opens the dashboard automatically on `start()`.
+- `lightlogger.help()` prints a full API cheatsheet to the terminal; `GET /help` serves the same reference as an offline HTML page, linked from the dashboard header.
+- 100% test coverage, `mypy --strict` clean, CI across Python 3.9–3.13, PyPI publishing via Trusted Publishing (OIDC) — no long-lived API token ever stored.

lightlogger-0.1.0/CLAUDE.md

@@ -0,0 +1,219 @@
+# CLAUDE.md — Developer Brief for "lightlogger"
+
+You (Claude Code) are the developer of this project. The owner is a solo student developer building this part-time. Follow this brief exactly. When in doubt, choose the simpler option.
+
+> **Naming note:** the product was originally conceived as "lightlog" but that name is taken on PyPI. The distribution/import name is **`lightlogger`** everywhere below (PyPI verified free on 2026-09-09).
+
+> **Scope amendment (post-Phase 6, 2026-09-09):** log grouping (`lightlogger.group(name)`) was added to the frozen v1 API as **Phase 6.5**, before Phase 7. This is a deliberate exception to golden rule "exactly this, nothing more" — the owner evaluated it as a real differentiator (no competing zero-dep local dashboard has nested log grouping) rather than scope creep, and chose to formalize it here rather than build it as an undocumented add-on. See the new API entry in section 5, the amended record structure in section 3, section 6.5, and Phase 6.5 in section 7.
+
+---
+
+## 1. WHAT WE ARE BUILDING
+
+**lightlogger** — a zero-dependency Python library that gives developers a live web dashboard for their application logs.
+
+Developer experience (this is sacred, never break it):
+
+```python
+pip install lightlogger
+```
+
+```python
+import lightlogger
+lightlogger.start()          # UI now live at http://127.0.0.1:4356
+lightlogger.info("user logged in")
+lightlogger.error("payment failed", data={"order_id": 123})
+lightlogger.var("cart", cart_dict)   # expandable JSON in UI
+```
+
+Two lines to a live, beautiful, dark-theme log dashboard in the browser. Zero config. Zero third-party dependencies. That is the entire product.
+
+**Why this wins (from competitive research):** No existing package does "import → background thread → live localhost web UI, zero config, zero deps." Logdy is a Go binary, Chronologer needs a separate server, cutelog needs PyQt, Logfire is closed-source cloud, lnav/klp are terminal-only, Django/Flask debug toolbars are framework-locked. Our moat = developer experience + zero dependencies + in-process capture.
+
+---
+
+## 2. GOLDEN RULES (NEVER VIOLATE)
+
+1. **ZERO third-party dependencies.** Python standard library ONLY. `dependencies = []` in pyproject.toml stays empty forever. If you ever feel you need a package — you don't; find the stdlib way.
+2. **Bind to `127.0.0.1` ONLY.** Never `0.0.0.0`. LAN exposure must be an explicit opt-in parameter (`host="0.0.0.0"`) that prints a loud warning when used. Logs are sensitive data.
+3. **Bounded memory.** All logs live in `collections.deque(maxlen=5000)` (configurable). The tool must NEVER be the reason a user's app runs out of RAM.
+4. **Never block the user's app.** Server runs in a daemon thread. Logging calls must return in microseconds. No disk I/O in the logging hot path.
+5. **Off unless started.** Nothing runs until the user calls `lightlogger.start()`. Document clearly: do not run in production.
+6. **Simple > clever.** Vanilla HTML/JS/CSS in ONE file for the UI. No React, no build step, no npm anywhere in v1.
+
+---
+
+## 3. HARD TECHNICAL REQUIREMENTS (from research)
+
+### Server
+- Use `http.server.ThreadingHTTPServer` (NOT plain `HTTPServer` — SSE holds connections open and would block a single-threaded server).
+- Subclass with `daemon_threads = True` and `allow_reuse_address = True`.
+- Run `serve_forever()` inside `threading.Thread(daemon=True)`.
+- Provide `lightlogger.stop()` → calls `httpd.shutdown()` + `server_close()` (needed for tests/notebooks).
+- Port: default 4356. On `OSError` (port busy), auto-increment to next free port. Always print the final URL to stdout: `lightlogger UI → http://127.0.0.1:4356`.
+
+### Live streaming (SSE, not websockets)
+- Endpoint `/api/stream` responds with headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`.
+- Each event: `data: <json>\n\n` (double newline is mandatory).
+- Send `retry: 3000` at connection start and a heartbeat comment line (`: ping\n\n`) every ~15s.
+- Fan-out pattern: each connected client gets its own `queue.Queue`. New log records get pushed to every client queue. Guard the client-queue set with `threading.Lock`.
+- Browser side is simply `new EventSource('/api/stream')`.
+
+### Ring buffer
+- `collections.deque(maxlen=N)`. `append()` is atomic in CPython, but take a lock when ITERATING (serving backlog to a new client).
+
+### Caller file/line capture — PERFORMANCE CRITICAL
+- **NEVER use `inspect.stack()`** — it reads source files from disk on every call. Forbidden in the hot path.
+- Use the stdlib logging approach: `sys._getframe()` / walk `frame.f_back`, read `frame.f_code.co_filename` and `frame.f_lineno`. Cheap attribute reads, no I/O.
+
+### stdlib logging integration (killer feature — must have in v1)
+- Ship `LightloggerHandler(logging.Handler)` whose `emit(record)` pushes into the buffer + SSE queues.
+- `lightlogger.start(capture_logging=True)` attaches it to the root logger → user's EXISTING `logging` calls and even third-party library logs appear in the UI with zero code changes.
+- Record structure (amended in Phase 6.5): `{time, level, message, data, file, line, logger_name, group_id, parent_group_id}`. `group_id`/`parent_group_id` are always-present keys (never omitted), typed `str | None` — every field defaults to `None` for code untouched by `group()`, so this is a value-level amendment, not a structural one. No `typing.NotRequired`/`typing_extensions` — that would violate zero-dependency on Python 3.9/3.10, where `NotRequired` doesn't exist in stdlib `typing`.
+
+### Log grouping (`lightlogger.group(name)`) — Phase 6.5
+- A context manager: `with lightlogger.group("process_order #123"): ...`. On enter, emits one group-marker record immediately (so even an empty group is visible); on exit, restores the previous group context. Nesting supported (a `group()` inside a `group()`).
+- A group-marker record is just a normal `LogRecord` with `group_id` set to a fresh id (e.g. `uuid.uuid4().hex`) and `message` set to the group's display name. Every OTHER record (marker or plain log) gets `parent_group_id` set to whatever group directly contains it (`None` if top-level) — this is how nesting and containment are reconstructed client-side, by walking `parent_group_id` chains.
+- Thread/async safety via `contextvars.ContextVar` (stdlib) holding "the current group id" — NOT a plain module global, which would leak across threads. Each thread that doesn't explicitly share context gets its own independent value; each asyncio `Task` gets its own copy at creation. This is what makes concurrent, non-interleaving grouping possible without extra locking.
+- Group-marker records stream over `/api/stream` and appear in `/api/logs` exactly like any other record — no special-casing needed in `buffer.py`/`server.py`, since `LogBuffer.add()` already treats every record uniformly.
+
+### Packaging the UI
+- One file: `src/lightlogger/static/index.html` (HTML + CSS + JS inline).
+- Read it at runtime with `importlib.resources.files("lightlogger") / "static" / "index.html"` — NEVER build paths from `__file__`.
+
+---
+
+## 4. FOLDER STRUCTURE (create exactly this — src layout)
+
+```
+lightlog/                        # workspace/repo root (kept as-is on disk)
+├── src/
+│   └── lightlogger/              # actual PyPI distribution + import name
+│       ├── __init__.py          # public API: start, stop, info, warn, error, debug, var, request
+│       ├── server.py            # ThreadingHTTPServer + daemon thread + routes
+│       ├── handler.py           # LightloggerHandler (logging.Handler subclass)
+│       ├── buffer.py            # ring buffer + SSE client fan-out
+│       ├── sse.py               # SSE framing helpers
+│       ├── py.typed             # empty PEP 561 marker
+│       └── static/
+│           └── index.html       # entire UI, single file
+├── tests/
+│   ├── test_buffer.py
+│   ├── test_handler.py
+│   └── test_server.py
+├── .github/workflows/
+│   ├── ci.yml                   # ruff + pytest, matrix Python 3.9–3.13
+│   └── publish.yml              # PyPI Trusted Publishing on GitHub Release
+├── assets/
+│   └── demo.gif                 # README demo (added later)
+├── pyproject.toml               # PEP 621
+├── README.md
+├── CHANGELOG.md                 # Keep a Changelog format
+├── CONTRIBUTING.md
+├── LICENSE                      # MIT
+├── .pre-commit-config.yaml      # ruff lint + format
+└── .gitignore
+```
+
+### pyproject.toml requirements
+- Build backend: **Hatchling** (auto-detects src layout, includes package data).
+- `[project]`: name `lightlogger`, version `0.1.0`, `requires-python = ">=3.9"`, description, readme, MIT license, classifiers, urls.
+- `dependencies = []` — EMPTY, forever.
+- `[project.optional-dependencies] dev = ["pytest", "ruff", "mypy"]`.
+- Tool configs in same file: `[tool.pytest.ini_options]`, `[tool.ruff]`, `[tool.mypy]` (strict).
+- Semantic Versioning. Full type hints everywhere + `py.typed`.
+
+### Publishing
+- PyPI **Trusted Publishing (OIDC)** via `pypa/gh-action-pypi-publish` with `permissions: id-token: write`. **NEVER store a long-lived PyPI API token as a GitHub secret** (this exact mistake caused the LiteLLM supply-chain attack, March 2026).
+- Name "lightlogger" confirmed free on PyPI (checked 2026-09-09).
+
+---
+
+## 5. PUBLIC API (v1 — exactly this, nothing more)
+
+```python
+lightlogger.start(port=4356, host="127.0.0.1", max_logs=5000, capture_logging=True, open_browser=False)
+lightlogger.stop()
+lightlogger.debug(msg, data=None)
+lightlogger.info(msg, data=None)
+lightlogger.warn(msg, data=None)
+lightlogger.error(msg, data=None)
+lightlogger.var(name, value)                          # logs any variable as expandable JSON
+lightlogger.request(method, url, status, duration_ms) # API/request logging
+lightlogger.group(name)                               # context manager; nested groups supported (Phase 6.5)
+```
+
+HTTP routes: `/` (UI), `/api/logs` (JSON backlog), `/api/stream` (SSE), `/api/clear` (POST, clears buffer).
+
+`data`/`value` serialization: `json.dumps(..., default=str)` so any object works without crashing.
+
+---
+
+## 6. UI REQUIREMENTS (single index.html)
+
+Must have in v1: dark theme (default), color-coded levels (debug grey, info blue, warn yellow, error red), live auto-scroll with **pause** button, **clear logs** button (calls /api/clear), search box (client-side filter), level filter dropdown, click row → expand full details (file:line, logger, pretty JSON data), download logs as .json button, connection status dot (connected/reconnecting), log counter.
+
+Style: clean, modern, monospace font for messages, subtle borders, feels like a premium dev tool. No external fonts/CDNs (zero network deps — must work offline).
+
+## 6.5. UI REQUIREMENTS — log grouping (Phase 6.5)
+
+- A group-marker record renders as a collapsible header row, not a normal log line: chevron/dropdown icon (inline SVG, no icon fonts, no CDN — same offline constraint as everything else), group name, child count, and a "worst-level" hint (e.g. a red tint/badge if any descendant is `error`-level) — computed client-side by walking descendants, no new server logic needed.
+- Nested groups indent their children (mirrors the browser DevTools `console.group`/`console.groupEnd` UX — a familiar reference point, not an arbitrary accordion pattern). Chevron rotates on toggle — this is user-triggered motion answering a click, not ambient decoration, so it's fine alongside the existing single ambient motion moment (the reconnecting-dot pulse from Phase 6).
+- Collapsed by default. Toolbar gains expand-all / collapse-all buttons.
+- Search/filter must work across grouped records: a match on a nested record auto-expands its ancestor chain so the match is visible; a group the user manually expanded/collapsed keeps that state once the search is cleared (search-driven expansion doesn't overwrite a person's own manual choice).
+- Visual theme gets richer/more colorful for this phase specifically — level colors (debug/info/warn/error) stay meaningful and unchanged, but group-related chrome (headers, chevrons, badges) can use more vivid accents than Phase 6's restrained palette, as a deliberate one-time exception to "keep it restrained."
+- Still one file, no CDN, fully offline, zero third-party dependencies.
+
+---
+
+## 7. BUILD PHASES (do IN ORDER, one phase per session, test before moving on)
+
+- **Phase 0:** Scaffold repo (structure above), pyproject.toml, LICENSE, ruff, pre-commit, empty CI. Verify `pip install -e .` works.
+- **Phase 1:** buffer.py + logger functions writing to deque. Unit tests. No server yet.
+- **Phase 2:** server.py — daemon thread, `/api/logs` returns JSON. Milestone: see JSON in browser.
+- **Phase 3:** Basic index.html — polls `/api/logs` every 2s, renders list. Ugly is fine.
+- **Phase 4:** SSE — `/api/stream`, EventSource, live updates, heartbeat, reconnect. Remove polling.
+- **Phase 5:** LightloggerHandler + `capture_logging` + file/line capture via `sys._getframe`.
+- **Phase 6:** Full UI polish — search, filters, pause, clear, expand, download, status dot.
+- **Phase 6.5:** Log grouping — `lightlogger.group(name)` context manager (contextvars-based, thread/async-safe, nested), amended record structure, UI collapsible group rows with expand/collapse-all and search-aware auto-expand. Scope amendment, see note at top of this file.
+- **Phase 7:** Tests to ~80% coverage, CI green on 3.9–3.13, mypy strict passes, README + demo GIF, publish 0.1.0 via Trusted Publishing.
+
+---
+
+## 8. DO NOT (explicit bans for v1)
+
+- ❌ NO third-party packages (not even in tests beyond pytest/ruff/mypy as dev deps)
+- ❌ NO websockets (SSE only), NO React/Vue/build tools/npm, NO CDN links in the UI
+- ❌ NO database, NO writing logs to disk
+- ❌ NO `inspect.stack()` in the logging path
+- ❌ NO `0.0.0.0` default binding
+- ❌ NO multiple layouts, NO AI features, NO auth/login, NO Flask/Django/FastAPI middleware, NO Node.js port — these are ALL post-v1. If tempted, add a note to CHANGELOG "Unreleased/Ideas" instead of building.
+- ❌ NO flat layout — src layout only
+- ❌ NO committing secrets/tokens ever
+
+---
+
+## 9. README (write at Phase 7 — it's our landing page)
+
+Order: name + one-liner → badges (PyPI, CI, license, Python versions) → **demo GIF** (before any scrolling — the single biggest factor for stars) → install + 2-line quickstart within first 200 words → features table → "Why lightlogger" (problem story) → contributing invite → MIT.
+
+One-liner: "Live web dashboard for your Python logs — pip install, add one line, open localhost:4356. Zero dependencies."
+
+Length 500–1500 words. GIF: <15s, ~640px, <8MB, stored in /assets. Add a security note: localhost-only by default, not for production.
+
+---
+
+## 10. DEFINITION OF DONE (v1)
+
+- [ ] `pip install lightlogger` + 2 lines → working live UI
+- [ ] Zero runtime dependencies (verify: fresh venv, install, run)
+- [ ] Existing `logging` calls appear in UI automatically
+- [ ] RAM bounded (deque maxlen honored under log flood)
+- [ ] Binds 127.0.0.1 only by default; warning on override
+- [ ] Search/filter/pause/clear/expand/download all work
+- [ ] `lightlogger.group()` nests correctly and stays isolated across concurrent threads
+- [ ] Survives: port conflict, browser refresh, SSE reconnect, `stop()` + `start()` again
+- [ ] Tests pass 3.9–3.13, mypy strict clean, ruff clean
+- [ ] README with GIF, CHANGELOG, published on PyPI via Trusted Publishing
+
+Owner's context: this project is also his portfolio piece for LinkedIn/recruiters — so code quality, comments, commit messages, and docs must look professional throughout. Write commit messages in conventional style (`feat:`, `fix:`, `docs:`).

lightlogger-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to lightlogger
+
+Thanks for considering a contribution! This project intentionally stays small and dependency-free — please read the ground rules before opening a PR.
+
+## Ground rules
+
+- **Zero third-party runtime dependencies.** Standard library only. Dev-only tools (`pytest`, `ruff`, `mypy`) are the sole exception.
+- **Binds to `127.0.0.1` by default.** Any change touching networking must preserve this.
+- **No `inspect.stack()`** in the logging hot path — use `sys._getframe()`.
+- **Vanilla HTML/CSS/JS** for the dashboard UI — no frameworks, no build step, no CDN links.
+
+## Setup
+
+```bash
+git clone https://github.com/Rahuwale123/lightlogger.git
+cd lightlogger
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Before opening a PR
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/lightlogger
+pytest
+```
+
+## Commit style
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, ...).

lightlogger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rahul wale
+
+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.

lightlogger-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: lightlogger
+Version: 0.1.0
+Summary: Live web dashboard for your Python logs — one line of code, zero dependencies
+Project-URL: Homepage, https://github.com/Rahuwale123/lightlogger
+Project-URL: Repository, https://github.com/Rahuwale123/lightlogger
+Project-URL: Changelog, https://github.com/Rahuwale123/lightlogger/blob/main/CHANGELOG.md
+Author-email: rahul wale <fthedrive@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dashboard,debugging,developer-tools,logging,logs,sse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lightlogger
+
+Live web dashboard for your Python logs — pip install, add one line, open localhost:4356. Zero dependencies.
+
+[![PyPI](https://img.shields.io/pypi/v/lightlogger.svg)](https://pypi.org/project/lightlogger/)
+[![CI](https://github.com/Rahuwale123/lightlogger/actions/workflows/ci.yml/badge.svg)](https://github.com/Rahuwale123/lightlogger/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+
+![lightlogger dashboard: a nested process_order group with a warning badge, a live error, and streaming request logs](https://raw.githubusercontent.com/Rahuwale123/lightlogger/main/assets/demo.gif)
+
+## Install
+
+```bash
+pip install lightlogger
+```
+
+```python
+import lightlogger
+lightlogger.start()
+lightlogger.info("user logged in")
+```
+
+That's it — open `http://127.0.0.1:4356` and watch it stream in live, in a dark, searchable dashboard. No config file, no separate server process to run, no npm install.
+
+Your existing `logging` calls show up too, with zero code changes:
+
+```python
+lightlogger.start(capture_logging=True)  # the default
+import logging
+logging.getLogger("some.third.party.lib").warning("disk almost full")  # appears in the UI automatically
+```
+
+And when one log message is really four related operations, group them:
+
+```python
+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")
+        lightlogger.info("sms sent")
+```
+
+They render as a collapsible tree — click to expand, nested groups indent, a red badge appears if anything inside failed.
+
+## Features
+
+| | |
+|---|---|
+| **Live streaming** | Server-Sent Events, not polling — logs appear the instant they're written |
+| **Zero-code `logging` capture** | Attaches to the root logger; your own and third-party libraries' logs show up automatically |
+| **Nested log grouping** | `with lightlogger.group(name):` — collapsible, nested, thread- and async-safe |
+| **Search & level filter** | Client-side, instant, works across grouped and ungrouped logs alike |
+| **Pause / Resume** | Freeze the view to read something — nothing is dropped, a counter shows what's waiting |
+| **Click to expand** | File, line, logger name, and pretty-printed JSON data for any entry |
+| **Download as JSON** | One click, the full current backlog |
+| **Bounded memory** | A fixed-size ring buffer — lightlogger can never be the reason your app runs out of RAM |
+| **Zero dependencies** | Python standard library only, from the HTTP server to the JSON encoding |
+
+## Built-in help
+
+Forgot the API? It's in the package, not just this README:
+
+```python
+>>> import lightlogger
+>>> lightlogger.help()
+```
+
+Prints a full cheatsheet to your terminal — every function, one-line descriptions, tiny examples, the `capture_logging` gotcha, no need to leave your shell. And once the dashboard is running, open `http://127.0.0.1:4356/help` for the same reference as a page, with copyable code blocks.
+
+## Why lightlogger
+
+Debugging a running Python process usually means one of three things: `print()` statements you'll forget to remove, a terminal window full of scrolling text you can't search, or reaching for a heavyweight observability platform to answer a question that takes ten seconds to answer once you can actually *see* your logs.
+
+We looked at what else exists. [Logdy](https://logdy.dev/) is a Go binary you install separately from your app. [Chronologer](https://github.com/nkconnor/chronologer) needs its own server process. [cutelog](https://github.com/busimus/cutelog) needs PyQt. Logfire is closed-source and cloud-hosted. `lnav` and `klp` are terminal-only. Django and Flask debug toolbars only work inside those specific frameworks, in that specific request/response cycle.
+
+None of them do the one thing that actually matches how a Python developer debugs: `import`, call one function, and get a live web page — from *inside* the process you're already running, with no extra install, no extra service, no dependencies to audit. That's the gap lightlogger fills. And once your logs have a real UI instead of a scrolling terminal, grouping related operations into a collapsible tree stops being a nice-to-have — it's the difference between reading a wall of text and reading a story.
+
+## Security
+
+lightlogger binds to `127.0.0.1` only, by default — nothing is reachable outside your machine unless you explicitly pass `host="0.0.0.0"` (which prints a loud warning when you do). It's a local development tool, not a production observability system: don't run it against a public-facing process, and don't leave it running longer than your debugging session needs.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (short version: zero dependencies, stay on stdlib, keep it simple). Bug reports and PRs both go through [GitHub Issues](https://github.com/Rahuwale123/lightlogger/issues).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lightlogger-0.1.0/README.md

@@ -0,0 +1,90 @@
+# lightlogger
+
+Live web dashboard for your Python logs — pip install, add one line, open localhost:4356. Zero dependencies.
+
+[![PyPI](https://img.shields.io/pypi/v/lightlogger.svg)](https://pypi.org/project/lightlogger/)
+[![CI](https://github.com/Rahuwale123/lightlogger/actions/workflows/ci.yml/badge.svg)](https://github.com/Rahuwale123/lightlogger/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+
+![lightlogger dashboard: a nested process_order group with a warning badge, a live error, and streaming request logs](https://raw.githubusercontent.com/Rahuwale123/lightlogger/main/assets/demo.gif)
+
+## Install
+
+```bash
+pip install lightlogger
+```
+
+```python
+import lightlogger
+lightlogger.start()
+lightlogger.info("user logged in")
+```
+
+That's it — open `http://127.0.0.1:4356` and watch it stream in live, in a dark, searchable dashboard. No config file, no separate server process to run, no npm install.
+
+Your existing `logging` calls show up too, with zero code changes:
+
+```python
+lightlogger.start(capture_logging=True)  # the default
+import logging
+logging.getLogger("some.third.party.lib").warning("disk almost full")  # appears in the UI automatically
+```
+
+And when one log message is really four related operations, group them:
+
+```python
+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")
+        lightlogger.info("sms sent")
+```
+
+They render as a collapsible tree — click to expand, nested groups indent, a red badge appears if anything inside failed.
+
+## Features
+
+| | |
+|---|---|
+| **Live streaming** | Server-Sent Events, not polling — logs appear the instant they're written |
+| **Zero-code `logging` capture** | Attaches to the root logger; your own and third-party libraries' logs show up automatically |
+| **Nested log grouping** | `with lightlogger.group(name):` — collapsible, nested, thread- and async-safe |
+| **Search & level filter** | Client-side, instant, works across grouped and ungrouped logs alike |
+| **Pause / Resume** | Freeze the view to read something — nothing is dropped, a counter shows what's waiting |
+| **Click to expand** | File, line, logger name, and pretty-printed JSON data for any entry |
+| **Download as JSON** | One click, the full current backlog |
+| **Bounded memory** | A fixed-size ring buffer — lightlogger can never be the reason your app runs out of RAM |
+| **Zero dependencies** | Python standard library only, from the HTTP server to the JSON encoding |
+
+## Built-in help
+
+Forgot the API? It's in the package, not just this README:
+
+```python
+>>> import lightlogger
+>>> lightlogger.help()
+```
+
+Prints a full cheatsheet to your terminal — every function, one-line descriptions, tiny examples, the `capture_logging` gotcha, no need to leave your shell. And once the dashboard is running, open `http://127.0.0.1:4356/help` for the same reference as a page, with copyable code blocks.
+
+## Why lightlogger
+
+Debugging a running Python process usually means one of three things: `print()` statements you'll forget to remove, a terminal window full of scrolling text you can't search, or reaching for a heavyweight observability platform to answer a question that takes ten seconds to answer once you can actually *see* your logs.
+
+We looked at what else exists. [Logdy](https://logdy.dev/) is a Go binary you install separately from your app. [Chronologer](https://github.com/nkconnor/chronologer) needs its own server process. [cutelog](https://github.com/busimus/cutelog) needs PyQt. Logfire is closed-source and cloud-hosted. `lnav` and `klp` are terminal-only. Django and Flask debug toolbars only work inside those specific frameworks, in that specific request/response cycle.
+
+None of them do the one thing that actually matches how a Python developer debugs: `import`, call one function, and get a live web page — from *inside* the process you're already running, with no extra install, no extra service, no dependencies to audit. That's the gap lightlogger fills. And once your logs have a real UI instead of a scrolling terminal, grouping related operations into a collapsible tree stops being a nice-to-have — it's the difference between reading a wall of text and reading a story.
+
+## Security
+
+lightlogger binds to `127.0.0.1` only, by default — nothing is reachable outside your machine unless you explicitly pass `host="0.0.0.0"` (which prints a loud warning when you do). It's a local development tool, not a production observability system: don't run it against a public-facing process, and don't leave it running longer than your debugging session needs.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (short version: zero dependencies, stay on stdlib, keep it simple). Bug reports and PRs both go through [GitHub Issues](https://github.com/Rahuwale123/lightlogger/issues).
+
+## License
+
+MIT — see [LICENSE](LICENSE).