Round out 2.0: HTML page handler, Jupyter support, numpy renderer, PyPI publishing

- New HTMLFileHandler + VisualFormatter: self-contained styled html pages
  with level-colored record cards, timestamps, logger names, escaped
  plain-text records and tracebacks; flushed per record so the page can
  be watched mid-run. Both are plain logging.FileHandler/Formatter
  subclasses and compose the stdlib way; 1.x usage with a bare
  FileHandler keeps working
- VisualRecord displays inline in Jupyter via _repr_html_
- max_size now applies to matplotlib figures too, by lowering savefig dpi
- New render_numpy fallback: numpy arrays render via PIL when OpenCV is
  not installed
- Embedded images get loading="lazy" so large logs open fast
- Type hints throughout and a py.typed marker
- publish.yml: build + publish to PyPI via trusted publishing on v* tags
- demo.py showcases the new handler; README rewritten accordingly

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ha16zNy2fDMdrZBMQGgpBt

Author: dchaplinsky

.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -16,20 +16,19 @@ You can read about it in detail in a great blog post [visual-logging, my new fav
 pip install visual-logging
 ```
 
-No extra dependencies — whichever of OpenCV, PIL/Pillow and matplotlib you already have installed are picked up automatically. Requires Python 3.9+.
+No extra dependencies — whichever of OpenCV, PIL/Pillow and matplotlib you already have installed are picked up automatically (numpy arrays render through PIL when OpenCV isn't around). Requires Python 3.9+.
 
 ## Usage example (see demo.py)
 
 ```python
 import logging
-from logging import FileHandler
-from vlogging import VisualRecord
+from vlogging import HTMLFileHandler, VisualRecord
 
 import cv2  # or PIL.Image, or matplotlib — whatever you use
 
 logger = logging.getLogger("demo")
 logger.setLevel(logging.DEBUG)
-logger.addHandler(FileHandler("test.html", mode="w"))
+logger.addHandler(HTMLFileHandler("test.html", title="My debug log"))
 
 cv_image = cv2.imread("lenna.jpg")
 
@@ -42,10 +41,21 @@ logger.warning(VisualRecord(
     "Hello from all", [cv_image, pil_image, mpl_figure],
     fmt="png", max_size=(320, 240)))
 
+# Ordinary log calls work too, and land in the same page:
+logger.info("Processed frame %d", 42)
+
 logging.shutdown()  # flushes and closes the html file
 ```
 
-Open `test.html` in a browser and enjoy. A sample of generated html is available [here](http://dchaplinsky.github.io/visual-logging/).
+Open `test.html` in a browser and enjoy: `HTMLFileHandler` writes a styled, self-contained page — records are color-coded by log level with timestamps and logger names, plain messages are escaped, and exceptions logged with `logger.exception(...)` include their traceback. Records are flushed as they happen, so you can watch the page mid-run.
+
+Everything composes the stdlib way: `HTMLFileHandler` is a `logging.FileHandler` that installs a `VisualFormatter` (a `logging.Formatter`) by default — use either piece on its own if you prefer. Passing a `VisualRecord` to a plain `FileHandler` still produces bare html fragments, exactly as in 1.x.
+
+In **Jupyter**, a `VisualRecord` displays itself inline — no logging setup needed:
+
+```python
+VisualRecord("Detected edges", edges_img, "Canny output")
+```
 
 ### `VisualRecord` arguments
 
@@ -55,12 +65,16 @@ Open `test.html` in a browser and enjoy. A sample of generated html is available
 | `imgs` | A single image or a list of images: OpenCV/numpy arrays, PIL images and matplotlib figures in any combination |
 | `footnotes` | Optional text rendered as `<pre>` under the images |
 | `fmt` | Image format to embed: `png` (default), `jpeg`, `webp` — anything your imaging library can encode |
-| `max_size` | Optional `(width, height)` tuple: OpenCV and PIL images bigger than that are downscaled proportionally before embedding, to keep log files readable and small (matplotlib figures are embedded as rendered) |
+| `max_size` | Optional `(width, height)` tuple: images bigger than that are downscaled proportionally before embedding (matplotlib figures by lowering the render dpi), to keep log files readable and small |
 
 ## Changelog
 
 **2.0**
-- Modern packaging (`pyproject.toml`), Python 3.9+ only
-- New `max_size` option to downscale embedded images
+- Modern packaging (`pyproject.toml`), Python 3.9+ only, `py.typed` type hints
+- New `HTMLFileHandler` + `VisualFormatter`: styled, self-contained html pages with level colors, timestamps, escaped plain-text records and tracebacks
+- New `max_size` option to downscale embedded images (all renderers)
+- `VisualRecord` displays inline in Jupyter notebooks
+- numpy arrays render via PIL when OpenCV is not installed
+- Embedded images use `loading="lazy"`, so huge logs open fast
 - matplotlib support no longer relies on the deprecated `pylab` module
-- Tests run on GitHub Actions against Python 3.9–3.13
+- Tests run on GitHub Actions against Python 3.9–3.13; releases publish to PyPI from tags via trusted publishing

demo.py

@@ -1,8 +1,7 @@
 import logging
-from logging import FileHandler
 from pathlib import Path
 
-from vlogging import VisualRecord
+from vlogging import HTMLFileHandler, VisualRecord
 
 if __name__ == "__main__":
     import cv2
@@ -22,10 +21,8 @@
     pil_image = Image.open(lenna)
 
     logger = logging.getLogger("demo")
-    fh = FileHandler("test.html", mode="w")
-
     logger.setLevel(logging.DEBUG)
-    logger.addHandler(fh)
+    logger.addHandler(HTMLFileHandler("test.html", title="visual-logging demo"))
 
     logger.debug(VisualRecord(
         "Hello from OpenCV", cv_image, "This is OpenCV image", fmt="png"))
@@ -45,4 +42,12 @@
                      [cv_image, pil_image, fig1],
                      fmt="png", max_size=(200, 200)))
 
+    logger.info("Plain text records work too, and are escaped: <html> & so on")
+
+    try:
+        1 / 0
+    except ZeroDivisionError:
+        logger.exception(VisualRecord(
+            "Exceptions come with tracebacks", cv_image))
+
     logging.shutdown()

pyproject.toml

@@ -42,5 +42,8 @@ test = [
 [tool.setuptools]
 packages = ["vlogging"]
 
+[tool.setuptools.package-data]
+vlogging = ["py.typed"]
+
 [tool.setuptools.dynamic]
 version = {attr = "vlogging.__version__"}