plotlet 0.2.0__tar.gz → 0.4.0__tar.gz

{plotlet-0.2.0/src/plotlet.egg-info → plotlet-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plotlet
-Version: 0.2.0
-Summary: Small, hackable Python library that emits matplotlib-style SVG plots.
+Version: 0.4.0
+Summary: Python library for SVG plots, with multi-panel composition and an extension API for custom plot types.
 Author: gitbamboo42
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/gitbamboo42/plotlet
@@ -22,6 +22,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fonttools>=4.0
+Requires-Dist: scipy>=1.10
 Provides-Extra: dev
 Requires-Dist: jupyter; extra == "dev"
 Requires-Dist: nbconvert; extra == "dev"
@@ -29,13 +30,13 @@ Dynamic: license-file
 
 # plotlet
 
-A small, hackable Python library that emits matplotlib-style SVG plots.
+A Python library for SVG plots — with multi-panel composition, shared-axis layouts, and an extension API for custom plot types.
 
-## Why
+## What it's for
 
-matplotlib is the right tool when you want the kitchen sink. plotlet's niche is **custom plot types** — genome tracks, Manhattan plots, phylogenetic trees, anything matplotlib's extension API makes painful. The whole library has a deliberately tiny, exposed core: adding a new plot type is a 3-step recipe, not an architecture project.
+plotlet is built for **multi-panel scientific figures with custom plot types** — genome tracks, spike rasters, climate stacks, Manhattan plots, phylogenetic trees. The core ships ~5 standard plots plus multi-panel composition (`|`, `/`, `share_x()`).
 
-It's a **scaffold, not a feature catalog**: the core ships ~5 standard plots and the infrastructure for extending. Custom plot types live in your own project (or [`cookbook/`](cookbook/)), not upstream. See [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for the full framing.
+Custom plot types are a 3-step recipe (`record`, `xdomain`/`ydomain`, `draw`) and live in your own project (or [`cookbook/`](cookbook/)) rather than upstream. See [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for the full framing.
 
 ```python
 import plotlet as pt
@@ -59,12 +60,13 @@ pip install plotlet
 
 ## Properties
 
-- **Lightweight.** `fonttools` for font handling. numpy / pandas / polars inputs work transparently if you have them.
+- **Minimal dependencies.** `fonttools` for font handling. numpy / pandas / polars inputs work transparently if you have them.
 - **Static SVG output.** No interactivity, no animation. Same script → byte-identical SVG.
 - **Cross-machine reproducible.** Bundled DejaVu Sans + text-as-paths means rendering is identical on Linux, macOS, Windows, headless CI.
-- **Jupyter-native.** `Figure._repr_html_` auto-renders the last expression in a cell.
-- **Tiny output.** Each plot is ~50 KB SVG, self-contained.
-- **Compositional.** Multi-panel layouts via `|`, `/`, `pt.grid`; share scales with `share_x=` / `share_y=`; layout-level legend with `pt.legend()` covering both discrete swatches and continuous gradients (the colorbar).
+- **Jupyter-native.** `Chart._repr_html_` auto-renders the last expression in a cell.
+- **Compact output.** Each plot is ~50 KB SVG, self-contained.
+- **Compositional.** Multi-panel layouts via `|`, `/`, `pt.grid`; share scales with `(a | b).share_x()` or `pt.grid(..., share_x="col")`; layout-level legend with `pt.legend()` covering both discrete swatches and continuous gradients (the colorbar).
+- **AI-readable.** Every figure ships `data-plotlet-*` attributes describing plot type, axes, scales, ranges, and series labels — readable in one XML parse, no glyph-path OCR. Schema: [docs/AI_ATTRS.md](docs/AI_ATTRS.md).
 
 ## API
 
@@ -74,7 +76,7 @@ pip install plotlet
 
 Pass at construction (`pt.chart(data, title=..., grid=True, ...)`) or as chained setters (`c.title(...)`, etc.):
 
-`title`, `xlabel`, `ylabel`, `xlim=(a, b)`, `ylim=(a, b)`, `xscale="linear"|"log"|"category"` (chained: `c.xscale("category", order=[...], padding=0)`), `yscale=...`, `grid=True/False`, `legend=True/False`, `data_width`, `data_height` (the data region — preferred), or `canvas_width`, `canvas_height` (the full SVG canvas — mutually exclusive with the data form). Sizes accept bare pixels (`400`) or unit-suffixed strings (`"4in"`, `"10cm"`, `"100mm"`, `"72pt"`).
+`title`, `xlabel`, `ylabel`, `xlim=(a, b)`, `ylim=(a, b)`, `xscale="linear"|"log"|"category"` (chained: `c.xscale("category", order=[...], padding=0)`), `yscale=...`, `grid=True/False`, `legend=True/False`, `data_width`, `data_height` (the data region — the figure canvas grows to fit titles, tick labels, and axis labels). Sizes accept bare pixels (`400`) or unit-suffixed strings (`"4in"`, `"10cm"`, `"100mm"`, `"72pt"`). To fit a composition into a target SVG canvas, chain `.fit(canvas_width=…, canvas_height=…)` after composing — it rescales data regions while keeping fonts, spines, and margins at their absolute pixel sizes.
 
 String-valued data on either axis (`scatter(["a","b","c"], ...)`, `bar`, …) auto-switches to a categorical scale, alphabetical by default. `padding=0` makes category bands contiguous (heatmap-track look).
 
@@ -92,11 +94,14 @@ Tick customization: `c.xticks([0, 5, 10], ["A","B","C"], rotation=45, fontsize=1
 | `.axhline(y, **opts)` / `.axvline(x, **opts)` | `color`, `linewidth`, `linestyle`, `alpha`, `label`, axes-fraction `xmin`/`xmax` (or `ymin`/`ymax`) |
 | `.axhspan(ymin, ymax, **opts)` / `.axvspan(xmin, xmax, **opts)` | `color`, `alpha`, `label`, axes-fraction `xmin`/`xmax` (or `ymin`/`ymax`) |
 | `.imshow(data, **opts)` | `cmap` (any matplotlib name, default `"viridis"`), `vmin`, `vmax`, `extent=(left, right, bottom, top)` |
+| `.heatmap(df, **opts)` | `cmap`, `vmin`, `vmax`, `norm`, `center`, `xticklabels`, `yticklabels`, `legend` |
 
 `hue=<col>` (on `.line` / `.scatter`) splits into one call per unique value with auto-labels and tab10 colors. Reference lines and spans default to black; spans use `alpha=0.2`. They're drawn outside the data color cycle and don't participate in autoscaling — they're decorations on the frame, not data.
 
 `.imshow(data)` renders a 2-D array as a colored grid. Small grids (`nrows × ncols ≤ 10000`) emit one `<rect>` per cell and stay vector-clean at any zoom; larger grids encode as a single base64 PNG and quantize to 256 levels. Image row 0 is rendered at the top of its rectangle; the y axis stays Cartesian (small at bottom). All ~180 matplotlib colormaps are vendored — see `pt.list_colormaps()`.
 
+`.heatmap(df)` is the DataFrame-aware companion to `.imshow`. A pandas DataFrame's `index` becomes the row tick labels and `columns` becomes the column tick labels; row 0 sits at the top. For a plain 2-D array, default labels are integer indices — pass `xticklabels=` / `yticklabels=` to override. Cells render at integer + 0.5 centers on a linear axis, which lines up with scipy's dendrogram leaf positions so a top/left dendrogram pairs cleanly via `share_x` / `share_y`.
+
 ### Subplots
 
 Compose multi-panel layouts with operators on `Chart`:
@@ -110,10 +115,11 @@ pt.grid([[a, b],       # 2-D grid; cells may be `None`
          [c, d]])
 
 # Share x or y across panels — collapses the gap between them
-# and forces both onto the source's scale.
+# and unions data ranges; the first leaf in reading order anchors
+# the scale, others are aspect-scaled to match.
 top  = pt.chart()
-main = pt.chart(share_x=top)
-top / main             # vertically stacked, x-axis joined
+main = pt.chart()
+(top / main).share_x()         # vertically stacked, x-axis joined
 
 # Layout-level legend (covers colorbar and discrete swatches in
 # one constructor — geometry follows from the source's color mapping).
@@ -147,7 +153,7 @@ c.write_html("plot.html")    # standalone HTML
 
 ## Adding a new plot type
 
-plotlet's central hackability claim: a custom plot type is a 3-step recipe (~50–100 lines) that gets axes, scales, legend, grid, and composability for free. The recommended home is your own project, or [`cookbook/`](cookbook/) as reference. Full guide: [docs/EXTENDING.md](docs/EXTENDING.md).
+plotlet is designed so that adding a new plot type is a 3-step recipe (~50–100 lines) that gets axes, scales, legend, grid, and composability for free. The recommended home is your own project, or [`cookbook/`](cookbook/) as reference. Full guide: [docs/EXTENDING.md](docs/EXTENDING.md).
 
 ## Testing
 
@@ -161,7 +167,7 @@ python tests/test_subplots.py         # subplot baselines + composition invarian
 ## Non-goals
 
 - No interactivity (hover, zoom, click). Static rendering is the point.
-- Not competing with matplotlib on standard plots; matplotlib is bigger and battle-tested.
+- Not aiming for full coverage of standard statistical plots — those needs are well-served elsewhere.
 - Not a 3D plotter, not a dashboard tool.
 - Not a feature catalog — new plot types belong in user projects or `cookbook/`, not in the core.
 

{plotlet-0.2.0 → plotlet-0.4.0}/README.md

@@ -1,12 +1,12 @@
 # plotlet
 
-A small, hackable Python library that emits matplotlib-style SVG plots.
+A Python library for SVG plots — with multi-panel composition, shared-axis layouts, and an extension API for custom plot types.
 
-## Why
+## What it's for
 
-matplotlib is the right tool when you want the kitchen sink. plotlet's niche is **custom plot types** — genome tracks, Manhattan plots, phylogenetic trees, anything matplotlib's extension API makes painful. The whole library has a deliberately tiny, exposed core: adding a new plot type is a 3-step recipe, not an architecture project.
+plotlet is built for **multi-panel scientific figures with custom plot types** — genome tracks, spike rasters, climate stacks, Manhattan plots, phylogenetic trees. The core ships ~5 standard plots plus multi-panel composition (`|`, `/`, `share_x()`).
 
-It's a **scaffold, not a feature catalog**: the core ships ~5 standard plots and the infrastructure for extending. Custom plot types live in your own project (or [`cookbook/`](cookbook/)), not upstream. See [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for the full framing.
+Custom plot types are a 3-step recipe (`record`, `xdomain`/`ydomain`, `draw`) and live in your own project (or [`cookbook/`](cookbook/)) rather than upstream. See [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) for the full framing.
 
 ```python
 import plotlet as pt
@@ -30,12 +30,13 @@ pip install plotlet
 
 ## Properties
 
-- **Lightweight.** `fonttools` for font handling. numpy / pandas / polars inputs work transparently if you have them.
+- **Minimal dependencies.** `fonttools` for font handling. numpy / pandas / polars inputs work transparently if you have them.
 - **Static SVG output.** No interactivity, no animation. Same script → byte-identical SVG.
 - **Cross-machine reproducible.** Bundled DejaVu Sans + text-as-paths means rendering is identical on Linux, macOS, Windows, headless CI.
-- **Jupyter-native.** `Figure._repr_html_` auto-renders the last expression in a cell.
-- **Tiny output.** Each plot is ~50 KB SVG, self-contained.
-- **Compositional.** Multi-panel layouts via `|`, `/`, `pt.grid`; share scales with `share_x=` / `share_y=`; layout-level legend with `pt.legend()` covering both discrete swatches and continuous gradients (the colorbar).
+- **Jupyter-native.** `Chart._repr_html_` auto-renders the last expression in a cell.
+- **Compact output.** Each plot is ~50 KB SVG, self-contained.
+- **Compositional.** Multi-panel layouts via `|`, `/`, `pt.grid`; share scales with `(a | b).share_x()` or `pt.grid(..., share_x="col")`; layout-level legend with `pt.legend()` covering both discrete swatches and continuous gradients (the colorbar).
+- **AI-readable.** Every figure ships `data-plotlet-*` attributes describing plot type, axes, scales, ranges, and series labels — readable in one XML parse, no glyph-path OCR. Schema: [docs/AI_ATTRS.md](docs/AI_ATTRS.md).
 
 ## API
 
@@ -45,7 +46,7 @@ pip install plotlet
 
 Pass at construction (`pt.chart(data, title=..., grid=True, ...)`) or as chained setters (`c.title(...)`, etc.):
 
-`title`, `xlabel`, `ylabel`, `xlim=(a, b)`, `ylim=(a, b)`, `xscale="linear"|"log"|"category"` (chained: `c.xscale("category", order=[...], padding=0)`), `yscale=...`, `grid=True/False`, `legend=True/False`, `data_width`, `data_height` (the data region — preferred), or `canvas_width`, `canvas_height` (the full SVG canvas — mutually exclusive with the data form). Sizes accept bare pixels (`400`) or unit-suffixed strings (`"4in"`, `"10cm"`, `"100mm"`, `"72pt"`).
+`title`, `xlabel`, `ylabel`, `xlim=(a, b)`, `ylim=(a, b)`, `xscale="linear"|"log"|"category"` (chained: `c.xscale("category", order=[...], padding=0)`), `yscale=...`, `grid=True/False`, `legend=True/False`, `data_width`, `data_height` (the data region — the figure canvas grows to fit titles, tick labels, and axis labels). Sizes accept bare pixels (`400`) or unit-suffixed strings (`"4in"`, `"10cm"`, `"100mm"`, `"72pt"`). To fit a composition into a target SVG canvas, chain `.fit(canvas_width=…, canvas_height=…)` after composing — it rescales data regions while keeping fonts, spines, and margins at their absolute pixel sizes.
 
 String-valued data on either axis (`scatter(["a","b","c"], ...)`, `bar`, …) auto-switches to a categorical scale, alphabetical by default. `padding=0` makes category bands contiguous (heatmap-track look).
 
@@ -63,11 +64,14 @@ Tick customization: `c.xticks([0, 5, 10], ["A","B","C"], rotation=45, fontsize=1
 | `.axhline(y, **opts)` / `.axvline(x, **opts)` | `color`, `linewidth`, `linestyle`, `alpha`, `label`, axes-fraction `xmin`/`xmax` (or `ymin`/`ymax`) |
 | `.axhspan(ymin, ymax, **opts)` / `.axvspan(xmin, xmax, **opts)` | `color`, `alpha`, `label`, axes-fraction `xmin`/`xmax` (or `ymin`/`ymax`) |
 | `.imshow(data, **opts)` | `cmap` (any matplotlib name, default `"viridis"`), `vmin`, `vmax`, `extent=(left, right, bottom, top)` |
+| `.heatmap(df, **opts)` | `cmap`, `vmin`, `vmax`, `norm`, `center`, `xticklabels`, `yticklabels`, `legend` |
 
 `hue=<col>` (on `.line` / `.scatter`) splits into one call per unique value with auto-labels and tab10 colors. Reference lines and spans default to black; spans use `alpha=0.2`. They're drawn outside the data color cycle and don't participate in autoscaling — they're decorations on the frame, not data.
 
 `.imshow(data)` renders a 2-D array as a colored grid. Small grids (`nrows × ncols ≤ 10000`) emit one `<rect>` per cell and stay vector-clean at any zoom; larger grids encode as a single base64 PNG and quantize to 256 levels. Image row 0 is rendered at the top of its rectangle; the y axis stays Cartesian (small at bottom). All ~180 matplotlib colormaps are vendored — see `pt.list_colormaps()`.
 
+`.heatmap(df)` is the DataFrame-aware companion to `.imshow`. A pandas DataFrame's `index` becomes the row tick labels and `columns` becomes the column tick labels; row 0 sits at the top. For a plain 2-D array, default labels are integer indices — pass `xticklabels=` / `yticklabels=` to override. Cells render at integer + 0.5 centers on a linear axis, which lines up with scipy's dendrogram leaf positions so a top/left dendrogram pairs cleanly via `share_x` / `share_y`.
+
 ### Subplots
 
 Compose multi-panel layouts with operators on `Chart`:
@@ -81,10 +85,11 @@ pt.grid([[a, b],       # 2-D grid; cells may be `None`
          [c, d]])
 
 # Share x or y across panels — collapses the gap between them
-# and forces both onto the source's scale.
+# and unions data ranges; the first leaf in reading order anchors
+# the scale, others are aspect-scaled to match.
 top  = pt.chart()
-main = pt.chart(share_x=top)
-top / main             # vertically stacked, x-axis joined
+main = pt.chart()
+(top / main).share_x()         # vertically stacked, x-axis joined
 
 # Layout-level legend (covers colorbar and discrete swatches in
 # one constructor — geometry follows from the source's color mapping).
@@ -118,7 +123,7 @@ c.write_html("plot.html")    # standalone HTML
 
 ## Adding a new plot type
 
-plotlet's central hackability claim: a custom plot type is a 3-step recipe (~50–100 lines) that gets axes, scales, legend, grid, and composability for free. The recommended home is your own project, or [`cookbook/`](cookbook/) as reference. Full guide: [docs/EXTENDING.md](docs/EXTENDING.md).
+plotlet is designed so that adding a new plot type is a 3-step recipe (~50–100 lines) that gets axes, scales, legend, grid, and composability for free. The recommended home is your own project, or [`cookbook/`](cookbook/) as reference. Full guide: [docs/EXTENDING.md](docs/EXTENDING.md).
 
 ## Testing
 
@@ -132,7 +137,7 @@ python tests/test_subplots.py         # subplot baselines + composition invarian
 ## Non-goals
 
 - No interactivity (hover, zoom, click). Static rendering is the point.
-- Not competing with matplotlib on standard plots; matplotlib is bigger and battle-tested.
+- Not aiming for full coverage of standard statistical plots — those needs are well-served elsewhere.
 - Not a 3D plotter, not a dashboard tool.
 - Not a feature catalog — new plot types belong in user projects or `cookbook/`, not in the core.
 

{plotlet-0.2.0 → plotlet-0.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plotlet"
-version = "0.2.0"
-description = "Small, hackable Python library that emits matplotlib-style SVG plots."
+version = "0.4.0"
+description = "Python library for SVG plots, with multi-panel composition and an extension API for custom plot types."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -36,6 +36,7 @@ classifiers = [
 ]
 dependencies = [
   "fonttools>=4.0",
+  "scipy>=1.10",
 ]
 
 [project.optional-dependencies]

plotlet-0.4.0/src/plotlet/__init__.py

@@ -0,0 +1,33 @@
+"""plotlet — pure-Python SVG renderer, matplotlib-flavored.
+
+    import plotlet as pt
+    c = pt.chart(df, title="...", xlabel="x", ylabel="y", legend=True, grid=True)
+    c.line(x="time", y="value", hue="series")
+    c                         # auto-renders in Jupyter
+
+For non-tabular use, the chained form works directly on the same Chart:
+
+    c = pt.chart()
+    c.plot([1, 2, 3], [1, 4, 9], label="squares")
+    c.title("Hello").legend().grid(True)
+    c
+"""
+from ._spec import SPEC
+from .colors import TAB10, colors
+from .colormaps import colormap, list_colormaps
+from .chart import Chart, chart
+from .layout import grid
+from .legend import legend
+from .registry import ArtistSpec, add_artist
+from .layout_diagram import layout_diagram
+
+__all__ = ["chart", "Chart", "SPEC", "TAB10", "colors",
+           "colormap", "list_colormaps", "grid", "legend",
+           "ArtistSpec", "add_artist", "layout_diagram"]
+
+# Single source of truth: pyproject.toml. importlib.metadata reads it at
+# runtime from the installed package metadata (works for `pip install` and
+# `pip install -e .` alike). Migrating to setuptools_scm later doesn't
+# touch this code — it just changes how pyproject.toml's version is set.
+from importlib.metadata import version as _pkg_version
+__version__ = _pkg_version("plotlet")