plotlet 0.1.0__tar.gz → 0.1.3__tar.gz

{plotlet-0.1.0/src/plotlet.egg-info → plotlet-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotlet
-Version: 0.1.0
+Version: 0.1.3
 Summary: Small, hackable Python library that emits matplotlib-style SVG plots.
 Author: gitbamboo42
 License-Expression: MIT
@@ -33,7 +33,7 @@ A small, hackable Python library that emits matplotlib-style SVG plots.
 
 ## Why
 
-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 is ~700 lines of Python with a deliberately tiny, exposed core: adding a new plot type is a 3-step recipe, not an architecture project.
+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.
 
 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.
 
@@ -53,12 +53,8 @@ c                                        # auto-renders in Jupyter
 
 ## Install
 
-Not on PyPI yet — clone and install editable:
-
 ```bash
-git clone <repo>
-cd plotlet
-pip install -e .
+pip install plotlet
 ```
 
 ## Properties
@@ -68,6 +64,7 @@ pip install -e .
 - **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).
 
 ## API
 
@@ -77,7 +74,11 @@ pip install -e .
 
 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="log"|"linear"`, `yscale=...`, `grid=True/False`, `legend=True/False`, `width`, `height`
+`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`, `width`, `height`
+
+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).
+
+Tick customization: `c.xticks([0, 5, 10], ["A","B","C"], rotation=45, fontsize=12, direction="out", marks=False)`. Pass `[]` to hide. `yticks(...)` works the same way.
 
 ### Mark methods
 
@@ -88,8 +89,45 @@ Pass at construction (`pt.chart(data, title=..., grid=True, ...)`) or as chained
 | `.bar(x=, y=, **opts)` | `color`, `label`, `alpha` |
 | `.hist(x=, **opts)` | `bins`, `color`, `alpha`, `label` |
 | `.fill_between(x=, y1=, y2=, **opts)` | `color`, `alpha`, `label` |
+| `.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)` |
+
+`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()`.
+
+### Subplots
+
+Compose multi-panel layouts with operators on `Chart`:
+
+```python
+a | b                  # side-by-side
+a / b                  # stacked
+a | b | c              # left-fold flatten — one row of three, not nested
+
+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.
+top  = pt.chart()
+main = pt.chart(share_x=top)
+top / main             # vertically stacked, x-axis joined
+
+# Layout-level legend (covers colorbar and discrete swatches in
+# one constructor — geometry follows from the source's color mapping).
+hm = pt.chart(); hm.imshow(matrix, cmap="viridis")
+hm | pt.legend(hm)             # heatmap + colorbar (gradient strip)
+
+# Multi-source: groups by chart, using each chart's title as
+# section header. `names={chart: "Override"}` renames a header,
+# `names={chart: None}` hides it, `group_by_chart=False` flattens.
+(hm | top) | pt.legend()       # auto-collects from siblings
+parent = a | b; parent.legend()  # sugar for parent | pt.legend()
+```
 
-`hue=<col>` (on `.line` / `.scatter`) splits into one call per unique value with auto-labels and tab10 colors.
+A composed chart owns its children; render the parent (`(a | b).show()` or `.to_svg()` / `.save_svg(...)`). Calling `.show()` on a child raises. See [`docs/SUBPLOTS.md`](docs/SUBPLOTS.md) for the design rationale.
 
 ### Render / save
 
@@ -117,6 +155,7 @@ plotlet's central hackability claim: a custom plot type is a 3-step recipe (~50
 python tests/test_chart.py            # check vs. committed baselines
 python tests/test_chart.py --update   # regenerate (review the diff!)
 python tests/test_chart.py --gallery  # build tests/baseline_images/chart/index.html
+python tests/test_subplots.py         # subplot baselines + composition invariants
 ```
 
 ## Non-goals

{plotlet-0.1.0 → plotlet-0.1.3}/README.md

@@ -4,7 +4,7 @@ A small, hackable Python library that emits matplotlib-style SVG plots.
 
 ## Why
 
-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 is ~700 lines of Python with a deliberately tiny, exposed core: adding a new plot type is a 3-step recipe, not an architecture project.
+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.
 
 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.
 
@@ -24,12 +24,8 @@ c                                        # auto-renders in Jupyter
 
 ## Install
 
-Not on PyPI yet — clone and install editable:
-
 ```bash
-git clone <repo>
-cd plotlet
-pip install -e .
+pip install plotlet
 ```
 
 ## Properties
@@ -39,6 +35,7 @@ pip install -e .
 - **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).
 
 ## API
 
@@ -48,7 +45,11 @@ pip install -e .
 
 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="log"|"linear"`, `yscale=...`, `grid=True/False`, `legend=True/False`, `width`, `height`
+`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`, `width`, `height`
+
+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).
+
+Tick customization: `c.xticks([0, 5, 10], ["A","B","C"], rotation=45, fontsize=12, direction="out", marks=False)`. Pass `[]` to hide. `yticks(...)` works the same way.
 
 ### Mark methods
 
@@ -59,8 +60,45 @@ Pass at construction (`pt.chart(data, title=..., grid=True, ...)`) or as chained
 | `.bar(x=, y=, **opts)` | `color`, `label`, `alpha` |
 | `.hist(x=, **opts)` | `bins`, `color`, `alpha`, `label` |
 | `.fill_between(x=, y1=, y2=, **opts)` | `color`, `alpha`, `label` |
+| `.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)` |
+
+`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()`.
+
+### Subplots
+
+Compose multi-panel layouts with operators on `Chart`:
+
+```python
+a | b                  # side-by-side
+a / b                  # stacked
+a | b | c              # left-fold flatten — one row of three, not nested
+
+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.
+top  = pt.chart()
+main = pt.chart(share_x=top)
+top / main             # vertically stacked, x-axis joined
+
+# Layout-level legend (covers colorbar and discrete swatches in
+# one constructor — geometry follows from the source's color mapping).
+hm = pt.chart(); hm.imshow(matrix, cmap="viridis")
+hm | pt.legend(hm)             # heatmap + colorbar (gradient strip)
+
+# Multi-source: groups by chart, using each chart's title as
+# section header. `names={chart: "Override"}` renames a header,
+# `names={chart: None}` hides it, `group_by_chart=False` flattens.
+(hm | top) | pt.legend()       # auto-collects from siblings
+parent = a | b; parent.legend()  # sugar for parent | pt.legend()
+```
 
-`hue=<col>` (on `.line` / `.scatter`) splits into one call per unique value with auto-labels and tab10 colors.
+A composed chart owns its children; render the parent (`(a | b).show()` or `.to_svg()` / `.save_svg(...)`). Calling `.show()` on a child raises. See [`docs/SUBPLOTS.md`](docs/SUBPLOTS.md) for the design rationale.
 
 ### Render / save
 
@@ -88,6 +126,7 @@ plotlet's central hackability claim: a custom plot type is a 3-step recipe (~50
 python tests/test_chart.py            # check vs. committed baselines
 python tests/test_chart.py --update   # regenerate (review the diff!)
 python tests/test_chart.py --gallery  # build tests/baseline_images/chart/index.html
+python tests/test_subplots.py         # subplot baselines + composition invariants
 ```
 
 ## Non-goals

{plotlet-0.1.0 → plotlet-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plotlet"
-version = "0.1.0"
+version = "0.1.3"
 description = "Small, hackable Python library that emits matplotlib-style SVG plots."
 readme = "README.md"
 license = "MIT"

{plotlet-0.1.0 → plotlet-0.1.3}/src/plotlet/__init__.py

@@ -16,8 +16,14 @@ Chained API (legacy, still supported):
 """
 from ._spec import SPEC
 from .colors import TAB10, colors
+from .colormaps import colormap, list_colormaps
 from .core import Figure, figure
 from .chart import Chart, chart
+from .layout import grid
+from .legend import legend
+from .registry import ArtistSpec, add_artist
 
-__all__ = ["chart", "Chart", "figure", "Figure", "SPEC", "TAB10", "colors"]
-__version__ = "0.1.0"
+__all__ = ["chart", "Chart", "figure", "Figure", "SPEC", "TAB10", "colors",
+           "colormap", "list_colormaps", "grid", "legend",
+           "ArtistSpec", "add_artist"]
+__version__ = "0.1.3"