plotlet 0.1.3__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotlet
-Version: 0.1.3
+Version: 0.3.0
 Summary: Small, hackable Python library that emits matplotlib-style SVG plots.
 Author: gitbamboo42
 License-Expression: MIT
@@ -62,9 +62,10 @@ pip install plotlet
 - **Lightweight.** `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.
+- **Jupyter-native.** `Chart._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).
+- **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 +75,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`, `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`, `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"`).
 
 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).
 
@@ -110,10 +111,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).

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

@@ -33,9 +33,10 @@ pip install plotlet
 - **Lightweight.** `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.
+- **Jupyter-native.** `Chart._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).
+- **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`, `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`, `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"`).
 
 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).
 
@@ -81,10 +82,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).

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

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

plotlet-0.3.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")

{plotlet-0.1.3 → plotlet-0.3.0}/src/plotlet/builtin_artists.py

@@ -79,6 +79,98 @@ def _refspan_legend_swatch(a, ctx, x0, y_mid):
     return _rect_swatch(a, x0, y_mid, ctx.defaults["refspan_alpha"])
 
 
+# --- AI-readable structural attrs + payloads (0.3.0) ------------------------
+# Each helper computes type-specific attrs from the recorded artist dict.
+# The wrapper in core._wrap_artist supplies the common attrs (type, index,
+# label, color); these add the per-artist fields. Returned dict keys map
+# 1:1 to `data-plotlet-<key>` attribute names.
+
+def _xy_minmax(xs, ys):
+    """Min/max for an x/y series, ignoring NaN. Returns dict ready to merge
+    into a data_attrs result."""
+    fxs = [x for x in xs if isinstance(x, (int, float)) and x == x]
+    fys = [y for y in ys if isinstance(y, (int, float)) and y == y]
+    out = {}
+    if fxs:
+        out["x-min"] = min(fxs)
+        out["x-max"] = max(fxs)
+    if fys:
+        out["y-min"] = min(fys)
+        out["y-max"] = max(fys)
+    return out
+
+
+def _plot_data_attrs(a):
+    out = {"n": len(a["xs"])}
+    out.update(_xy_minmax(a["xs"], a["ys"]))
+    if a["opts"].get("linestyle"):
+        out["linestyle"] = a["opts"]["linestyle"]
+    if a["opts"].get("marker"):
+        out["marker"] = a["opts"]["marker"]
+    return out
+
+
+def _scatter_data_attrs(a):
+    out = {"n": len(a["xs"])}
+    out.update(_xy_minmax(a["xs"], a["ys"]))
+    out["marker"] = a["opts"].get("marker", "o")
+    return out
+
+
+def _bar_data_attrs(a):
+    fvals = [v for v in a["vals"] if isinstance(v, (int, float)) and v == v]
+    out = {"n": len(a["cats"])}
+    if fvals:
+        out["y-min"] = min(fvals)
+        out["y-max"] = max(fvals)
+    return out
+
+
+def _hist_data_attrs(a):
+    raw = a["data"]
+    out = {"n": len(raw), "bins": len(a.get("_bins", [])) or a["opts"].get("bins", 10)}
+    bins = a.get("_bins") or []
+    if bins:
+        out["x-min"] = bins[0]["x0"]
+        out["x-max"] = bins[-1]["x1"]
+        out["count-max"] = max(b["count"] for b in bins)
+    return out
+
+
+def _fill_between_data_attrs(a):
+    ys_all = list(a["y1"]) + list(a["y2"])
+    out = {"n": len(a["xs"])}
+    out.update(_xy_minmax(a["xs"], ys_all))
+    return out
+
+
+def _axhline_data_attrs(a):  return {"y": a["y"]}
+def _axvline_data_attrs(a):  return {"x": a["x"]}
+def _axhspan_data_attrs(a):  return {"ymin": a["ymin"], "ymax": a["ymax"]}
+def _axvspan_data_attrs(a):  return {"xmin": a["xmin"], "xmax": a["xmax"]}
+
+
+def _imshow_data_attrs(a):
+    out = {
+        "rows": a["_nrows"],
+        "cols": a["_ncols"],
+        "vmin": a["_vmin"],
+        "vmax": a["_vmax"],
+        "cmap": a["opts"].get("cmap", _D["default_cmap"]),
+        # imshow is always raster (PNG-embedded above the rect threshold,
+        # individual <rect>s below). The flag is here so AI tools know
+        # which decoding strategy they're looking at.
+        "data-encoding": "png-embedded" if (a["_nrows"] * a["_ncols"]
+                                              > _D["imshow_max_rects"]) else "rects",
+    }
+    extent = a["opts"].get("extent")
+    if extent is not None:
+        out["extent"] = ",".join(repr(float(v)) for v in extent)
+    return out
+
+
+
+
 # --- plot (line) ------------------------------------------------------------
 
 add_artist(ArtistSpec(
@@ -89,6 +181,7 @@ add_artist(ArtistSpec(
     ydomain=_ys_of,
     draw=lambda a, ctx: _artist_plot(a, ctx.x_scale, ctx.y_scale, ctx.color),
     legend_swatch=_plot_legend_swatch,
+    data_attrs=_plot_data_attrs,
 ))
 
 
@@ -102,6 +195,7 @@ add_artist(ArtistSpec(
     ydomain=_ys_of,
     draw=lambda a, ctx: _artist_scatter(a, ctx.x_scale, ctx.y_scale, ctx.color),
     legend_swatch=_scatter_legend_swatch,
+    data_attrs=_scatter_data_attrs,
 ))
 
 
@@ -117,6 +211,7 @@ add_artist(ArtistSpec(
     ydomain=_vals_of,
     draw=lambda a, ctx: _artist_bar(a, ctx.x_scale, ctx.y_scale, ctx.color),
     legend_swatch=_bar_legend_swatch,
+    data_attrs=_bar_data_attrs,
 ))
 
 
@@ -129,6 +224,7 @@ add_artist(ArtistSpec(
     ydomain=_bin_ys,
     draw=lambda a, ctx: _artist_hist(a, ctx.x_scale, ctx.y_scale, ctx.ih, ctx.color),
     legend_swatch=_bar_legend_swatch,
+    data_attrs=_hist_data_attrs,
 ))
 
 
@@ -145,6 +241,7 @@ add_artist(ArtistSpec(
     ydomain=_y1y2_of,
     draw=lambda a, ctx: _artist_fill_between(a, ctx.x_scale, ctx.y_scale, ctx.color),
     legend_swatch=_plot_legend_swatch,
+    data_attrs=_fill_between_data_attrs,
 ))
 
 
@@ -160,6 +257,7 @@ add_artist(ArtistSpec(
     uses_color_cycle=False,
     default_color=_D["refline_color"],
     legend_swatch=_refline_legend_swatch,
+    data_attrs=_axhline_data_attrs,
 ))
 
 add_artist(ArtistSpec(
@@ -171,6 +269,7 @@ add_artist(ArtistSpec(
     uses_color_cycle=False,
     default_color=_D["refline_color"],
     legend_swatch=_refline_legend_swatch,
+    data_attrs=_axvline_data_attrs,
 ))
 
 add_artist(ArtistSpec(
@@ -182,6 +281,7 @@ add_artist(ArtistSpec(
     uses_color_cycle=False,
     default_color=_D["refspan_color"],
     legend_swatch=_refspan_legend_swatch,
+    data_attrs=_axhspan_data_attrs,
 ))
 
 add_artist(ArtistSpec(
@@ -193,6 +293,7 @@ add_artist(ArtistSpec(
     uses_color_cycle=False,
     default_color=_D["refspan_color"],
     legend_swatch=_refspan_legend_swatch,
+    data_attrs=_axvspan_data_attrs,
 ))
 
 
@@ -251,4 +352,5 @@ add_artist(ArtistSpec(
     draw=lambda a, ctx: _artist_imshow(a, ctx.x_scale, ctx.y_scale, None),
     legend_gradient=_imshow_legend_gradient,
     uses_color_cycle=False,
+    data_attrs=_imshow_data_attrs,
 ))