fluxplot 0.1.0__py3-none-any.whl

fluxplot/recipe.py

@@ -0,0 +1,178 @@
+"""Assemble the ``*.recipe.json`` provenance sidecar (spec §11.3, v0 "enough to re-run here").
+
+The recipe is the **provenance surface**, deliberately separate from the deterministic manifest:
+timestamps and content hashes (which vary run-to-run) live here, so the SVG + manifest stay
+byte-stable for morph/diff while provenance stays honest.
+
+When the producing ``script`` is known, the recipe also carries a small **re-run block**
+(``command``/``args``/``cwd``/``output``) so Flux's ``rerun-plot`` (and the in-app *Regenerate*
+button) can reproduce the plot. Those paths are written **relative** so the recipe survives the
+project being moved or copied as a whole; only the interpreter (``command``) is absolute, and it is
+overridable via ``recipe["command"]``.
+
+The script no longer has to be recorded by hand: when the caller does not pass one,
+:mod:`fluxplot.provenance` discovers it from the running interpreter (safe deterministic rules
+only — see plan §1). Explicit fields always win; ``recipe=False`` suppresses discovery entirely
+for notebooks, generated figures and privacy-sensitive callers. The recipe then says *how* the
+script was determined (``provenance.scriptDiscovery``: automatic / explicit / unavailable) and
+never claims to know inputs or parameters it cannot know — there is no automatic input discovery.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+from datetime import datetime, timezone
+
+from . import provenance as _provenance
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _script_block(script) -> dict | None:
+    if script is None:
+        return None
+    if isinstance(script, dict):
+        return script
+    return {"path": str(script)}
+
+
+def _hash_input(inp, base_dir):
+    path = inp if isinstance(inp, str) else inp.get("path")
+    role = "data" if isinstance(inp, str) else inp.get("role", "data")
+    entry = {"role": role, "path": path}
+    full = path if base_dir is None else os.path.join(base_dir, path)
+    try:
+        with open(full, "rb") as f:
+            digest, size = hashlib.sha256(), 0
+            for chunk in iter(lambda: f.read(1024 * 1024), b""):
+                digest.update(chunk)
+                size += len(chunk)
+        entry["sha256"] = digest.hexdigest()
+        entry["bytes"] = size
+    except OSError:
+        entry["sha256"] = None
+    return entry
+
+
+def build_recipe(
+    recipe: dict | bool | None,
+    *,
+    plot_name: str,
+    svg_filename: str | None = None,
+    glb_filename: str | None = None,
+    manifest_filename: str,
+    spec_version: str,
+    base_dir: str | None = None,
+    recipe_dir: str | None = None,
+    now: str | None = None,
+) -> dict:
+    if (svg_filename is None) == (glb_filename is None):
+        raise ValueError("provide exactly one svg_filename or glb_filename")
+    output_name = glb_filename if glb_filename is not None else svg_filename
+    # recipe semantics (plan §1): None → automatic provenance; False → explicitly suppress it
+    # (still writes a valid, non-rerunnable recipe); a dict → explicit fields win, an inferred
+    # script only fills a *missing* script. Inputs are never discovered automatically.
+    suppress = recipe is False
+    recipe = {} if recipe in (None, False) else dict(recipe)
+
+    script = _script_block(recipe.get("script"))
+    notebook = None
+    if script is not None:
+        discovery = "explicit"
+    elif recipe.get("notebook"):
+        # a notebook cell made the plot: recorded (path, cell, hash), not rerunnable by Flux yet
+        notebook = _provenance.notebook_block(recipe["notebook"], recipe.get("cell"))
+        discovery = "notebook"
+    elif not suppress:
+        found = _provenance.discover_script()
+        if found:
+            script = {"path": found}
+            discovery = "automatic"
+        else:
+            nb = _provenance.discover_notebook()
+            if nb:
+                notebook = _provenance.notebook_block(nb, recipe.get("cell"))
+                discovery = "notebook"
+            else:
+                discovery = "unavailable"
+    else:
+        discovery = "suppressed"
+
+    inputs = recipe.get("inputs", []) or []
+    out = {
+        "spec": "fluxplot/recipe",
+        "schemaVersion": spec_version,
+        "plot": plot_name,
+        "outputs": {("glb" if glb_filename is not None else "svg"): output_name, "manifest": manifest_filename},
+        "generatedAt": now or _now_iso(),
+        "script": script,
+        "params": recipe.get("params", {}),
+        "inputs": [_hash_input(i, base_dir) for i in inputs],
+        "env": None,  # v0: full environment capture deferred (spec §11.3)
+    }
+    if notebook is not None:
+        out["notebook"] = notebook
+    if not suppress:
+        out["provenance"] = _provenance.build_provenance(
+            script.get("path") if script else (notebook["path"] if notebook else None), discovery
+        )
+        if notebook is not None and notebook["sha256"] is None:
+            out["provenance"].pop("scriptSha256", None)
+
+    # Re-run block — what flux-core's runRecipe needs to reproduce the plot. It resolves
+    # `cwd` and `output` against the recipe's OWN directory, runs `command args` (appending
+    # params as `--key value` and exporting them as $FLUX_PARAMS), so the script re-emits the
+    # SVG in place. Emitted only when we know which script produced the plot. Paths are written
+    # relative (to the recipe dir / the run cwd) for portability; the interpreter is absolute
+    # and overridable via recipe["command"].
+    script = out["script"]
+    if script and script.get("path") and recipe_dir is not None:
+        cwd_now = os.path.abspath(os.path.join(recipe_dir, recipe["cwd"])) if recipe.get("cwd") else os.getcwd()
+        script_abs = os.path.abspath(script["path"])
+        svg_abs = os.path.join(recipe_dir, output_name)
+        out["command"] = recipe.get("command") or sys.executable or "python"
+        out["args"] = list(recipe["args"]) if "args" in recipe else [os.path.relpath(script_abs, cwd_now)]
+        out["cwd"] = os.path.relpath(cwd_now, recipe_dir)
+        out["output"] = recipe.get("output", os.path.relpath(svg_abs, recipe_dir))
+    elif recipe.get("command"):  # explicit command without a script — pass through (back-compat)
+        out["command"] = recipe["command"]
+        for key in ("args", "cwd", "output"):
+            if key in recipe:
+                out[key] = recipe[key]
+    return out
+
+
+def params(defaults: dict | None = None) -> dict:
+    """Merge ``defaults`` with any ``FLUX_PARAMS`` (JSON) provided in the environment.
+
+    Read tunables through this so ``flux rerun-plot <recipe> --key value`` (and the in-app
+    *Regenerate* button, which set ``$FLUX_PARAMS``) can re-run the script with overrides::
+
+        import fluxplot as fp
+        p = fp.params({"test": "t-test", "smooth": False})
+        if p["test"] == "mann-whitney":
+            ...
+    """
+    import json as _json
+
+    out = dict(defaults or {})
+    raw = os.environ.get("FLUX_PARAMS")
+    if raw:
+        try:
+            out.update(_json.loads(raw))
+        except Exception:
+            pass
+    # `flux rerun-plot --__fluxplot__ '{…}'` hands the colour controls over as one JSON string;
+    # the block is always a mapping to the helpers.
+    controls = out.get("__fluxplot__")
+    if isinstance(controls, str):
+        try:
+            out["__fluxplot__"] = _json.loads(controls)
+        except ValueError:
+            raise ValueError("FLUX_PARAMS __fluxplot__ is not valid JSON") from None
+        if not isinstance(out["__fluxplot__"], dict):
+            raise ValueError("FLUX_PARAMS __fluxplot__ must be a JSON object keyed by colour-control key")
+    return out

fluxplot/render.py

@@ -0,0 +1,66 @@
+"""Deterministic SVG rendering (P5). Where byte-stability is won or lost.
+
+See ``NOTES_matplotlib_svg.md`` for the verified determinism knobs.
+"""
+from __future__ import annotations
+
+import io
+
+import matplotlib.pyplot as plt
+
+# rcParams that make matplotlib's SVG output deterministic + editable/addressable.
+DETERMINISTIC_RCPARAMS = {
+    # keep text as real <text> referencing fonts by name → editable, restyleable, addressable,
+    # and font-version-independent (the 'path' default outlines glyphs into nondeterministic d's).
+    "svg.fonttype": "none",
+    "savefig.bbox": None,
+    # path simplification is deterministic given a pinned threshold; pin both explicitly.
+    "path.simplify": True,
+    "path.simplify_threshold": 0.111111,
+}
+
+
+def render_svg(fig, hashsalt: str, dpi=None) -> bytes:
+    """Render ``fig`` to SVG bytes deterministically.
+
+    ``hashsalt`` fixes matplotlib's hashed ids (clip-paths, marker glyphs, ``<defs>``); without it
+    they are salted with a fresh uuid4 each run. ``metadata={'Date': None}`` drops the timestamp.
+    We never pass ``bbox_inches='tight'`` — it would crop/shift the viewBox *after* coordinate
+    anchors were captured, invalidating the data↔pixel mapping.
+
+    ``dpi`` sets the resolution of **rasterized artists only** (see ``raster.py``). SVG user
+    space is points, so vector geometry is dpi-invariant — verified in
+    ``NOTES_matplotlib_svg.md`` §6 and pinned by ``tests/test_rasterize.py``. Pass it only
+    when something is actually rasterized, so ordinary saves keep matplotlib's default.
+    """
+    rc = dict(DETERMINISTIC_RCPARAMS)
+    rc["svg.hashsalt"] = hashsalt
+    buf = io.BytesIO()
+    extra = {"dpi": dpi} if dpi else {}
+    with plt.rc_context(rc):
+        fig.savefig(buf, format="svg", metadata={"Date": None}, bbox_inches=None, **extra)
+    return buf.getvalue()
+
+
+from contextlib import contextmanager
+
+
+@contextmanager
+def final_layout(fig):
+    """Lay out with the SVG renderer, then freeze it through capture and export.
+
+    Agg and SVG have different font metrics. Public draw_without_rendering avoids
+    rasterizing data just to obtain the correct text/layout metrics.
+    """
+    from matplotlib.backends.backend_svg import FigureCanvasSVG
+    canvas, dpi, engine = fig.canvas, fig.dpi, fig.get_layout_engine()
+    try:
+        FigureCanvasSVG(fig)
+        fig.set_dpi(72)
+        fig.draw_without_rendering()
+        fig.set_layout_engine('none')
+        yield
+    finally:
+        fig.set_layout_engine(engine)
+        fig.set_dpi(dpi)
+        fig.set_canvas(canvas)

fluxplot/roles.py

@@ -0,0 +1,147 @@
+"""Role vocabulary revision 1 (spec §5, §10). A versioned core + a namespaced ``x-`` extension mechanism.
+
+Unknown roles are NOT rejected — they degrade gracefully (P4): they still get a stable id and a
+``data-role`` and are listed in the manifest; consumers that don't recognize them treat them as
+opaque addressable groups.
+"""
+from __future__ import annotations
+
+ROLE_VERSION = 1  # Local vocabulary revision; not a serialized schema version.
+
+CORE_ROLES = frozenset(
+    {
+        # containers
+        "figure",
+        "panel",
+        "plot-area",
+        "legend",
+        "colorbar",
+        "title",
+        "subtitle",
+        # scaffold / guides
+        "axis",
+        "spine",
+        "tick",
+        "tick-label",
+        "axis-title",
+        "gridline",
+        "background",
+        # data marks (geoms)
+        "series",
+        "mesh", "pane", "scalebar",
+        "image",
+        "line",
+        "point",
+        "bar",
+        "area",
+        "errorbar",
+        "box",
+        "violin",
+        "contour",
+        # composite sub-parts (box / violin / errorbar internals)
+        "whisker",
+        "cap",
+        "flier",
+        "median",
+        "mean",
+        "segment",
+        # overlays
+        "annotation",
+        "reference-line",
+        "highlight-region",
+        "significance-bracket",
+        "label",
+        "caption",
+        # untagged user-drawn artists swept into addressable "extra" content
+        "extra",
+        # legend internals
+        "legend-entry",
+        "legend-swatch",
+        "legend-label",
+        # a manifest-only container that groups sibling parts (e.g. "all x tick labels")
+        "group",
+    }
+)
+
+
+# Data-kind hints (text | line | shape | container) per core role — authored truth for
+# consumers (Flux's part editors pick the property set by kind: a tick-label edits like a
+# text object, a gridline like a line, …). Deliberate omission: "extra" is heterogeneous
+# (a swept artist can be a line, a collection or a patch), so its kind is inferred from
+# the concrete artist at sweep time (see ``descriptors.artist_kind``). Unknown / ``x-``
+# roles are likewise inferred per-artist where possible, else the hint is omitted.
+KIND_BY_ROLE = {
+    "mesh": "shape", "pane": "shape", "scalebar": "line",
+    # containers
+    "figure": "container",
+    "panel": "container",
+    "plot-area": "container",
+    "legend": "container",
+    "colorbar": "container",
+    "axis": "container",
+    "series": "container",
+    "group": "container",
+    "legend-entry": "container",
+    # text
+    "title": "text",
+    "subtitle": "text",
+    "tick-label": "text",
+    "axis-title": "text",
+    "legend-label": "text",
+    "annotation": "text",
+    "label": "text",
+    "caption": "text",
+    # line
+    "line": "line",
+    "spine": "line",
+    "tick": "line",
+    "gridline": "line",
+    "reference-line": "line",
+    "errorbar": "line",
+    "whisker": "line",
+    "cap": "line",
+    "median": "line",
+    "mean": "line",
+    "segment": "line",
+    "significance-bracket": "line",
+    # shape
+    "image": "shape",
+    "area": "shape",
+    "bar": "shape",
+    "point": "shape",
+    "box": "shape",
+    "violin": "shape",
+    "contour": "shape",
+    "flier": "shape",
+    "background": "shape",
+    "highlight-region": "shape",
+    "legend-swatch": "shape",
+    # members of colour-mapped fields: a heatmap cell, a contour band / level path, a hexagon
+    "cell": "shape",
+    "contour-level": "shape",
+    "x-hex": "shape",
+}
+
+
+def kind_for_role(role: str):
+    """The data-kind hint for a role, or ``None`` when the role carries no static kind."""
+    return KIND_BY_ROLE.get(role)
+
+
+def is_core(role: str) -> bool:
+    return role in CORE_ROLES
+
+
+def is_extension(role: str) -> bool:
+    return role.startswith("x-")
+
+
+def validate(role: str) -> str:
+    """Return the role unchanged if it is a recognized core role or a well-formed ``x-`` extension.
+
+    Unknown bare roles are allowed (graceful degradation) but normalized into the ``x-`` namespace
+    so the core vocabulary stays closed and self-describing.
+    """
+    if is_core(role) or is_extension(role):
+        return role
+    return f"x-{role}"