plotlet 0.6.4__tar.gz → 0.7.0__tar.gz

{plotlet-0.6.4/src/plotlet.egg-info → plotlet-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotlet
-Version: 0.6.4
+Version: 0.7.0
 Summary: Python library for reproducible, multi-panel scientific figures, with byte-identical output across machines and an extension API for custom plot types.
 Author: gitbamboo42
 License-Expression: MIT
@@ -31,6 +31,7 @@ Requires-Dist: nbconvert; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Requires-Dist: pandas; extra == "test"
+Requires-Dist: jsonschema; extra == "test"
 Provides-Extra: pdf
 Requires-Dist: cairosvg; extra == "pdf"
 Dynamic: license-file

{plotlet-0.6.4 → plotlet-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plotlet"
-version = "0.6.4"
+version = "0.7.0"
 description = "Python library for reproducible, multi-panel scientific figures, with byte-identical output across machines and an extension API for custom plot types."
 readme = "README.md"
 license = "MIT"
@@ -48,6 +48,7 @@ dev = [
 test = [
   "pytest>=7",
   "pandas",
+  "jsonschema",
 ]
 pdf = [
   "cairosvg",
@@ -74,4 +75,12 @@ plotlet = ["spec.json", "themes/*.json", "draw/fonts/*.ttf", "draw/fonts/*.txt",
            # AI onboarding: pt.skill() reads skills/, and the guides point
            # at the shipped docs/ and examples/ so an installed package is
            # self-sufficient — no repo clone, no web access needed.
-           "skills/*.md", "docs/*.md", "examples/*.py"]
+           "skills/*.md", "docs/*.md", "examples/*.py",
+           # JSON twins of the examples, for authoring plots as JSON
+           # journals (skills/json.md). Generated by
+           # tests/gen_json_examples.py — never edited by hand.
+           "examples/json/*.json",
+           # JSON Schema for journal-lite blobs, for editor/server-side
+           # validation. Generated by tests/gen_json_schema.py from
+           # pt.op_schema() — never edited by hand.
+           "schemas/*.json"]

{plotlet-0.6.4 → plotlet-0.7.0}/src/plotlet/__init__.py

@@ -34,8 +34,16 @@ from .formatters import (register_formatter, list_formatters,
 from ._coord_registry import register_coord_codec
 from .record.journal import (to_journal, from_journal, to_json, from_json,
                        JournalNode, Journal)
+from .record.journal_lite import to_json_lite, from_json_lite
+from .record.codegen import to_python
 from .record.figure_ir import to_ir, from_ir, FigureIR, IRNode
 from .skill import skill
+# Shadows the `plotlet.lint` submodule attribute with the function —
+# the os.path-style pattern: `pt.lint(c)` calls it, and
+# `from plotlet.lint import lint` still resolves via sys.modules.
+from .lint import lint
+from .describe import describe
+from .op_help import op_help, op_schema  # same shadowing pattern as lint
 from . import draw, utils
 
 
@@ -62,10 +70,11 @@ __all__ = ["chart", "Chart", "Layout", "SPEC", "TAB10",
            "linkage", "linkage_split", "SplitTree",
            "register_formatter", "list_formatters",
            "superscript", "subscript",
-           "to_json", "from_json", "register_coord_codec",
+           "to_json", "from_json", "to_json_lite", "from_json_lite",
+           "to_python", "register_coord_codec",
            "to_journal", "from_journal", "JournalNode", "Journal",
            "to_ir", "from_ir", "FigureIR", "IRNode",
-           "skill",
+           "skill", "lint", "describe", "op_help", "op_schema",
            "draw", "utils"]
 
 # Single source of truth: pyproject.toml. importlib.metadata reads it at

{plotlet-0.6.4 → plotlet-0.7.0}/src/plotlet/_json_layer.py

@@ -36,6 +36,7 @@ both halves need it (the render tree's hydrator and the front half's
 facet expansion) and it resolves only against shared vocabulary.
 """
 from __future__ import annotations
+import json
 from typing import Any
 
 import numpy as np
@@ -136,6 +137,53 @@ def json_hydrate(value: Any) -> Any:
     return value
 
 
+_PRETTY_WIDTH = 100     # target line width for pretty_dumps
+
+
+def pretty_dumps(value: Any) -> str:
+    """Canonical JSON text form — what `pt.to_json` returns and the
+    shipped example twins use. Objects and arrays stay on one line when
+    they fit in `_PRETTY_WIDTH` columns; a too-long dict or mixed list
+    expands one element per line (1-space indent steps); a too-long
+    list of primitives wraps at the width, continuation lines aligned
+    under its opening bracket — so journal entries read structurally
+    while data columns stay a few dense lines. Deterministic (same
+    value → same bytes) and whitespace-only: `json.loads` of the
+    result equals `json.loads(json.dumps(value))`."""
+    return _pretty(value, 0, "")
+
+
+def _pretty(value: Any, col: int, pad: str) -> str:
+    """Render `value` starting at column `col`; `pad` is the
+    indentation of the enclosing construct."""
+    compact = json.dumps(value)
+    if col + len(compact) <= _PRETTY_WIDTH \
+            or not isinstance(value, (dict, list)):
+        return compact
+    inner = pad + " "
+    if isinstance(value, dict):
+        lines = []
+        for k, v in value.items():
+            key = f"{inner}{json.dumps(k)}: "
+            lines.append(key + _pretty(v, len(key), inner))
+        return "{\n" + ",\n".join(lines) + "\n" + pad + "}"
+    if all(not isinstance(v, (dict, list)) for v in value):
+        room = max(_PRETTY_WIDTH - col - 1, 20)     # width left after "["
+        parts, lines, used = [json.dumps(v) for v in value], [], -2
+        for part in parts:
+            if used < 0 or used + 2 + len(part) > room:
+                lines.append([part])
+                used = len(part)
+            else:
+                lines[-1].append(part)
+                used += 2 + len(part)
+        joined = (",\n" + " " * (col + 1)).join(
+            ", ".join(line) for line in lines)
+        return "[" + joined + "]"
+    lines = [inner + _pretty(v, len(inner), inner) for v in value]
+    return "[\n" + ",\n".join(lines) + "\n" + pad + "]"
+
+
 def _decode(value: Any, nid_to_node: dict, data_table: dict) -> Any:
     """Resolve plotlet's *reference* envelopes back to live objects —
     `{"$node"}` via `nid_to_node`, `{"$coord"}` via the coord registry,

{plotlet-0.6.4 → plotlet-0.7.0}/src/plotlet/_regions.py

@@ -58,6 +58,11 @@ class _Sink:
     # offset to recorded bboxes so consumers receive outer-SVG coords
     # regardless of whether the chart is single- or multi-panel.
     translate_stack: list[tuple[float, float]] = field(default_factory=list)
+    # Depth of active `structural()` blocks — chrome recorded inside
+    # one lives inside the panel rect by design (coordinate-owned
+    # chrome, an inside-positioned legend), so overlap lint can tell
+    # it from misplaced chrome.
+    structural_depth: int = 0
 
     def _offset(self) -> tuple[float, float]:
         dx = dy = 0.0
@@ -75,6 +80,12 @@ class _Sink:
         # the bbox in outer-SVG coords.
         if "polygon" in meta:
             meta["polygon"] = [(px + dx, py + dy) for px, py in meta["polygon"]]
+        # Multi-line text ships one quad per inked line under `lines`.
+        if "lines" in meta:
+            meta["lines"] = [[(px + dx, py + dy) for px, py in quad]
+                             for quad in meta["lines"]]
+        if self.structural_depth:
+            meta.setdefault("structural", True)
         self.regions.append(Region(kind=kind, bbox=(x + dx, y + dy, w, h),
                                    name=name, meta=meta))
 
@@ -128,6 +139,26 @@ def suppressed():
         _CURRENT.reset(token)
 
 
+@contextmanager
+def structural():
+    """Mark every region recorded in the block as `structural=True` —
+    chrome that lives inside the panel rect *by design*, so its overlap
+    with the panel/spines is rendering geometry, not a layout bug.
+    Wrapped around coordinate-owned chrome emission (a circular chart's
+    angular tick labels and sector walls all sit inside the data ring)
+    and an inside-positioned legend's body. Overlap lint skips
+    structural-vs-container pairs. No-op when no sink is active."""
+    sink = _CURRENT.get()
+    if sink is None:
+        yield
+        return
+    sink.structural_depth += 1
+    try:
+        yield
+    finally:
+        sink.structural_depth -= 1
+
+
 @contextmanager
 def translate(dx: float, dy: float):
     """Push a translate offset onto the sink's transform stack for the

plotlet-0.7.0/src/plotlet/_spec.py

@@ -0,0 +1,187 @@
+"""Visual spec — loaded from `spec.json` at import time. Internal.
+
+The spec is the locked visual contract: colors, fonts, sizes, default alphas,
+legend dimensions. Submodules read from here to avoid hardcoding literals.
+
+`SPEC` and the per-section handles (`_FRAME`, `_GRIDSPEC`, …) are *live dicts*:
+when a chart's `theme=` is applied, [`active_theme(name)`](#active_theme)
+mutates the inner contents of these dicts so every module sees the
+override without an import-time refactor. The previous contents are
+restored when the context exits.
+
+Decision note — module-level mutation vs the no-global-state policy
+-------------------------------------------------------------------
+The policy ("no global state: themes per-chart, deterministic") is about
+what a *user* can observe: no chart's theme leaks into another, and the
+same script renders byte-identical SVG everywhere. This module satisfies
+that with scoped mutation, not with parameter threading:
+
+- `active_theme` wraps each leaf's render and measurement walk in
+  `_layout_engine`; restore runs in `try/finally`, so an exception
+  inside a render still restores. `load_theme(name)` is evaluated
+  before any mutation, so an unknown theme raises without touching the
+  spec.
+- Rendering is synchronous and single-threaded, so the swap is
+  invisible from outside a render call. The known limit: rendering two
+  charts concurrently from *user* threads would interleave spec
+  mutations. Accepted deliberately — threading a spec object through
+  every draw/measure call in every render module buys thread safety
+  nobody has asked for at the cost of noise on every signature. Revisit
+  if a concurrent-render use case actually appears.
+"""
+from __future__ import annotations
+
+import contextlib
+import copy
+import difflib
+
+from .themes import load_theme, _deep_merge
+
+
+def _install(target, source) -> None:
+    """Replace `target`'s contents with `source`'s, preserving identity of
+    nested mutable containers (dicts AND lists). Used to swap themes
+    without breaking references that other modules captured at import
+    time via `from ._spec import _FRAME`. Nested dicts
+    and lists that exist on both sides are recursed into so their
+    identity survives; mismatched-type or absent-on-target values are
+    deep-copied wholesale.
+    """
+    if isinstance(target, dict) and isinstance(source, dict):
+        for k in list(target.keys()):
+            if k not in source:
+                del target[k]
+        for k, v in source.items():
+            existing = target.get(k)
+            if isinstance(v, dict) and isinstance(existing, dict):
+                _install(existing, v)
+            elif isinstance(v, list) and isinstance(existing, list):
+                _install(existing, v)
+            else:
+                target[k] = copy.deepcopy(v)
+    elif isinstance(target, list) and isinstance(source, list):
+        target.clear()
+        target.extend(copy.deepcopy(item) for item in source)
+
+
+# Initialize from the locked default theme. Every module that imports
+# `_FRAME`, `_FONTSPEC`, … gets a reference to one of these dicts; their
+# contents change when `active_theme(name)` is in effect.
+SPEC: dict = {}
+_install(SPEC, load_theme("classic"))
+
+_DASH = SPEC["linestyles"]
+_SCALESPEC = SPEC["scale"]
+_RASTERSPEC = SPEC["raster"]
+_FRAME = SPEC["frame"]
+_GRIDSPEC = SPEC["grid"]
+_FONTSPEC = SPEC["font"]
+_LEGSPEC = SPEC["legend"]
+_PADSPEC = SPEC["pad"]
+_SIZESPEC = SPEC["size"]
+_MARGIN_FLOOR = SPEC["size"]["margin_floor"]
+_OUTER_MARGIN = SPEC["size"]["outer_margin"]
+_LAYOUTSPEC = SPEC["layout"]
+_FIGSPEC = SPEC["figure"]
+
+_CURRENT_THEME: str = "classic"
+
+
+def current_theme() -> str:
+    """Name of the theme currently installed in the spec dicts."""
+    return _CURRENT_THEME
+
+
+def _swap_to(name: str | None, overrides: dict | None = None) -> dict:
+    """Install theme `name` (deep-merged with per-chart `overrides`, if
+    any) into the live spec dicts; return the previous full SPEC
+    snapshot for later restoration. `_install` recurses into nested
+    dicts and lists, so module-level handles at any depth (`_FRAME`,
+    `_MARGIN_FLOOR`, …) keep their identity. The merge never
+    touches `load_theme`'s cache — `_deep_merge` copies its base."""
+    global _CURRENT_THEME
+    snapshot = copy.deepcopy(SPEC)
+    prev_theme = _CURRENT_THEME
+    resolved = load_theme(name)
+    if overrides:
+        resolved = _deep_merge(resolved, overrides)
+    _install(SPEC, resolved)
+    _CURRENT_THEME = name if name is not None else "classic"
+    return {"spec": snapshot, "theme": prev_theme}
+
+
+def _restore(snapshot: dict) -> None:
+    global _CURRENT_THEME
+    _install(SPEC, snapshot["spec"])
+    _CURRENT_THEME = snapshot["theme"]
+
+
+def _bad_key(key: str, candidates, where: str) -> ValueError:
+    hint = difflib.get_close_matches(key, list(candidates), n=1)
+    did_you_mean = f"; did you mean {hint[0]!r}?" if hint else ""
+    return ValueError(
+        f"spec override: no key {key!r} in {where}{did_you_mean} "
+        f"Available: {sorted(candidates)}"
+    )
+
+
+def validate_overrides(overrides: dict) -> None:
+    """Check `c.spec(...)` overrides against the spec's shape: every
+    kwarg must be a root spec key — a section/block (`font`, `grid`,
+    `scatter`, …) holding a dict, or one of the shared scalar keys
+    (`linewidth`, `cmap`, …) — and every key inside a dict must exist
+    at that path in the classic spec; the deep merge would silently
+    absorb a typo like `titlesize` otherwise. Validation runs against
+    the classic spec (`load_theme("classic")`), never the live dicts
+    above: those are mutated mid-render by `active_theme`, while
+    classic is the stable shape authority. Values are not type-checked
+    beyond the dict/scalar split; the spec's leaves are too
+    heterogeneous for that to pay its way."""
+    spec = load_theme("classic")
+    valid = {k: v for k, v in spec.items() if k != "version"}
+    for key, value in overrides.items():
+        if key not in valid:
+            raise _bad_key(key, valid, "the spec")
+        if isinstance(valid[key], dict):
+            if not isinstance(value, dict):
+                raise TypeError(
+                    f"spec override {key!r} must be a dict of "
+                    f"{key}.* keys, got {type(value).__name__}"
+                )
+            _validate_section(value, valid[key], key)
+        elif isinstance(value, dict):
+            raise TypeError(
+                f"spec override {key!r} takes a single value, "
+                "got a dict"
+            )
+
+
+def _validate_section(override: dict, base: dict, path: str) -> None:
+    for k, v in override.items():
+        if k not in base:
+            raise _bad_key(k, base.keys(), f"spec section {path!r}")
+        if isinstance(base[k], dict) and isinstance(v, dict):
+            _validate_section(v, base[k], f"{path}.{k}")
+
+
+@contextlib.contextmanager
+def active_theme(name: str | None, overrides: dict | None = None):
+    """Apply theme `name` to the live spec dicts for the duration of the
+    `with` block. `None` is a passthrough — used by code paths that
+    haven't decided a theme yet (e.g. parent rendering before walking
+    into a leaf that may set its own).
+
+    `overrides` carries a chart's accumulated `c.spec(...)` values,
+    deep-merged over the named theme. With overrides present the swap
+    always runs — even `name=None` means "classic + overrides", not a
+    passthrough — and never short-circuits on the current-theme name,
+    since the merged spec differs from the plain named one.
+    """
+    if not overrides and (name is None or name == _CURRENT_THEME):
+        yield
+        return
+    snapshot = _swap_to(name, overrides)
+    try:
+        yield
+    finally:
+        _restore(snapshot)

{plotlet-0.6.4 → plotlet-0.7.0}/src/plotlet/artists/_shared.py

@@ -2,7 +2,8 @@
 
 Each built-in artist registers one of the `*_legend_entries` functions so
 the legend dispatch in `_render_inner` can stay generic — no type-string matching.
-Paint logic is a nested closure; there are no shared swatch helpers.
+Paint logic is a nested closure; the only shared swatch helpers are the
+two size clamps (`swatch_radius` / `swatch_stroke`).
 
 The `pool_*` / `rgb_buffer` helpers back the PNG-embedded raster paths of
 image_cmap / image_rgba and heatmap: a grid denser than the display can show is box-pooled
@@ -14,20 +15,65 @@ import math
 
 import numpy as np
 
-from .._spec import _LEGSPEC, _D
-from ..draw import marker, segment, rect
+from .._spec import _LEGSPEC, SPEC, _RASTERSPEC
+from ..draw import marker, segment, rect, resolve_color
 from ..draw import TAB10
 from ..utils import to_list, resolve_aes, palette_color
 
 
+def edge_px(scale, v):
+    """Map `v` through `scale`, clamping an unmappable value to the
+    domain-lo panel edge. On a log axis a value at or below zero has no
+    pixel; connected geometry (bands, baselines, fitted lines, KDE
+    tails) draws it at the axis edge — where the panel clip cuts it
+    off — instead of printing a non-finite coordinate into the path.
+    Point markers should keep masking (skip the point): a clamped
+    marker would invent a datum at the edge."""
+    p = scale(v)
+    if math.isfinite(p):
+        return p
+    return scale.r0
+
+
+def point_outline(opts):
+    """Outline (stroke, width) for a point-cloud artist (strip/swarm),
+    per the `draw.marker` rule: `edgecolor=` turns the outline on,
+    `linewidth=` only sizes it (spec marker stroke width when omitted).
+    No edgecolor → no outline, whatever the width. Returns stroke None
+    when hidden."""
+    stroke = resolve_color(opts.get("edgecolor"))
+    if stroke is None:
+        return None, 0
+    lw = opts.get("linewidth")
+    lw = SPEC["marker_stroke_width"] if lw is None else float(lw)
+    if lw <= 0:
+        return None, 0
+    return stroke, lw
+
+
+def swatch_radius(r):
+    """Marker radius for a legend key: the plotted radius, capped so the
+    glyph stays inside its legend row. A key mirrors the mark's styling,
+    but a `size=40` dot would spill across the whole legend box and out
+    the other side — past the cap the exact radius stops carrying
+    information anyway."""
+    return min(float(r), _LEGSPEC["max_swatch_radius"])
+
+
+def swatch_stroke(w):
+    """Stroke width for a legend key, capped the same way — half of a
+    wide stroke sits outside the shape it outlines."""
+    return min(float(w), _LEGSPEC["max_swatch_stroke"])
+
+
 def pool_target(n_cells, px):
     """Output-pixel count along one raster axis: full data resolution
-    until cells outnumber `raster_oversample` per display pixel, then
+    until cells outnumber `raster.oversample` cells per display pixel, then
     capped at that. The oversample headroom keeps hi-dpi rendering and
     moderate zoom sharp; past it the viewer can't show the extra cells
     anyway, and its nearest-neighbour downscale would *subsample* them
     (drop cells) where pooling summarizes them."""
-    cap = max(1, math.ceil(px * _D["raster_oversample"]))
+    cap = max(1, math.ceil(px * _RASTERSPEC["oversample"]))
     return n_cells if n_cells <= cap else cap
 
 
@@ -309,11 +355,11 @@ def _line_legend_entries(a):
         sw = _LEGSPEC["swatch_width"]
         out = segment(x0, y_mid, x0 + sw, y_mid,
                       color=a["_color"],
-                      width=a["opts"].get("linewidth", ctx.defaults["linewidth"]),
+                      width=a["opts"].get("linewidth", ctx.spec["linewidth"]),
                       dash=a["opts"].get("linestyle"))
         if a["opts"].get("marker"):
             out += marker(a["opts"]["marker"], x0 + sw / 2, y_mid,
-                          a["opts"].get("markersize", ctx.defaults["markersize"]),
+                          a["opts"].get("markersize", ctx.spec["marker_size"]),
                           a["_color"], 1)
         return out
     return [{"label": label, "color": a.get("_color"), "paint": paint}]
@@ -327,22 +373,11 @@ def _refline_legend_entries(a):
         sw = _LEGSPEC["swatch_width"]
         return segment(x0, y_mid, x0 + sw, y_mid,
                        color=a["_color"],
-                       width=a["opts"].get("linewidth", ctx.defaults["refline_width"]),
+                       width=a["opts"].get("linewidth", ctx.spec["refline"]["linewidth"]),
                        dash=a["opts"].get("linestyle"))
     return [{"label": label, "color": a.get("_color"), "paint": paint}]
 
 
-def _bar_legend_entries(a):
-    label = a["opts"].get("label")
-    if not label:
-        return []
-    def paint(a, ctx, x0, y_mid):
-        sw = _LEGSPEC["swatch_width"]
-        return rect(x0, y_mid - 5, sw, 10, fill=a["_color"],
-                    alpha=a["opts"].get("alpha", 1))
-    return [{"label": label, "color": a.get("_color"), "paint": paint}]
-
-
 def _refspan_legend_entries(a):
     label = a["opts"].get("label")
     if not label:
@@ -350,5 +385,5 @@ def _refspan_legend_entries(a):
     def paint(a, ctx, x0, y_mid):
         sw = _LEGSPEC["swatch_width"]
         return rect(x0, y_mid - 5, sw, 10, fill=a["_color"],
-                    alpha=a["opts"].get("alpha", ctx.defaults["refspan_alpha"]))
+                    alpha=a["opts"].get("alpha", ctx.spec["refspan"]["alpha"]))
     return [{"label": label, "color": a.get("_color"), "paint": paint}]