codefig 0.17.0__py3-none-any.whl

codefig/export.py

@@ -0,0 +1,204 @@
+"""Export: SVG (always), PNG and PDF via cairosvg, plus alt text and save-time lint.
+
+* ``.svg`` — text stays text (``font-family`` lists the resolved installed family
+  first, then the theme's stack).
+* ``.png`` — px figures: ``scale=`` (2 → 2×); physical (pt) figures: ``dpi=``
+  (default 300 → ``width_pt × 300 / 72`` pixels).
+* ``.pdf`` — vector, fonts embedded as TrueType subsets by cairo (no Type 3 for
+  TrueType/OpenType sources). Note: ICML/MLSys ask for Type 1; embedded TrueType is
+  accepted in practice and by NeurIPS/ICLR/ACM/USENIX (``docs/concepts/themes-venues.md``).
+"""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+if TYPE_CHECKING:
+    from .figure import Figure
+
+
+def _cairosvg():
+    try:
+        import cairosvg
+    except ImportError as e:  # pragma: no cover - dependency is declared
+        raise ImportError("PNG/PDF export requires cairosvg: pip install cairosvg") from e
+    return cairosvg
+
+
+def _lint_mode(fig: "Figure", lint: Optional[str]) -> Optional[str]:
+    if lint in (None, False, "off", "none"):
+        return None
+    if lint == "auto":
+        return "error" if getattr(fig, "physical", False) else None
+    if lint not in ("error", "warn"):
+        raise ValueError("lint must be 'error', 'warn', 'auto' or None")
+    return lint
+
+
+def save_figure(
+    fig: "Figure",
+    path: Union[str, Path],
+    *,
+    scale: Optional[float] = None,
+    dpi: Optional[float] = None,
+    lint: Optional[str] = "auto",
+    alt: Optional[str] = None,
+    venue: Optional[str] = None,
+    stacklevel: int = 3,
+) -> Path:
+    """Write ``.svg`` / ``.png`` / ``.pdf`` (see module docstring)."""
+    path = Path(path)
+    suffix = path.suffix.lower()
+    if suffix not in (".svg", ".png", ".pdf"):
+        raise ValueError(f"Unsupported export format: {suffix!r} (use .svg, .png or .pdf)")
+    if scale is not None and scale <= 0:
+        raise ValueError(f"scale must be > 0, got {scale!r}")
+    if dpi is not None and dpi <= 0:
+        raise ValueError(f"dpi must be > 0, got {dpi!r}")
+    mode = _lint_mode(fig, lint)
+    if mode is not None:
+        from .lint import LintWarning
+
+        rep = fig.lint(venue=venue, alt=alt)
+        if mode == "error" and any(f.severity == "error" for f in rep.findings):
+            _raise_with_preview(fig, rep, path, alt)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    for ext in (".png", ".svg"):  # a successful save clears a stale lint preview
+        stale = path.with_name(path.stem + ".lint_preview" + ext)
+        if stale.exists():
+            stale.unlink()
+    if mode == "warn":
+        prev = None
+        if any(f.severity == "error" for f in rep.findings):
+            prev = write_lint_preview(fig, rep, path, alt)  # iteration mode: figure + preview
+        for f in rep.findings:
+            if f.severity in ("error", "warn"):
+                warnings.warn(f"{f.rule_id} {f.severity}: {f.message}"
+                              + (f" (fix: {f.fix})" if f.fix else "")
+                              + (f" [outlined in {prev}]" if prev is not None and f.severity == "error"
+                                 else ""), LintWarning, stacklevel=stacklevel)
+    svg = fig.to_svg(alt=alt)
+    if alt:
+        path.with_suffix(".alt.txt").write_text(alt.strip() + "\n", encoding="utf-8")
+    if suffix == ".svg":
+        path.write_text(svg, encoding="utf-8")
+        return path
+    cairosvg = _cairosvg()
+    data = svg.encode("utf-8")
+    if suffix == ".png":
+        if getattr(fig, "physical", False):
+            if scale is not None and dpi is None:
+                dpi = 72.0 * scale
+            px_w = fig.width * float(dpi or 300.0) / 72.0
+            cairosvg.svg2png(bytestring=data, write_to=str(path), output_width=round(px_w))
+        else:
+            cairosvg.svg2png(bytestring=data, write_to=str(path), scale=float(scale or 1.0))
+        return path
+    cairosvg.svg2pdf(bytestring=data, write_to=str(path))
+    if mode is not None:
+        _check_pdf_fonts(path, mode)
+    return path
+
+
+def lint_preview_svg(fig: "Figure", report: Any, *, alt: Optional[str] = None,
+                     warnings_too: bool = True) -> str:
+    """v0.12.0 (A7): the figure's SVG with every lint finding that has a location
+    outlined — errors in red, warnings in orange — and its rule id beside the box."""
+    svg = fig.to_svg(alt=alt)
+    marks = []
+    for f in report.findings:
+        if f.severity == "error":
+            col = "#e41a1c"
+        elif f.severity == "warn" and warnings_too:
+            col = "#ff7f00"
+        else:
+            continue
+        for j, b in enumerate(f.boxes):
+            x0, y0, x1, y1 = b
+            pad = 0.8
+            marks.append(f'<rect x="{x0 - pad:.2f}" y="{y0 - pad:.2f}" width="{x1 - x0 + 2 * pad:.2f}" '
+                         f'height="{y1 - y0 + 2 * pad:.2f}" fill="none" stroke="{col}" '
+                         f'stroke-width="0.6" />')
+            if j == 0:  # the rule id once per finding, at its first location
+                marks.append(f'<text x="{x0:.2f}" y="{y0 - 1.4:.2f}" font-size="3.2" '
+                             f'fill="{col}" font-family="Liberation Sans, Arial, sans-serif">'
+                             f'{f.rule_id}</text>')
+    if not marks:
+        return svg
+    i = svg.rfind("</svg>")
+    return svg[:i] + '<g id="codefig-lint-preview">' + "".join(marks) + "</g>\n" + svg[i:]
+
+
+def write_lint_preview(fig: "Figure", rep: Any, path: Path, alt: Optional[str] = None) -> Optional[Path]:
+    """Write ``<stem>.lint_preview.png`` (``.svg`` when PNG export is unavailable) with
+    every located finding outlined; returns its path (``None`` if it could not be written)."""
+    prev = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        svg = lint_preview_svg(fig, rep, alt=alt)
+        try:
+            cairosvg = _cairosvg()
+            prev = path.with_name(path.stem + ".lint_preview.png")
+            px_w = fig.width * 400.0 / 72.0 if getattr(fig, "physical", False) else fig.width * 2
+            cairosvg.svg2png(bytestring=svg.encode("utf-8"), write_to=str(prev),
+                             output_width=round(px_w))
+        except Exception:
+            prev = path.with_name(path.stem + ".lint_preview.svg")
+            prev.write_text(svg, encoding="utf-8")
+    except Exception:  # pragma: no cover - the preview must never hide the real error
+        prev = None
+    return prev
+
+
+def _raise_with_preview(fig: "Figure", rep: Any, path: Path, alt: Optional[str]) -> None:
+    """Write the lint preview, then raise LintError naming it (summary on the last line)."""
+    from .lint import LintError
+
+    prev = write_lint_preview(fig, rep, path, alt)
+    raise LintError(rep, preview=prev, target=path)
+
+
+def _check_pdf_fonts(path: Path, mode: str) -> None:
+    """CF-EXP-002 on the written file: every font embedded, none Type 3."""
+    from .lint import LintError, LintWarning
+
+    bad = [f for f in pdf_fonts(path) if not f["embedded"] or "Type 3" in f["type"]]
+    if not bad:
+        return
+    msg = "CF-EXP-002 error: " + ", ".join(f"{f['name']} ({f['type']}, embedded={f['embedded']})"
+                                           for f in bad)
+    if mode == "error":
+        raise LintError(msg)
+    warnings.warn(msg, LintWarning, stacklevel=3)
+
+
+def pdf_fonts(path: Union[str, Path]) -> list:
+    """Fonts of a PDF as ``[{"name", "type", "embedded"}]`` (``pdffonts`` if present,
+    else a byte scan of the font dictionaries)."""
+    import re
+    import shutil
+    import subprocess
+
+    path = Path(path)
+    if shutil.which("pdffonts"):
+        out = subprocess.run(["pdffonts", str(path)], capture_output=True, text=True).stdout
+        rows = []
+        for line in out.splitlines()[2:]:
+            parts = line.split()
+            if len(parts) < 7:
+                continue
+            # name type [subtype words] encoding emb sub uni object ID
+            name = parts[0]
+            emb = parts[-5]
+            ftype = " ".join(parts[1:-6]) if len(parts) > 7 else parts[1]
+            rows.append({"name": name, "type": ftype, "embedded": emb == "yes"})
+        return rows
+    raw = path.read_bytes()
+    rows = []
+    for m in re.finditer(rb"/Subtype\s*/(Type3|Type1|TrueType|Type0|CIDFontType2|CIDFontType0)"
+                         rb"[^>]*?/BaseFont\s*/([^\s/>]+)", raw):
+        rows.append({"name": m.group(2).decode("latin-1"), "type": m.group(1).decode(),
+                     "embedded": b"/FontFile" in raw})
+    return rows