quantized-lab 0.8.1__tar.gz → 0.9.0__tar.gz

{quantized_lab-0.8.1 → quantized_lab-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantized-lab
-Version: 0.8.1
+Version: 0.9.0
 Summary: Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines.
 Project-URL: Homepage, https://github.com/pquarterman17/quantized
 Project-URL: Documentation, https://github.com/pquarterman17/quantized/wiki

{quantized_lab-0.8.1 → quantized_lab-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantized-lab"
-version = "0.8.1"
+version = "0.9.0"
 description = "Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines."
 readme = "README.md"
 requires-python = ">=3.11"

{quantized_lab-0.8.1 → quantized_lab-0.9.0}/src/quantized/__init__.py

@@ -7,5 +7,5 @@ Layered, enforced architecture (see CLAUDE.md):
 
 from __future__ import annotations
 
-__version__ = "0.8.1"
+__version__ = "0.9.0"
 __all__ = ["__version__"]

quantized_lab-0.9.0/src/quantized/calc/figure_labels.py

@@ -0,0 +1,127 @@
+"""Mathtext label guard for figure export (GOTO #5 rich-text labels).
+
+Labels flow from the UI as plain text with optional ``$...$`` mathtext
+regions (the frontend's ``lib/richtext`` micro-syntax is a strict subset of
+matplotlib mathtext, so passthrough is the rendering mechanism). matplotlib
+parses math regions at DRAW time, which means an invalid label would raise
+inside ``fig.savefig`` and turn an export into a 500. This module is the
+shared chokepoint every ``calc.figure*`` renderer routes its user-supplied
+strings through: it pre-validates with matplotlib's own mathtext parser and,
+on failure, escapes the dollar signs so the label renders as literal text
+(matplotlib renders ``\\$`` as a plain ``$``) -- an invalid label must NEVER
+error an export.
+
+Screen/export WYSIWYG (bug-hunt fix): the frontend's parser
+(``frontend/src/lib/richtext.ts``) only accepts a STRICT SUBSET of
+mathtext -- Greek letters, ``\\AA \\circ \\times \\cdot \\pm \\prime \\,
+\\mathrm \\mathit``, and literal Unicode -- and rejects everything else
+(e.g. ``\\frac``, ``\\sqrt``, ``\\sum``) as invalid markup, rendering it
+literally on screen. Raw matplotlib accepts a much larger command set, so
+without this gate a label like ``$\\frac{1}{2}$`` would render literal text
+("Invalid markup") on screen but an actual fraction in the PDF/SVG export --
+a WYSIWYG violation. `_uses_only_supported_commands` enumerates the SAME
+command set the frontend parser accepts and rejects (falls back to literal)
+any ``$...$`` region using a command outside it, BEFORE the matplotlib trial
+parse below ever runs. Keep `SUPPORTED_MATHTEXT_COMMANDS` in sync with
+richtext.ts's ``GREEK``/``SYMBOLS`` tables + ``mathrm``/``mathit`` handling.
+
+Pure layer: string in -> string out. matplotlib is imported lazily (same
+convention as the figure modules -- the heavy import is paid only on export).
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Any
+
+__all__ = ["safe_mathtext_label", "SUPPORTED_MATHTEXT_COMMANDS"]
+
+# A "$" not preceded by a backslash -- matplotlib's own math-region rule
+# (matplotlib.cbook.is_math_text counts these; an odd count means the string
+# is rendered as literal text, dollars visible, no mathtext at all).
+_UNESCAPED_DOLLAR = re.compile(r"(?<!\\)\$")
+
+# A backslash command name (`\foo`) inside a math region. `\,` (thin space)
+# is handled separately by richtext.ts before its name-based dispatch and
+# has no letters, so it never matches this and is implicitly always allowed.
+_COMMAND = re.compile(r"\\([a-zA-Z]+)")
+
+# Mirrors frontend/src/lib/richtext.ts's `GREEK` table: lowercase (+ \var*
+# variants) render italic, uppercase upright -- irrelevant here, we only
+# need the NAME set, not the styling.
+_GREEK_COMMANDS = frozenset(
+    {
+        "alpha", "beta", "gamma", "delta", "epsilon", "varepsilon", "zeta",
+        "eta", "theta", "vartheta", "iota", "kappa", "lambda", "mu", "nu",
+        "xi", "pi", "rho", "sigma", "varsigma", "tau", "upsilon", "phi",
+        "varphi", "chi", "psi", "omega",
+        "Gamma", "Delta", "Theta", "Lambda", "Xi", "Pi", "Sigma", "Upsilon",
+        "Phi", "Psi", "Omega",
+    }
+)
+# Mirrors richtext.ts's `SYMBOLS` table (non-Greek symbol commands).
+_SYMBOL_COMMANDS = frozenset({"AA", "circ", "times", "cdot", "pm", "prime"})
+# Mirrors richtext.ts's `\mathrm{...}` / `\mathit{...}` style-group handling.
+_STYLE_COMMANDS = frozenset({"mathrm", "mathit"})
+
+SUPPORTED_MATHTEXT_COMMANDS = _GREEK_COMMANDS | _SYMBOL_COMMANDS | _STYLE_COMMANDS
+
+
+def _uses_only_supported_commands(label: str) -> bool:
+    """True when every backslash command inside every ``$...$`` region of
+    `label` is in `SUPPORTED_MATHTEXT_COMMANDS`. Text OUTSIDE `$...$` is
+    never scanned -- a stray backslash there is the caller's problem, not
+    this gate's (and richtext.ts itself only ever considers commands inside
+    math regions). Assumes a balanced (even) unescaped-`$` count, as
+    guaranteed by `safe_mathtext_label` calling this only after that check.
+    """
+    segments = _UNESCAPED_DOLLAR.split(label)
+    for i, segment in enumerate(segments):
+        if i % 2 == 0:
+            continue  # literal text outside $...$
+        for m in _COMMAND.finditer(segment):
+            if m.group(1) not in SUPPORTED_MATHTEXT_COMMANDS:
+                return False
+    return True
+
+
+@lru_cache(maxsize=1)
+def _parser() -> Any:
+    """The mathtext trial parser (cached -- construction is not free)."""
+    from matplotlib.mathtext import MathTextParser
+
+    return MathTextParser("agg")
+
+
+def safe_mathtext_label(label: str) -> str:
+    """Return ``label`` unchanged when it renders safely; else de-math it.
+
+    - No ``$`` at all: fast path, returned as-is (byte-identical to today).
+    - Odd count of unescaped ``$``: matplotlib already treats the whole
+      string as literal text -- returned as-is.
+    - Balanced ``$...$`` regions using only commands the frontend's
+      richtext.ts subset also accepts (`SUPPORTED_MATHTEXT_COMMANDS`), AND
+      that trial-parse successfully with matplotlib's mathtext parser ->
+      unchanged (mathtext renders it at export, matching the screen).
+      Otherwise (an out-of-subset command, e.g. ``\\frac``/``\\sqrt``/
+      ``\\sum``, OR a parse failure even within the subset, e.g. unbalanced
+      braces) -> every unescaped ``$`` is escaped to ``\\$`` so matplotlib
+      renders the literal string (dollars visible) instead of raising at
+      savefig time OR silently rendering richer math than the screen ever
+      showed.
+    """
+    if not label or "$" not in label:
+        return label
+    n_math = len(_UNESCAPED_DOLLAR.findall(label))
+    if n_math == 0 or n_math % 2 == 1:
+        # Zero unescaped $ (all \$-escaped) or an odd count: matplotlib
+        # already renders the whole string as literal text -- leave it be.
+        return label
+    if not _uses_only_supported_commands(label):
+        return _UNESCAPED_DOLLAR.sub(r"\\$", label)
+    try:
+        _parser().parse(label)
+    except Exception:  # ANY parse failure means "render literal", never raise
+        return _UNESCAPED_DOLLAR.sub(r"\\$", label)
+    return label

{quantized_lab-0.8.1 → quantized_lab-0.9.0}/src/quantized/calc/figure_overrides.py

@@ -17,6 +17,7 @@ from collections.abc import Mapping
 from typing import Any
 
 from quantized.calc.figure_labels import safe_mathtext_label
+from quantized.calc.figure_shapes import _apply_shapes, _validate_shapes
 
 __all__ = ["_apply_overrides", "_validate_overrides"]
 
@@ -63,6 +64,7 @@ def _validate_overrides(ov: Mapping[str, Any]) -> None:
             if prev_hi is not None and lo < prev_hi:
                 raise ValueError("x_breaks entries must be sorted and non-overlapping")
             prev_hi = hi
+    _validate_shapes(ov.get("shapes"))
 
 
 def _apply_overrides(
@@ -142,6 +144,23 @@ def _apply_overrides(
             # pixel-identical placement between screen and export.
             ann_kw["xycoords"] = "figure fraction"
             y = 1.0 - y
+        frame = ann.get("frame")
+        if frame:
+            # MAIN #27 "text box": a bbox behind the annotation text. `pad`
+            # (screen CSS px around the measured text) has no exact
+            # matplotlib equivalent (`boxstyle="square,pad=N"`'s pad is in
+            # font-size units, not px) -- divided by a fixed factor so the
+            # box reads as padded rather than pixel-identical, the same
+            # "Origin-parity-in-spirit, not pixel-identical" caveat the
+            # page-anchor y-flip above documents. fc/ec default to a plain
+            # white-card-on-black-border look (independent of the screen's
+            # own dark-canvas ink default -- publication export is white-bg).
+            ann_kw["bbox"] = dict(
+                boxstyle=f"square,pad={float(frame.get('pad', 4)) / 4.0}",
+                fc=frame.get("fill") or "white",
+                ec=frame.get("stroke") or "black",
+                alpha=frame.get("opacity", 1.0),
+            )
         ax.annotate(
             safe_mathtext_label(str(ann.get("text", ""))),
             xy=(x, y),
@@ -157,3 +176,8 @@ def _apply_overrides(
             top=None if margins.get("top") is None else 1.0 - float(margins["top"]),
             bottom=margins.get("bottom"),
         )
+
+    # MAIN #27: shapes paint LAST -- on top of everything else this sweep
+    # drew (annotations included), matching export intent: shapes mark up
+    # the finished figure.
+    _apply_shapes(fig, ax, ov.get("shapes"))

quantized_lab-0.9.0/src/quantized/calc/figure_shapes.py

@@ -0,0 +1,153 @@
+"""Drawn-shape overrides (MAIN #27) -- export parity for the screen's
+``lib/uplotShapes.ts``. Split out of ``figure_overrides.py`` purely to stay
+under each module's line-count discipline (same reasoning as
+``figure_labels.py`` / ``figure_break.py``) -- the behavioural contract is
+still ``figure_overrides``'s; ``_apply_overrides`` calls ``_apply_shapes``
+as its last step, AFTER the annotation sweep, so shapes paint on TOP of
+everything else the override sweep drew (annotations included) -- matching
+export intent: shapes mark up the finished figure. Pure layer: mapping in ->
+mutates the passed matplotlib Figure/Axes, no return value.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal
+
+from matplotlib.lines import Line2D
+from matplotlib.patches import Ellipse, FancyArrowPatch, Rectangle
+
+__all__ = ["_apply_shapes", "_validate_shapes"]
+
+_SHAPE_KINDS = frozenset({"arrow", "line", "rect", "ellipse"})
+
+# Default whole-shape opacity (fill AND stroke, ONE knob) mirroring the
+# screen's `defaultShapeOpacity` (lib/uplotShapes.ts): 1 for line/arrow, 0.35
+# for rect/ellipse (a freshly drawn box reads as visibly translucent OVER
+# the data it marks).
+_DEFAULT_OPACITY = {"arrow": 1.0, "line": 1.0, "rect": 0.35, "ellipse": 0.35}
+_DEFAULT_WIDTH = 1.5
+_DEFAULT_STROKE = "black"
+
+
+def _validate_shapes(shapes: Sequence[Mapping[str, Any]] | None) -> None:
+    """Raise ``ValueError`` on a malformed shape (bad kind, non-finite
+    coords); a shape with an unknown/missing key inside is otherwise
+    tolerant (unknown keys ignored), mirroring ``_validate_overrides``."""
+    if not shapes:
+        return
+    for sh in shapes:
+        kind = sh.get("kind")
+        if kind not in _SHAPE_KINDS:
+            raise ValueError(f"shape kind must be one of {sorted(_SHAPE_KINDS)}")
+        for key in ("x1", "y1", "x2", "y2"):
+            v = sh.get(key)
+            if not isinstance(v, (int, float)) or isinstance(v, bool):
+                raise ValueError(f"shape {key} must be a number")
+
+
+def _shape_endpoints(
+    sh: Mapping[str, Any], ax: Any, fig: Any
+) -> tuple[tuple[float, float], tuple[float, float], Any]:
+    """(p1, p2, transform) for one shape, resolving its anchor -- DATA (the
+    default: ``ax.transData``, applied implicitly by omitting ``transform``
+    and adding via ``ax.add_patch``/``ax.add_line``) or PAGE (explicit
+    ``fig.transFigure``, Y FLIPPED -- canvas y grows downward, matplotlib
+    figure fraction grows upward -- the SAME convention
+    ``_apply_overrides``'s page-anchored annotation uses)."""
+    x1, y1 = float(sh["x1"]), float(sh["y1"])
+    x2, y2 = float(sh["x2"]), float(sh["y2"])
+    if sh.get("anchor") == "page":
+        return (x1, 1.0 - y1), (x2, 1.0 - y2), fig.transFigure
+    return (x1, y1), (x2, y2), ax.transData
+
+
+def _apply_shapes(fig: Any, ax: Any, shapes: Sequence[Mapping[str, Any]] | None) -> None:
+    """Draw MAIN #27 shapes (arrow/line/rect/ellipse). Arrows use
+    ``FancyArrowPatch``; plain lines ``Line2D``; rect/ellipse the matching
+    matplotlib patch with ``alpha`` -- all added via ``ax.add_patch``/
+    ``ax.add_line`` (data-anchored, the default -- no explicit ``transform``
+    needed there; matplotlib resolves an artist added this way against
+    ``ax.transData``) or with an EXPLICIT ``transform=fig.transFigure`` for
+    a page-anchored shape (``ax.add_patch``/``add_line`` never override an
+    already-set transform -- verified empirically, see the porting notes).
+    """
+    if not shapes:
+        return
+    for sh in shapes:
+        kind = sh.get("kind")
+        if kind not in _SHAPE_KINDS:
+            continue
+        p1, p2, transform = _shape_endpoints(sh, ax, fig)
+        stroke = sh.get("stroke") or _DEFAULT_STROKE
+        # `is not None` (not `or`): an explicit `width: 0` is falsy in Python
+        # and `... or _DEFAULT_WIDTH` was silently replacing it with the
+        # default (1.5) -- unlike the correct `opacity` idiom two lines below.
+        width = float(sh["width"]) if sh.get("width") is not None else _DEFAULT_WIDTH
+        dash: Literal["-", "--"] = "--" if sh.get("dash") else "-"
+        opacity = sh.get("opacity")
+        opacity = float(opacity) if opacity is not None else _DEFAULT_OPACITY[kind]
+        fill = sh.get("fill") or stroke
+        patch: Any
+
+        if kind == "arrow":
+            patch = FancyArrowPatch(
+                p1,
+                p2,
+                transform=transform,
+                arrowstyle="-|>",
+                mutation_scale=12 + width * 4,
+                # matplotlib's FancyArrowPatch default shrinkA/shrinkB=2pt
+                # insets BOTH ends from the given points (meant for
+                # "annotate near, not touching, an object") -- WYSIWYG with
+                # the screen's canvas draw (no shrink at all) needs the
+                # endpoints to land EXACTLY where dragged.
+                shrinkA=0,
+                shrinkB=0,
+                color=stroke,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_patch(patch)
+        elif kind == "line":
+            line = Line2D(
+                [p1[0], p2[0]],
+                [p1[1], p2[1]],
+                transform=transform,
+                color=stroke,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_line(line)
+        elif kind == "rect":
+            x0, x1v = min(p1[0], p2[0]), max(p1[0], p2[0])
+            y0, y1v = min(p1[1], p2[1]), max(p1[1], p2[1])
+            patch = Rectangle(
+                (x0, y0),
+                x1v - x0,
+                y1v - y0,
+                transform=transform,
+                edgecolor=stroke,
+                facecolor=fill,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_patch(patch)
+        else:  # ellipse
+            cx, cy = (p1[0] + p2[0]) / 2, (p1[1] + p2[1]) / 2
+            w, h = abs(p2[0] - p1[0]), abs(p2[1] - p1[1])
+            patch = Ellipse(
+                (cx, cy),
+                w,
+                h,
+                transform=transform,
+                edgecolor=stroke,
+                facecolor=fill,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_patch(patch)