plotlive 0.1.0__tar.gz

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

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    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 dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[gif]"
+          pip install pytest
+
+      - name: Run tests
+        env:
+          SDL_VIDEODRIVER: dummy
+          SDL_AUDIODRIVER: dummy
+        run: pytest

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

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+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 tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload build artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC — no API key needed)
+
+    steps:
+      - name: Download build artefacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

plotlive-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.installed.cfg
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Distribution / packaging
+MANIFEST
+
+# Hatch
+.hatch/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Project outputs
+*.gif
+*.mp4
+*.png
+frame_*.png
+out.*

plotlive-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,347 @@
+# How plotlive works
+
+plotlive is a thin layer that lets you write standard matplotlib code and get an interactive pygame window instead of a static image. This post walks through every major architectural decision — why each layer exists, how the pieces fit together, and where the tricky parts live.
+
+---
+
+## The goal in one sentence
+
+Run this matplotlib code:
+
+```python
+import plotlive.pyplot as plt
+plt.plot([1, 2, 3], [4, 5, 6], label='data')
+plt.legend()
+plt.show()
+```
+
+And get a live window where you can scroll to zoom, drag to pan, and hover to read data values off the line.
+
+The constraint is that the library must not depend on matplotlib itself. It reimplements just enough of the API to cover the plots data scientists actually reach for during EDA and ML tutorials.
+
+---
+
+## Layer map
+
+```
+┌─────────────────────────────────────────────────────┐
+│  pyplot.py   — state machine (plt.plot, plt.show)   │
+├─────────────────────────────────────────────────────┤
+│  Figure / Axes  — data model                        │
+│    artists.py   — Line2D, Rectangle, Polygon, …     │
+│    transform.py — data ↔ screen math                │
+├─────────────────────────────────────────────────────┤
+│  renderer.py  — all pygame draw calls               │
+├─────────────────────────────────────────────────────┤
+│  events.py    — pan / zoom / keyboard               │
+│  animation.py — timer-driven frame loop             │
+└─────────────────────────────────────────────────────┘
+           ↓
+      pygame-ce + numpy
+```
+
+Each layer has a single job. Artists store data. The transform does math. The renderer draws. Events mutate state. Nothing bleeds across.
+
+---
+
+## Artists: data only, no drawing
+
+Every plot call creates one or more **artist** objects and pushes them into typed lists on the Axes:
+
+```
+ax.lines        → list[Line2D]
+ax.collections  → list[PathCollection]   (scatter)
+ax.patches      → list[Rectangle | Polygon]
+ax.images       → list[AxesImage]
+ax.errorbars    → list[ErrorBar]
+```
+
+An artist is a pure data container. `Line2D` knows its x/y arrays, color, linewidth, and linestyle — nothing more. It never touches pygame. All drawing happens in the renderer, which visits each list in order.
+
+This separation means animations are trivial: `plt.cla()` empties the lists, `update_fn(frame)` rebuilds them, and the renderer draws the new state. The renderer doesn't know or care whether the frame changed.
+
+**Why typed lists instead of a single artist list?** Because the render order matters for visual correctness: images first, then filled polygons, then rectangles, then point collections, then lines on top, then error bars last. Keeping them in separate lists makes the order explicit and avoids an isinstance chain on every render.
+
+---
+
+## Transform: the single source of truth for coordinates
+
+`Transform` owns all zoom/pan state and all coordinate math. There is one Transform per Axes.
+
+```python
+class Transform:
+    xlim: tuple[float, float]   # current data extent
+    ylim: tuple[float, float]
+    axes_rect: tuple[int, int, int, int]  # (left, top, w, h) in screen pixels
+    xscale: str  # 'linear' | 'log'
+    yscale: str
+```
+
+The forward transform maps data coordinates to screen pixels:
+
+```python
+def data_to_screen(self, x, y):
+    sx = left + self._x_norm(x) * width
+    sy = top + height - self._y_norm(y) * height  # Y flip
+    return sx, sy
+```
+
+The Y flip is the most important invariant in the system. Screen Y increases downward; data Y increases upward. The flip lives in exactly one place — `data_to_screen` — and nowhere else. Duplicating it anywhere would cause subtle, hard-to-find bugs.
+
+### Zoom
+
+Zoom is anchored to the cursor position:
+
+```python
+def zoom(self, sx, sy, factor):
+    cx, cy = self.screen_to_data(sx, sy)   # anchor in data coords
+    self.xlim = (cx - (cx - xmin) * factor, cx + (xmax - cx) * factor)
+    self.ylim = (cy - (cy - ymin) * factor, cy + (ymax - cy) * factor)
+```
+
+Converting the cursor to data coordinates first is essential. If you scale `xlim` around its center instead of the cursor, the point under the cursor drifts as you zoom — a disorienting and wrong behaviour.
+
+### Log scale
+
+Log scale changes how `_x_norm` / `_y_norm` compute the fraction along the axis:
+
+```python
+def _y_norm(self, y):
+    if self.yscale == 'log':
+        ly = log10(y)
+        lmin, lmax = log10(ymin), log10(ymax)
+        return (ly - lmin) / (lmax - lmin)
+    return (y - ymin) / (ymax - ymin)
+```
+
+Everything upstream — `data_to_screen`, `screen_to_data`, `zoom`, `pan`, `auto_scale` — just calls `_x_norm` / `_y_norm` and gets correct log-space behaviour for free.
+
+Log zoom is geometric (scales in log space, so each scroll tick feels consistent regardless of your current position) and log pan is additive in log space (which is multiplicative in data space — dragging right multiplies all x values by the same factor).
+
+### Auto-scale timing
+
+`auto_scale` runs at render time, not at plot time. This is a subtle but important decision. Users often write:
+
+```python
+plt.plot(x, y)
+plt.ylim(0, 1)   # called after plot()
+```
+
+If auto-scale ran inside `plot()`, the subsequent `ylim()` call would be silently overwritten on the next render. Running it at the start of `AxesRenderer.render()` — after the user has had a chance to call `set_xlim/set_ylim` — ensures user-specified limits always win.
+
+---
+
+## Renderer: all drawing in one place
+
+`FigureRenderer.render()` creates a pygame Surface the size of the window, then delegates each Axes to `AxesRenderer`. Each Axes renderer gets its own surface allocation based on the normalised rect `(left, bottom, width, height)` stored on the Axes.
+
+Within one Axes, the rendering pipeline is fixed:
+
+```
+1.  auto_scale()                  — fit limits to data
+2.  compute data_rect             — pixel rect for the actual plot area
+3.  fill axes background
+4.  draw grid lines
+5.  AxesImage (imshow)
+6.  Polygon (fill_between, violin, pie, stackplot)
+7.  Rectangle (bar, hist, boxplot body)
+8.  PathCollection (scatter)
+9.  Line2D (plot, boxplot whiskers)
+10. ErrorBar (whiskers + caps)
+11. axes border
+12. ticks + tick labels
+13. title, xlabel, ylabel
+14. legend
+15. colorbar
+```
+
+Steps 5–10 draw on a **subsurface** — a zero-copy view into the full surface clipped to the data rectangle. This has two benefits: pygame automatically clips draw calls to the subsurface bounds (no manual clipping code needed), and artists don't need to know where on screen the data area starts.
+
+The catch: all screen coordinates from `Transform` are in full-surface space, so the renderer subtracts `data_rect.topleft` before using them on the subsurface:
+
+```python
+sx, sy = ax.transform.data_to_screen(x, y)
+sx -= data_rect.left
+sy -= data_rect.top
+```
+
+This subtraction lives in `_screen_to_sub()` and is called at the top of every `_draw_*` helper. Miss it once and everything renders at the wrong position.
+
+### Transparent polygons can't use subsurfaces
+
+Polygons need an alpha channel for `fill_between` and violin plots. pygame surfaces created with `SRCALPHA` support per-pixel alpha, but `subsurface()` returns a view that inherits its parent's flags — and the parent surface has no alpha channel.
+
+The fix is to create a temporary SRCALPHA surface the same size as the data area, draw the polygon on it, and then blit it onto the subsurface:
+
+```python
+tmp = pygame.Surface((data_w, data_h), pygame.SRCALPHA)
+pygame.draw.polygon(tmp, facecolor, points)
+data_surf.blit(tmp, (0, 0))
+```
+
+This allocates a new surface per polygon per frame. For the typical number of polygons in a plot it's fast enough, but it's worth knowing this is happening.
+
+### Pie chart aspect ratio
+
+Pie charts require `aspect='equal'` — a circle should look like a circle, not an ellipse that stretches to fill whatever rectangle the Axes was given. The renderer detects this before setting `axes_rect`:
+
+```python
+if ax._aspect == 'equal':
+    x_ppu = data_w / x_range   # pixels per data unit, x
+    y_ppu = data_h / y_range   # pixels per data unit, y
+    if x_ppu < y_ppu:
+        data_h = int(data_w * y_range / x_range)   # shrink height
+    else:
+        data_w = int(data_h * x_range / y_range)   # shrink width
+```
+
+The smaller dimension drives the other, and the leftover pixels become empty margins. The transform's `axes_rect` is updated to reflect the squarer geometry before any drawing begins.
+
+---
+
+## The event loop
+
+`plt.show()` drives a standard pygame event loop at 60 fps:
+
+```python
+while running:
+    for event in pygame.event.get():
+        if event.type == pygame.QUIT:
+            running = False
+        elif event.type == animation_event_id:
+            dirty |= animation._on_timer()
+        else:
+            dirty |= state.handle_event(event, screen=screen)
+
+    if dirty:
+        surface = FigureRenderer(fig).render()
+        screen.blit(surface, (0, 0))
+        pygame.display.flip()
+        dirty = False
+
+    clock.tick(60)
+```
+
+`dirty` is the only redraw flag. Nothing renders unless something actually changed. This matters because rendering is not free — rebuilding the whole surface on every tick at 60 fps would be wasteful.
+
+`InteractionState` translates raw pygame events into mutations on `Transform`:
+
+| Event | Action |
+|-------|--------|
+| Left mouse down | start pan, record position |
+| Mouse motion while dragging | `transform.pan(dx, dy)` |
+| Mouse wheel | `transform.zoom(cx, cy, factor)` |
+| Double-click | `transform.reset_to_home()` |
+| Scroll up/down | zoom in/out centered on cursor |
+
+Each event handler returns `True` if it changed something, which propagates to `dirty`. Mouse motion always returns `True` because the hover tooltip needs to follow the cursor even when not panning.
+
+**Per-axes isolation**: zoom and pan only apply to the Axes under the cursor. `_find_ax_at(sx, sy)` uses `Transform.contains_screen_point()` to identify which Axes the cursor is inside. A figure with a 2×2 grid of subplots has four completely independent Transform instances; zooming into one doesn't touch the others.
+
+---
+
+## Animation
+
+`Animation` wraps the user's `update_fn(frame)` and drives it with a pygame timer:
+
+```python
+pygame.time.set_timer(event_id, interval_ms)   # fires every N ms
+```
+
+The timer fires a `USEREVENT` that the main loop intercepts. On each tick, `_on_timer()` calls `update_fn(frame)`, increments the frame counter, and marks all axes dirty.
+
+Animations **start paused**. The timer is not activated in `plt.animate()` or `plt.show()` — only when the user presses Space. This allows scrubbing with arrow keys before anything has played, which is useful when you want to examine the starting state or step through an algorithm one frame at a time.
+
+**Frame scrubbing** is implemented as two methods:
+
+```python
+def step_forward(self):
+    return self._show_frame(self._displayed_frame + 1)
+
+def step_back(self):
+    return self._show_frame(max(0, self._displayed_frame - 1))
+```
+
+`_show_frame(n)` calls `update_fn(n)` directly, bypassing the timer entirely. Because `update_fn` typically clears the axes and redraws from scratch, any frame is reachable in O(1) regardless of whether it was previously rendered. The animation is random-access, not sequential.
+
+**Exporting to GIF or MP4** uses the same headless render path. `Animation.save(filename)` iterates all frames, calls `update_fn(i)` and `FigureRenderer(fig).render()` for each, converts the resulting `pygame.Surface` to a `(H, W, 3)` numpy array via `pygame.surfarray.array3d().transpose(1, 0, 2)`, then hands the frame list to Pillow (GIF) or imageio+ffmpeg (video). No display window is needed — `pygame.init()` alone is sufficient, because font rendering goes through `pygame.font` which doesn't require `display.set_mode()`. The typical pattern is export then show:
+
+```python
+anim = plt.animate(update, frames=30, interval=150)
+plt.save_animation('gradient_descent.gif')  # headless export
+plt.show()                                   # interactive window
+```
+
+After `save()` completes, it calls `update_fn(0)` to restore the figure to frame 0, so the subsequent `show()` opens at the beginning rather than the last frame.
+
+**R key** resets both the view and the animation simultaneously:
+
+```python
+ax.transform.reset_to_home()
+anim.pause()
+anim._finished = False
+anim._next_frame = 0
+anim._show_frame(0)
+```
+
+The order matters: pause first (cancel the timer), then reset the frame counter, then render frame 0. Calling `_show_frame(0)` before pausing would let the timer fire and advance to frame 1 before the user sees frame 0.
+
+---
+
+## Ticks and log scale
+
+Tick generation lives in `ticks.py` and is scale-aware:
+
+**Linear**: a nice-step algorithm that tries steps from `[1, 2, 2.5, 5, 10] × 10^k` and picks the first that gives 3–8 ticks across the current view.
+
+**Log**: decade ticks (1, 10, 100, …) at every power of ten in range, plus 2× and 5× intermediate ticks when fewer than three decades are visible. Labels use plain numbers for exponents −3 to 4 (`0.001` through `10000`) and scientific notation (`1e+8`) for anything beyond.
+
+The renderer calls the right tick generator based on `ax._xscale` / `ax._yscale` and uses the same ticks for both the grid lines and the tick marks. They are always in sync.
+
+---
+
+## Color system
+
+`to_rgba(color, alpha=1.0)` converts any matplotlib-style color spec to an `(R, G, B, A)` uint8 tuple that pygame can use directly. Accepted forms:
+
+- Named: `'steelblue'`, `'red'`, `'k'`, `'w'`
+- Single char: `'b'`, `'r'`, `'g'`, `'m'`, `'c'`, `'y'`
+- Hex: `'#3498DB'`, `'#3498DB80'` (with alpha)
+- Cycle alias: `'C0'` through `'C9'` (tab10 palette)
+- Grayscale: `'0.5'`
+- Float tuple: `(0.2, 0.4, 0.8)` in [0, 1]
+- `'none'` → fully transparent
+
+The 10-color default cycle is tab10. Each Axes tracks a `_color_cycle_idx` counter that auto-increments every time a plot call uses the default color. `cla()` resets the counter so re-drawn animations stay consistent across frames.
+
+---
+
+## Format string parsing
+
+`plt.plot(x, y, 'r--o')` is shorthand for `color='red', linestyle='--', marker='o'`. Parsing this is more subtle than it looks because the characters can appear in any order and some overlap: `-` could start `-` (solid) or `--` (dashed) or `-.` (dash-dot).
+
+The parser tries longer patterns first:
+
+```python
+for ls in ['-.', '--', '-', ':']:   # longest first
+    if fmt.startswith(ls):
+        props['linestyle'] = ls
+        fmt = fmt[len(ls):]
+        break
+```
+
+Without this, `'--'` would match as two `-` characters and set the linestyle to solid.
+
+---
+
+## What's missing
+
+The library is deliberately scoped to what's needed for interactive ML tutorials. Deferred features that would add significant complexity:
+
+- `ax.twinx()` / `ax.twiny()` — shared-axis subplots with independent scales
+- `sharex` / `sharey` — linked zoom across subplots
+- `ax.annotate()` / `ax.text()` — arbitrary text at data coordinates
+- `contour` / `contourf` — contour lines over 2D grids
+- Multiple simultaneous figure windows
+
+The core architecture is designed so these could be added without restructuring: artists extend naturally, the transform already supports independent x/y scales, and the event loop is straightforward to extend. But each would take meaningful work to get right, so they're out of scope for now.

plotlive-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] — 2026-06-06
+
+### Added
+- Initial release
+- `matplotlib.pyplot`-compatible state-machine API (`plt.plot`, `plt.scatter`, `plt.hist`, `plt.bar`, `plt.imshow`, `plt.show`, …)
+- OOP API (`fig, ax = plt.subplots()`)
+- Pan (drag), zoom (scroll wheel), reset (double-click or R key)
+- Hover tooltips showing nearest data point
+- Subplot grid via `plt.subplots(nrows, ncols)`
+- Animation via `FuncAnimation` / `plt.animate()` with play/pause/step controls
+- Export animations to GIF (Pillow) or MP4 (imageio + ffmpeg)
+- Jupyter notebook inline display — static figures as PNG, animations as GIF/MP4
+- 10 built-in colormaps: `viridis`, `plasma`, `inferno`, `magma`, `coolwarm`, `RdBu`, `Blues`, `Reds`, `jet`, `gray`
+- `plt.colorbar()` for heatmaps
+- `plt.savefig()` to PNG
+- Log scale (`set_xscale('log')`, `set_yscale('log')`)
+- Bundled DejaVu Sans fonts (no system font dependency)

plotlive-0.1.0/CLAUDE.md

@@ -0,0 +1,85 @@
+# plotlive — codebase guide
+
+Interactive matplotlib-compatible graphs rendered with pygame-ce. Drop-in replacement for the most common `matplotlib.pyplot` patterns; renders a live, pannable, zoomable window instead of a static plot.
+
+## Dev setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[gif,video]"   # install with all optional deps
+pytest                          # run unit tests
+SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy pytest   # headless (CI)
+```
+
+## Architecture
+
+```
+pyplot.py  (state-machine API — plt.plot, plt.show …)
+  └─ Figure  (figure.py)
+       └─ Axes  (axes.py)  — stores artists, no draw calls
+            ├─ Artists  (artists.py)  — Line2D, PathCollection, Rectangle, AxesImage …
+            ├─ CoordTransform  (transform.py)  — data↔screen math, zoom/pan state
+            └─ [rendered by] AxesRenderer  (renderer.py)
+                  ├─ ticks.py   — auto_ticks(), format_ticks()
+                  ├─ drawing.py — draw_dashed_polyline(), draw_marker()
+                  ├─ fonts.py   — cached Font instances, rotated text
+                  └─ colors.py  — to_rgba(), Colormap
+
+pyplot.show()
+  ├─ non-Jupyter → pygame event loop (InteractionState + FuncAnimation timer)
+  └─ Jupyter     → _jupyter.py (headless render → PNG/GIF/MP4 via IPython.display)
+```
+
+## Coordinate systems — the biggest gotcha
+
+Two spaces exist and **must not be mixed**:
+
+| Space | Origin | Used by |
+|-------|--------|---------|
+| Figure-space | top-left of the full window (px) | `transform.data_x_to_screen()`, `transform.data_y_to_screen()`, `axes_rect` |
+| Axes-surface space | top-left of the data area pygame subsurface | `_draw_ticks`, `_draw_grid`, all drawing on `subsurface(data_rect)` |
+
+`data_y_to_screen(y)` returns **figure-space** y (includes `ax_offset`).  
+Before comparing against `data_rect.top / data_rect.bottom`, subtract `self.ax_offset[1]`.  
+This is done in both `_draw_ticks` and `_draw_grid` in `renderer.py`.
+
+## Key invariants
+
+- **Y-axis is flipped**: screen Y=0 is top, data Y increases upward. All flips live in `CoordTransform` only — never duplicate elsewhere.
+- **`plot()` always returns a list** — `line, = plt.plot(x, y)` tuple-unpack is idiomatic.
+- **Auto-scale runs at render time**, not at `plot()` time — users often call `set_xlim()` after `plot()`.
+- **Drawing on `subsurface(data_rect)`** shifts the origin; subtract `data_rect.topleft` from all figure-space coords.
+- **`pygame.draw.circle` at r≤2** produces a diamond artifact. Minimum usable radius for circles is r=3; the marker formula uses `max(2, round(sqrt(size)/1.5))`.
+
+## File map
+
+| File | Responsibility |
+|------|---------------|
+| `pyplot.py` | Global state (`_figures`, `_current_figure`, `_current_axes`), state-machine API, `show()` |
+| `figure.py` | `Figure` — owns `axes[]`, `pixel_size`, `_animation` |
+| `axes.py` | `Axes` — stores artists, `hit_test()`, `cla()`, axis config |
+| `artists.py` | Data-only artist classes (no pygame) |
+| `transform.py` | `CoordTransform` — zoom/pan state, data↔screen math |
+| `renderer.py` | `FigureRenderer` + `AxesRenderer` — all pygame draw calls |
+| `animation.py` | `FuncAnimation` — pygame timer playback + `save()` to GIF/MP4 |
+| `events.py` | `InteractionState` — pan, zoom, hover, keyboard, focus mode |
+| `drawing.py` | `draw_dashed_polyline()`, `draw_marker()`, `draw_colorbar_strip()` |
+| `ticks.py` | `auto_ticks()`, `log_ticks()`, `format_ticks()` |
+| `colors.py` | `to_rgba()`, `Colormap`, 10 built-in colormaps |
+| `fonts.py` | Cached `pygame.font.Font` instances, `render_text_rotated()` |
+| `_parsers.py` | `_parse_fmt()`, `_parse_plot_args()` — matplotlib format strings |
+| `_jupyter.py` | `is_jupyter()`, `show_figure()`, `show_animation()` — IPython inline display |
+
+## Adding a new plot type
+
+1. Add an artist class in `artists.py` (data storage only).
+2. Add a method on `Axes` in `axes.py` that creates the artist and appends it.
+3. Add a drawing branch in `AxesRenderer.render()` in `renderer.py`.
+4. Delegate from `pyplot.py` via `gca().new_method(...)`.
+
+## Running examples
+
+```bash
+SDL_VIDEODRIVER=dummy python examples/bubble_sort.py   # headless smoke test
+python examples/bubble_sort.py                         # interactive window
+```