codefig 0.17.0__py3-none-any.whl

codefig/__init__.py

@@ -0,0 +1,210 @@
+"""codefig — Python-first code-to-diagram library for research figures."""
+
+from .constraints import (
+    Anchor,
+    Constraint,
+    ConstraintConflictError,
+    ConstraintWarning,
+    above,
+    align,
+    allow_overlap,
+    below,
+    distribute,
+    left_of,
+    nudge,
+    place,
+    right_of,
+    same_height,
+    same_width,
+    align_columns,
+    align_rows,
+    same_x,
+    same_y,
+    solve_constraints,
+)
+from .edges import Diagram, Edge, Fork, Guide, Join, Port
+from .legend import Hatch, Key, Legend
+from .policy import POLICY_TABLE, ROLES, role_of, use_policy
+from .overlaps import Overlap, OverlapError, OverlapWarning
+from .figure import Figure, Panel, LayoutError
+from .node import Col, Grid, Row, Stack
+from .primitives import (
+    Arrow,
+    Box,
+    Brace,
+    Callout,
+    CircleHighlight,
+    DotGrid,
+    Ellipsis,
+    Group,
+    LoopArrow,
+    Matrix,
+    Spacer,
+    Strip,
+    Table,
+    Text,
+    TokenStrip,
+)
+from .glyphs import Badge, BarChart, Divider, Swatch, VectorFan
+from . import icons
+from .icon import Icon, Image
+from .fills import Gradient, Split
+from .shapes import (BlockArrow, ChatBubble, Circle, Cylinder, Diamond, Document, Ellipse,
+                     Hexagon, Op, OpCircle, Parallelogram, Polygon, Shape, Trapezoid, Triangle)
+from .compose import Repeat, Series, Stacked
+from .solids import Cuboid, Pyramid, SlabStack
+from .charts import GroupedBarChart, LineChart, Scale, Sparkline, StackedBarChart
+from .regions import Region
+from .flows import WrapFlow
+from .tree import Tree
+from .styles import (CLASSIC_THEME, DEFAULT_THEME, PAPER_THEME, THEMES, Head, Theme, shade, tint,
+                     current_theme, get_theme, register_theme, set_theme, use_theme)
+from .venues import VENUES, Venue, get_venue
+from .lint import RULES, Finding, LintError, LintReport, LintWarning, lint_config
+from .steps import Step, StepCounter
+from .code import CODE_LANGS, CODE_THEMES, CodeBlock, tokenize
+from .dim import Dim
+from .timeline import Lane, LaneBand, Lanes, Marker, Task, TimeSpan, Timeline, TimelineWarning
+
+__version__ = "0.17.0"
+
+__all__ = [
+    "Figure",
+    "Panel",
+    "Box",
+    "Text",
+    "Arrow",
+    "LoopArrow",
+    "Matrix",
+    "Stack",
+    "Row",
+    "Col",
+    "Grid",
+    "Ellipsis",
+    "DotGrid",
+    "Strip",
+    "Group",
+    "Callout",
+    "CircleHighlight",
+    "Brace",
+    "Spacer",
+    "Badge",
+    "Divider",
+    "BarChart",
+    "VectorFan",
+    "Swatch",
+    "Port",
+    "Edge",
+    "Guide",
+    # v0.3.0
+    "Fork",
+    "Join",
+    "Head",
+    "Legend",
+    "Key",
+    "Hatch",
+    "TokenStrip",
+    "Table",
+    "ROLES",
+    "POLICY_TABLE",
+    "role_of",
+    "use_policy",
+    "Diagram",
+    "Theme",
+    "DEFAULT_THEME",
+    # v0.6.0
+    "PAPER_THEME",
+    "CLASSIC_THEME",
+    "THEMES",
+    "current_theme",
+    "get_theme",
+    "register_theme",
+    "set_theme",
+    "tint",
+    "shade",
+    "Cuboid",
+    "SlabStack",
+    "Pyramid",
+    "StackedBarChart",
+    "GroupedBarChart",
+    "Scale",
+    "LineChart",
+    "Sparkline",
+    "Region",
+    "WrapFlow",
+    "use_theme",
+    "VENUES",
+    "Venue",
+    "get_venue",
+    "RULES",
+    "Finding",
+    "LintError",
+    "LintReport",
+    "LintWarning",
+    "lint_config",
+    # v0.4.0
+    "icons",
+    "Icon",
+    "Image",
+    "Gradient",
+    "Split",
+    "Shape",
+    "Ellipse",
+    "Circle",
+    "OpCircle",
+    "Cylinder",
+    "Document",
+    "Trapezoid",
+    "Triangle",
+    "Polygon",
+    "Op",
+    "Parallelogram",
+    "Hexagon",
+    "Diamond",
+    "ChatBubble",
+    "BlockArrow",
+    "Stacked",
+    "Repeat",
+    "Series",
+    "Tree",
+    # v0.5.0
+    "Timeline",
+    "Task",
+    "TimeSpan",
+    "Marker",
+    "LaneBand",
+    "TimelineWarning",
+    "Lanes",
+    "Lane",
+    "CodeBlock",
+    "CODE_LANGS",
+    "CODE_THEMES",
+    "tokenize",
+    "Step",
+    "StepCounter",
+    "Dim",
+    # constraints (v0.1.8; distribute / overlaps v0.1.9)
+    "Anchor",
+    "Constraint",
+    "ConstraintConflictError",
+    "ConstraintWarning",
+    "align",
+    "same_x",
+    "same_y",
+    "same_width",
+    "align_columns",
+    "align_rows",
+    "same_height",
+    "below",
+    "above",
+    "right_of",
+    "left_of",
+    "place",
+    "nudge",
+    "solve_constraints",
+    "distribute",
+    "allow_overlap",
+    "Overlap",
+    "OverlapError",
+    "OverlapWarning",
+]

codefig/_validate.py

@@ -0,0 +1,12 @@
+"""Shared enum diagnostics."""
+from difflib import get_close_matches
+
+
+def check_enum(name, value, valid, aliases=None):
+    """Resolve aliases or raise an actionable enumeration error."""
+    value = (aliases or {}).get(value, value)
+    if value not in valid:
+        close = get_close_matches(str(value), valid, n=1, cutoff=0.3)
+        hint = f"; did you mean {close[0]!r}?" if close else ""
+        raise ValueError(f"{name}={value!r}: not one of {list(valid)!r}{hint}")
+    return value

codefig/autowrap.py

@@ -0,0 +1,277 @@
+"""v0.14.0: wrap long labels at word boundaries before a figure shrinks to fit.
+
+When a physical figure's natural width exceeds the venue slot, everything would be
+scaled down uniformly (and text may fall below the 6 pt floor).  Before that happens
+:func:`auto_wrap` breaks the widest single-line labels *that actually set the width*
+(Box / Text labels on the critical path of Rows, the widest member of a Col, edge
+labels that stick out of their Diagram, panel titles wider than their content) into
+two balanced lines, re-lays the figure out and keeps a wrap only when the figure got
+narrower.  It stops as soon as the content fits; whatever is left shrinks as before.
+
+Opt out with ``Figure(auto_wrap=False)``; a label that already contains ``"\\n"`` is
+never touched, and ``auto_wrap=False`` on any node (``Box``, ``Text`` …) or ``Edge`` pins one label.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional, Tuple
+
+from .textutil import measure_text
+
+MAX_ROUNDS = 6
+
+
+def split_two(text: str, width_of: Callable[[str], float]) -> Optional[str]:
+    """Best two-line split of ``text`` at a space outside markup (``**…**``, ``*…*``,
+    ``[…]``, ``{…}``, ``$…$``, backticks), minimising the wider line; ``None`` if the
+    text has no usable break or already has a line break."""
+    if not text or "\n" in text or " " not in text.strip():
+        return None
+    breaks: List[int] = []
+    depth = 0
+    toggles = {"$": False, "`": False}
+    bold = italic = False
+    i = 0
+    s = text
+    while i < len(s):
+        ch = s[i]
+        if ch == "\\":
+            i += 2
+            continue
+        if ch in "[{(":
+            depth += 1
+        elif ch in "]})":
+            depth = max(0, depth - 1)
+        elif ch in toggles:
+            toggles[ch] = not toggles[ch]
+        elif ch == "*":
+            if s.startswith("**", i):
+                bold = not bold
+                i += 2
+                continue
+            italic = not italic
+        elif ch == " " and depth == 0 and not any(toggles.values()) and not bold and not italic:
+            if s[:i].strip() and s[i + 1:].strip():
+                breaks.append(i)
+        i += 1
+    if not breaks:
+        return None
+    best = None
+    for b in breaks:
+        a, c = s[:b].rstrip(), s[b + 1:].lstrip()
+        w = max(width_of(a), width_of(c))
+        if best is None or w < best[0] - 1e-6:
+            best = (w, a + "\n" + c)
+    return best[1] if best else None
+
+
+def _children(n: Any) -> List[Any]:
+    try:
+        return [k for k in n.children() if not getattr(k, "_cf_guide", False)]
+    except Exception:  # pragma: no cover
+        return []
+
+
+def _critical(n: Any, out: List[Any]) -> None:
+    """Nodes whose width can set ``n``'s width: every member of a Row (or Grid), the
+    widest member(s) of anything else."""
+    from .node import Container, Grid
+
+    out.append(n)
+    kids = _children(n)
+    if not kids:
+        return
+    if isinstance(n, Grid) or (isinstance(n, Container) and getattr(n, "direction", "") == "row"):
+        for k in kids:
+            _critical(k, out)
+        return
+    ws = [(k.measure()[0], k) for k in kids]
+    m = max(w for w, _ in ws)
+    for w, k in ws:
+        if w >= m - 1.0:
+            _critical(k, out)
+
+
+class _Cand:
+    __slots__ = ("kind", "obj", "attr", "old", "new", "gain", "name")
+
+    def __init__(self, kind: str, obj: Any, attr: str, old: str, new: str, gain: float, name: str):
+        self.kind, self.obj, self.attr = kind, obj, attr
+        self.old, self.new, self.gain, self.name = old, new, gain, name
+
+    def apply(self) -> None:
+        setattr(self.obj, self.attr, self.new)
+
+    def revert(self) -> None:
+        setattr(self.obj, self.attr, self.old)
+
+
+def _label_node_cands(n: Any, out: List[_Cand], done: set) -> None:
+    from .constraints import node_name
+    from .primitives import Box, Text
+
+    if id(n) in done or getattr(n, "auto_wrap", True) is False:
+        return
+    if isinstance(n, Box):
+        if n.fixed_w is not None or getattr(n, "label_rotate", 0) or not isinstance(n.text, str):
+            return
+        fs, mono, weight = n._fs(), n.mono, n.weight
+    elif isinstance(n, Text):
+        if n.rotate or not isinstance(n.text, str):
+            return
+        fs, mono, weight = n._fs(), n.mono, n.weight
+    else:
+        return
+    if n.text.count(" ") > 12:  # paragraphs are the author's business
+        return
+
+    def wof(t: str) -> float:
+        return measure_text(t, fs, mono=mono, weight=weight)[0]
+
+    new = split_two(n.text, wof)
+    if new is None:
+        return
+    gain = wof(n.text) - max(wof(x) for x in new.split("\n"))
+    if gain > 1.0:
+        out.append(_Cand("label", n, "text", n.text, new, gain, node_name(n)))
+
+
+def _edge_cands(d: Any, out: List[_Cand], done: set) -> None:
+    from .overlaps import edge_name
+
+    try:
+        l, _t, r, _b = d._margins()
+    except Exception:  # pragma: no cover
+        return
+    if l + r < 2.0:
+        return
+    th = d.theme
+    for e in getattr(d, "edges", []) or []:
+        lab = getattr(e, "label", None)
+        if not isinstance(lab, str) or id(e) in done or getattr(e, "auto_wrap", True) is False:
+            continue
+        try:
+            fs = e._label_fs(th)
+        except Exception:  # pragma: no cover
+            fs = th.font_size * 0.9
+
+        def wof(t: str, fs: float = fs) -> float:
+            return measure_text(t, fs)[0]
+
+        new = split_two(lab, wof)
+        if new is None:
+            continue
+        gain = min(l + r, wof(lab) - max(wof(x) for x in new.split("\n")))
+        if gain > 1.0:
+            out.append(_Cand("edge", e, "label", lab, new, gain, edge_name(e)))
+
+
+def _candidates(fig: Any, done: set) -> List[_Cand]:
+    from .edges import Diagram
+
+    out: List[_Cand] = []
+    for k in fig._order:
+        p = fig._panels[k]
+        if p.content is None:
+            continue
+        wp = getattr(p, "_wparts", None) or {}
+        if p.title and "\n" not in str(p.title) and wp.get("caption", 0) > wp.get("content", 0) + 1.0 \
+                and id(p) not in done and not p._no_caption():
+            fs = fig.theme.panel_title_size
+            pre = f"({p.letter}) " if p.letters else ""
+
+            def wof(t: str, fs: float = fs) -> float:
+                return measure_text(t, fs, weight="bold")[0]
+
+            new = split_two(pre + str(p.title), wof)
+            if new is not None and (not pre or new.startswith(pre.rstrip() + " ") or new.startswith(pre)):
+                new_t = new[len(pre):] if pre and new.startswith(pre) else None
+                if new_t:
+                    gain = min(wp["caption"] - wp["content"],
+                               wof(pre + str(p.title)) - max(wof(x) for x in new.split("\n")))
+                    if gain > 1.0:
+                        out.append(_Cand("title", p, "title", p.title, new_t, gain, f"panel ({k}) title"))
+        crit: List[Any] = []
+        _critical(p.content, crit)
+        for n in crit:
+            if isinstance(n, Diagram):
+                _edge_cands(n, out, done)
+            else:
+                _label_node_cands(n, out, done)
+    out.sort(key=lambda c: -c.gain)
+    return out
+
+
+def auto_wrap(fig: Any, relayout: Callable[[], None]) -> List[Tuple[str, str, str]]:
+    """Greedy wrap pass (see module docstring). Returns ``[(name, old, new)]`` kept."""
+    from .constraints import invalidate_tree
+
+    kept: List[Tuple[str, str, str]] = []
+    done: set = set()
+    tw = fig.target_width
+    for _round in range(MAX_ROUNDS):
+        nat = float(getattr(fig, "natural_width", 0.0) or 0.0)
+        if tw is None or nat <= tw + 0.05:
+            break
+        over = nat - tw
+        with fig._ctx():
+            cands = _candidates(fig, done)
+        if not cands:
+            break
+        pick: List[_Cand] = []
+        acc = 0.0
+        for c in cands:
+            pick.append(c)
+            acc += c.gain
+            if acc >= over * 1.1:
+                break
+        for c in pick:
+            c.apply()
+            done.add(id(c.obj))
+        for p in fig._panels.values():
+            if p.content is not None:
+                invalidate_tree(p.content)
+            p.__dict__.pop("_sub_cache", None)
+        relayout()
+        nat2 = float(getattr(fig, "natural_width", 0.0) or 0.0)
+        if nat2 < nat - 0.5:
+            kept.extend((c.name, c.old, c.new) for c in pick)
+            continue
+        for c in pick:  # no gain (another member sets the width): undo
+            c.revert()
+        for p in fig._panels.values():
+            if p.content is not None:
+                invalidate_tree(p.content)
+        relayout()
+    return kept
+
+
+def width_setters(fig: Any, limit: int = 4) -> List[str]:
+    """Labels on the critical width path that could still be shortened or wrapped
+    (for the CF-EXP-001 hint), widest first."""
+    from .constraints import node_name
+    from .primitives import Box, Text
+
+    rows: List[Tuple[float, str]] = []
+    try:
+        with fig._ctx():
+            for k in fig._order:
+                p = fig._panels[k]
+                if p.content is None:
+                    continue
+                crit: List[Any] = []
+                _critical(p.content, crit)
+                seen = set()
+                for n in crit:
+                    if id(n) in seen or not isinstance(n, (Box, Text)) or not isinstance(n.text, str):
+                        continue
+                    seen.add(id(n))
+                    w = n.geom.w if getattr(n, "geom", None) is not None else n.measure()[0]
+                    if w < 18 or getattr(n, "fixed_w", None) is not None or len(n.text.strip()) < 4:
+                        continue  # a fixed size / tiny label is not what sets the width
+                    lab = n.text.replace("\n", "⏎")
+                    rows.append((w, f"{node_name(n)} '{lab[:30]}' {w:.0f} pt"))
+    except Exception:  # pragma: no cover - diagnostics must never break lint
+        return []
+    rows.sort(key=lambda r: -r[0])
+    return [r[1] for r in rows[:limit]]