figkit 0.1.0__py3-none-any.whl

figkit/export.py

@@ -0,0 +1,301 @@
+"""Exporting figures to SVG, PNG, PDF and HTML.
+
+SVG is written natively.  PNG/PDF go through cairosvg when it is installed,
+and otherwise fall back to whichever converter is on ``PATH``
+(``rsvg-convert``, ``resvg``, ``inkscape``, ``chromium``).
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+import shutil
+import subprocess
+import tempfile
+
+__all__ = ["save_figure", "to_png", "to_pdf", "to_svg", "to_html",
+           "available_backends", "ExportError"]
+
+
+class ExportError(RuntimeError):
+    """Raised when a figure cannot be converted to the requested format."""
+
+
+_RASTER_FORMATS = {"png", "jpg", "jpeg", "webp"}
+_VECTOR_FORMATS = {"svg", "pdf", "ps", "eps"}
+
+
+def available_backends() -> dict:
+    """Which conversion backends this machine can use."""
+    out = {"cairosvg": False, "rsvg-convert": False, "resvg": False,
+           "inkscape": False, "chromium": False}
+    try:
+        import cairosvg  # noqa: F401  (import is the availability check)
+        out["cairosvg"] = True
+    except Exception:
+        pass
+    for name in ("rsvg-convert", "resvg", "inkscape"):
+        out[name] = bool(shutil.which(name))
+    out["chromium"] = bool(shutil.which("chromium") or shutil.which("chrome")
+                           or shutil.which("google-chrome")
+                           or shutil.which("chromium-browser"))
+    return out
+
+
+def _ext(path) -> str:
+    return os.path.splitext(str(path))[1].lstrip(".").lower()
+
+
+def save_figure(fig, path, *, scale: float = None, dpi: float = None,
+                format: str = None, **kw) -> str:
+    """Save ``fig`` to ``path``; the format comes from the extension."""
+    path = os.fspath(path)
+    fmt = (format or _ext(path) or "svg").lower()
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+
+    if fmt == "svg":
+        svg = fig.to_svg(**kw)
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(svg)
+        return os.path.abspath(path)
+    if fmt in ("html", "htm"):
+        html_kw = {k: v for k, v in kw.items()
+                   if k in ("title", "background", "text_as_paths",
+                            "embed_fonts", "pretty")}
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(fig.to_html(**html_kw))
+        return os.path.abspath(path)
+    if fmt in _RASTER_FORMATS:
+        data = to_png(fig, None, scale=scale if scale is not None else 2.0,
+                      dpi=dpi, fmt=fmt, **kw)
+        with open(path, "wb") as fh:
+            fh.write(data)
+        return os.path.abspath(path)
+    if fmt in _VECTOR_FORMATS:
+        data = to_pdf(fig, None, fmt=fmt, **kw)
+        with open(path, "wb") as fh:
+            fh.write(data)
+        return os.path.abspath(path)
+    raise ExportError(
+        f"unknown output format {fmt!r}; use svg, png, pdf or html")
+
+
+def to_svg(fig, path=None, **kw):
+    svg = fig.to_svg(**kw)
+    if path is None:
+        return svg
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(svg)
+    return os.path.abspath(path)
+
+
+def to_html(fig, path=None, **kw):
+    html = fig.to_html(**kw)
+    if path is None:
+        return html
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(html)
+    return os.path.abspath(path)
+
+
+def _warn_if_text_not_outlined(fig, svg: str, svg_kw: dict) -> None:
+    """Raster/PDF export outlines text so the output cannot depend on the
+    renderer's fonts. If no outline font could be found we fall back to real
+    ``<text>``, which quietly reintroduces that dependency — so say so."""
+    if not svg_kw.get("text_as_paths") or "<text" not in svg:
+        return
+    warnings.warn(
+        "figkit: no outline font was available, so text was exported as "
+        "<text> rather than paths. The rendered output will use whatever font "
+        "the converter picks, which may not match the measured layout. "
+        "Install the font you asked for, or register one with "
+        "figkit.register_font().", stacklevel=3)
+
+
+def _split_kw(kw: dict) -> tuple:
+    """Separate SVG-rendering options from converter options."""
+    svg_keys = ("pretty", "text_as_paths", "embed_fonts", "standalone")
+    svg_kw = {k: v for k, v in kw.items() if k in svg_keys}
+    rest = {k: v for k, v in kw.items() if k not in svg_keys}
+    return svg_kw, rest
+
+
+def to_png(fig, path=None, *, scale: float = 2.0, dpi: float = None,
+           background=None, fmt: str = "png", **kw):
+    """Rasterise a figure. Returns bytes when ``path`` is ``None``."""
+    svg_kw, _ = _split_kw(kw)
+    # Outlining text removes any dependency on the converter's font stack.
+    svg_kw.setdefault("text_as_paths", True)
+    svg = fig.to_svg(**svg_kw)
+    _warn_if_text_not_outlined(fig, svg, svg_kw)
+    vb = fig.viewbox()
+    scale = float(scale if scale is not None else 2.0)
+    if dpi:
+        scale = float(dpi) / 96.0
+    width = max(1, int(round(vb.w * fig.scale * scale)))
+    height = max(1, int(round(vb.h * fig.scale * scale)))
+    data = _rasterize(svg, width, height, background, fmt)
+    if path is None:
+        return data
+    with open(path, "wb") as fh:
+        fh.write(data)
+    return os.path.abspath(path)
+
+
+def to_pdf(fig, path=None, *, background=None, fmt: str = "pdf", **kw):
+    """Export to PDF (or PS/EPS). Returns bytes when ``path`` is ``None``."""
+    svg_kw, _ = _split_kw(kw)
+    svg_kw.setdefault("text_as_paths", True)
+    svg = fig.to_svg(**svg_kw)
+    _warn_if_text_not_outlined(fig, svg, svg_kw)
+    data = _vectorize(svg, fmt, background)
+    if path is None:
+        return data
+    with open(path, "wb") as fh:
+        fh.write(data)
+    return os.path.abspath(path)
+
+
+# --------------------------------------------------------------------------
+# Backends
+# --------------------------------------------------------------------------
+
+def _cairosvg(svg: str, fmt: str, width=None, height=None, background=None):
+    """Convert via cairosvg, or return None so the next backend gets a turn.
+
+    Every step is guarded, not just the import: cairosvg raises OSError when
+    its native Cairo library is missing, and it can raise that on import *or*
+    on first attribute access. A backend in the fallback chain must never be
+    able to end the chain.
+    """
+    try:
+        import cairosvg
+
+        fn = {"png": cairosvg.svg2png, "pdf": cairosvg.svg2pdf,
+              "ps": cairosvg.svg2ps, "eps": cairosvg.svg2ps}.get(fmt)
+    except Exception:
+        return None
+    if fn is None:
+        return None
+
+    if "<filter" in svg:
+        # cairosvg ignores filter primitives outright, so a shadow that shows
+        # up in the SVG would silently vanish here. Say so rather than ship
+        # two files that disagree.
+        warnings.warn(
+            "figkit: this figure uses an SVG filter (e.g. shadow=...), which "
+            "the cairosvg backend ignores — the rasterised output will differ "
+            "from the SVG. Drop the filter, or render with rsvg-convert / "
+            "resvg / chromium.", stacklevel=3)
+
+    kwargs = {"bytestring": svg.encode("utf-8")}
+    if width:
+        kwargs["output_width"] = width
+    if height:
+        kwargs["output_height"] = height
+    if background:
+        kwargs["background_color"] = background
+    try:
+        return fn(**kwargs)
+    except Exception as exc:
+        warnings.warn(f"figkit: the cairosvg backend failed ({exc}); "
+                      f"trying the next one", stacklevel=3)
+        return None
+
+
+def _run_cli(cmd: list, svg: str, out_suffix: str) -> bytes | None:
+    with tempfile.TemporaryDirectory(prefix="figkit-export-") as tmp:
+        src = os.path.join(tmp, "figure.svg")
+        dst = os.path.join(tmp, "figure" + out_suffix)
+        with open(src, "w", encoding="utf-8") as fh:
+            fh.write(svg)
+        real = [c.format(src=src, dst=dst) for c in cmd]
+        try:
+            proc = subprocess.run(real, capture_output=True, timeout=180)
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+        if proc.returncode != 0 or not os.path.exists(dst):
+            return None
+        with open(dst, "rb") as fh:
+            return fh.read()
+
+
+def _rasterize(svg: str, width: int, height: int, background, fmt: str) -> bytes:
+    data = _cairosvg(svg, "png", width, height, background)
+    if data:
+        return data
+    exe = shutil.which("rsvg-convert")
+    if exe:
+        cmd = [exe, "-w", str(width), "-h", str(height), "-o", "{dst}", "{src}"]
+        if background:
+            cmd[1:1] = ["-b", str(background)]
+        data = _run_cli(cmd, svg, ".png")
+        if data:
+            return data
+    exe = shutil.which("resvg")
+    if exe:
+        data = _run_cli([exe, "--width", str(width), "--height", str(height),
+                         "{src}", "{dst}"], svg, ".png")
+        if data:
+            return data
+    exe = shutil.which("inkscape")
+    if exe:
+        data = _run_cli([exe, "{src}", "--export-type=png",
+                         f"--export-width={width}", f"--export-height={height}",
+                         "--export-filename={dst}"], svg, ".png")
+        if data:
+            return data
+    exe = _chromium()
+    if exe:
+        data = _run_cli([exe, "--headless", "--disable-gpu", "--no-sandbox",
+                         f"--window-size={width},{height}",
+                         "--default-background-color=00000000",
+                         "--screenshot={dst}", "{src}"], svg, ".png")
+        if data:
+            return data
+    raise ExportError(
+        "no PNG backend available. Install one of:\n"
+        "  pip install 'figkit[export]'      (cairosvg — recommended)\n"
+        "  apt install librsvg2-bin          (rsvg-convert)\n"
+        "  cargo install resvg               (resvg)\n"
+        "Or export SVG and convert it yourself.")
+
+
+def _vectorize(svg: str, fmt: str, background) -> bytes:
+    data = _cairosvg(svg, fmt, background=background)
+    if data:
+        return data
+    suffix = "." + fmt
+    exe = shutil.which("rsvg-convert")
+    if exe:
+        data = _run_cli([exe, "-f", fmt, "-o", "{dst}", "{src}"], svg, suffix)
+        if data:
+            return data
+    exe = shutil.which("inkscape")
+    if exe:
+        data = _run_cli([exe, "{src}", f"--export-type={fmt}",
+                         "--export-filename={dst}"], svg, suffix)
+        if data:
+            return data
+    exe = _chromium()
+    if exe and fmt == "pdf":
+        data = _run_cli([exe, "--headless", "--disable-gpu", "--no-sandbox",
+                         "--print-to-pdf={dst}", "--no-pdf-header-footer",
+                         "{src}"], svg, ".pdf")
+        if data:
+            return data
+    raise ExportError(
+        f"no {fmt.upper()} backend available. Install one of:\n"
+        "  pip install 'figkit[export]'      (cairosvg — recommended)\n"
+        "  apt install librsvg2-bin          (rsvg-convert)\n"
+        "  apt install inkscape")
+
+
+def _chromium() -> str | None:
+    for name in ("chromium", "chromium-browser", "google-chrome", "chrome"):
+        exe = shutil.which(name)
+        if exe:
+            return exe
+    return None

figkit/figure.py

@@ -0,0 +1,312 @@
+"""The :class:`Figure` root: collects elements, sizes the canvas, exports."""
+
+from __future__ import annotations
+
+import os
+import warnings
+
+from .core import Group, pop_container, push_container
+from .geom import Affine, BBox, _expand_spec, to_point
+from .style import DEFAULT_THEME, Theme, use_theme
+from .svgdoc import Node, RenderContext
+
+__all__ = ["Figure"]
+
+SVG_NS = "http://www.w3.org/2000/svg"
+XLINK_NS = "http://www.w3.org/1999/xlink"
+
+
+class Figure(Group):
+    """The drawing surface.
+
+    Use it as a context manager and every element you create is added
+    automatically::
+
+        with Figure(theme=my_theme, pad=24) as fig:
+            a = Box("input")
+            b = Box("model").right_of(a, gap=40)
+            arrow(a.e, b.w)
+        fig.save("figure.svg")
+
+    By default the canvas is sized to fit its contents plus ``pad``.  Pass
+    ``w``/``h`` to pin it instead.
+    """
+
+    role = "figure"
+
+    def __init__(self, w: float = None, h: float = None, *, pad=24,
+                 background=None, theme: Theme = None, style=None,
+                 title: str = None, description: str = None,
+                 viewbox: BBox = None, origin=None, scale: float = 1.0,
+                 **props):
+        self._fixed_w = w
+        self._fixed_h = h
+        self.pad = _expand_spec(pad)
+        self.background = background
+        self.title = title
+        self.description = description
+        self._viewbox = viewbox
+        self._origin = origin
+        self.scale = float(scale)
+        self._theme_token = None
+        self._container_token = None
+        super().__init__(style=style, theme=theme or DEFAULT_THEME, add=False,
+                         **props)
+        self.parent = None
+
+    # -- context manager -------------------------------------------------
+    def __enter__(self) -> "Figure":
+        self._container_token = push_container(self)
+        self._theme_token = use_theme(self._theme or DEFAULT_THEME)
+        self._theme_token.__enter__()
+        return self
+
+    def __exit__(self, *exc):
+        if self._theme_token is not None:
+            self._theme_token.__exit__(*exc)
+            self._theme_token = None
+        pop_container(self._container_token)
+        self._container_token = None
+        return False
+
+    def child_matrix(self) -> Affine:
+        return Affine.IDENTITY
+
+    def parent_matrix(self) -> Affine:
+        return Affine.IDENTITY
+
+    # -- canvas geometry -------------------------------------------------
+    def content_bbox(self) -> BBox:
+        boxes = [c.ink_bbox for c in self._children if c.visible]
+        bb = BBox.union_all(boxes)
+        return bb if bb is not None else BBox(0, 0, 0, 0)
+
+    @property
+    def fixed_size(self) -> bool:
+        """True when both dimensions were pinned, i.e. this is a canvas."""
+        return self._fixed_w is not None and self._fixed_h is not None
+
+    def viewbox(self) -> BBox:
+        """The rectangle of world space that ends up in the output.
+
+        Auto-sized figures wrap their content plus ``pad``. Giving both ``w``
+        and ``h`` makes the figure a fixed canvas, whose origin is ``(0, 0)``
+        so that coordinates mean what they say — pass ``origin=`` to move it,
+        or ``origin="content"`` for the auto-sized behaviour.
+        """
+        if self._viewbox is not None:
+            return self._viewbox
+        content = self.content_bbox()
+        top, right, bottom, left = self.pad
+        bb = content.expand(0, top=top, right=right, bottom=bottom, left=left)
+        if self._fixed_w is not None:
+            bb = BBox(bb.x, bb.y, float(self._fixed_w), bb.h)
+        if self._fixed_h is not None:
+            bb = BBox(bb.x, bb.y, bb.w, float(self._fixed_h))
+        anchor = self._origin
+        if anchor is None and self.fixed_size:
+            anchor = (0.0, 0.0)      # a pinned canvas starts at the origin
+        if anchor is not None and anchor != "content":
+            p = to_point(anchor)
+            bb = BBox(p.x, p.y, bb.w, bb.h)
+        if bb.w <= 0:
+            bb = BBox(bb.x, bb.y, 1.0, bb.h)
+        if bb.h <= 0:
+            bb = BBox(bb.x, bb.y, bb.w, 1.0)
+        return bb
+
+    @property
+    def size(self):
+        vb = self.viewbox()
+        from .geom import Point
+        return Point(vb.w * self.scale, vb.h * self.scale)
+
+    def set_viewbox(self, x, y=None, w=None, h=None) -> "Figure":
+        """Pin the visible rectangle explicitly."""
+        self._viewbox = x if isinstance(x, BBox) else BBox(x, y, w, h)
+        return self
+
+    def fit_contents(self, pad=None) -> "Figure":
+        """Drop any pinned viewbox or fixed size and go back to auto-sizing."""
+        self._viewbox = None
+        self._fixed_w = self._fixed_h = None
+        self._origin = None
+        if pad is not None:
+            self.pad = _expand_spec(pad)
+        return self
+
+    # -- rendering -------------------------------------------------------
+    def render_context(self, **opts) -> RenderContext:
+        return RenderContext(theme=self._theme or DEFAULT_THEME, **opts)
+
+    def to_svg(self, *, pretty: bool = True, text_as_paths: bool = False,
+               embed_fonts: bool = False, standalone: bool = True,
+               scale: float = None, width: float = None,
+               height: float = None) -> str:
+        """Render to an SVG document string."""
+        ctx = self.render_context(text_as_paths=text_as_paths,
+                                  embed_fonts=embed_fonts, pretty=pretty)
+        vb = self.viewbox()
+        body_nodes = []
+        kids = sorted([c for c in self._children if c.visible],
+                      key=lambda c: (getattr(c, "z", 0) or 0))
+        for child in kids:
+            node = child.render(ctx)
+            if node is not None:
+                body_nodes.append(node)
+
+        sc = self.scale if scale is None else float(scale)
+        out_w = width if width is not None else vb.w * sc
+        out_h = height if height is not None else vb.h * sc
+
+        svg = Node("svg", xmlns=SVG_NS, xmlns__xlink=XLINK_NS,
+                   width=_len(out_w), height=_len(out_h),
+                   viewBox=f"{_n(vb.x)} {_n(vb.y)} {_n(vb.w)} {_n(vb.h)}")
+        if self.title:
+            svg.add(Node("title", text=self.title))
+        if self.description:
+            svg.add(Node("desc", text=self.description))
+
+        if embed_fonts:
+            css = _font_face_css(ctx)
+            if css:
+                svg.add(Node("style", raw=css, type="text/css"))
+        if ctx.defs:
+            defs = Node("defs")
+            defs.add(*ctx.defs)
+            svg.add(defs)
+        bg = self.background if self.background is not None else \
+            self.prop("background", None)
+        if bg and str(bg).lower() != "none":
+            svg.add(Node("rect", x=vb.x, y=vb.y, width=vb.w, height=vb.h,
+                         fill=bg))
+        svg.add(*body_nodes)
+
+        for message in ctx.warnings:
+            warnings.warn(f"figkit: {message}", stacklevel=2)
+        head = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n' \
+            if standalone else ""
+        return head + svg.render(0, pretty)
+
+    def _repr_svg_(self) -> str:
+        """Rich display in Jupyter."""
+        return self.to_svg(standalone=False)
+
+    def to_html(self, *, title: str = None, embed: bool = True,
+                background: str = "#ffffff", **svg_kw) -> str:
+        """A standalone HTML page wrapping the SVG."""
+        svg = self.to_svg(standalone=False, **svg_kw)
+        heading = title or self.title or "figure"
+        return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{_esc(heading)}</title>
+<style>
+  :root {{ color-scheme: light dark; }}
+  body {{ margin: 0; min-height: 100vh; display: grid; place-items: center;
+         background: {background}; padding: 24px; box-sizing: border-box;
+         font-family: system-ui, -apple-system, "Segoe UI", sans-serif; }}
+  .figkit-wrap {{ max-width: 100%; }}
+  .figkit-wrap svg {{ max-width: 100%; height: auto; display: block; }}
+</style>
+</head>
+<body>
+<div class="figkit-wrap">
+{svg}
+</div>
+</body>
+</html>
+"""
+
+    # -- saving ----------------------------------------------------------
+    def save(self, path, *, scale: float = None, dpi: float = None,
+             format: str = None, **kw) -> str:
+        """Write the figure to ``.svg``, ``.png``, ``.pdf`` or ``.html``.
+
+        >>> fig.save("out.svg")
+        >>> fig.save("out.png", scale=2)      # 2x pixel density
+        >>> fig.save("out.pdf")
+        """
+        from .export import save_figure
+        return save_figure(self, path, scale=scale, dpi=dpi, format=format, **kw)
+
+    def to_png(self, path=None, *, scale: float = 2.0, **kw):
+        from .export import to_png
+        return to_png(self, path, scale=scale, **kw)
+
+    def to_pdf(self, path=None, **kw):
+        from .export import to_pdf
+        return to_pdf(self, path, **kw)
+
+    def audit(self, **options):
+        """Check the figure for the mistakes you would otherwise spot by eye.
+
+        Returns a :class:`~figkit.audit.Report` that is falsy when nothing
+        looks wrong, so ``print(fig.audit())`` is usually all you need::
+
+            with Figure() as fig:
+                ...
+            print(fig.audit())
+
+        See :func:`figkit.audit.audit` for the individual checks and how to
+        switch them off.
+        """
+        from .audit import audit as run_audit
+        return run_audit(self, **options)
+
+    def show(self, path=None) -> str:
+        """Write an HTML preview and return its path (handy while iterating)."""
+        path = path or "figure.html"
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(self.to_html())
+        return os.path.abspath(path)
+
+    def __repr__(self) -> str:
+        vb = self.viewbox()
+        return (f"<Figure {len(self._children)} elements "
+                f"{vb.w:.4g}x{vb.h:.4g}>")
+
+
+def _n(v: float) -> str:
+    from .svgpath import fmt
+    return fmt(v)
+
+
+def _len(v: float) -> str:
+    from .svgpath import fmt
+    return fmt(v)
+
+
+def _esc(s: str) -> str:
+    return (str(s).replace("&", "&amp;").replace("<", "&lt;")
+            .replace(">", "&gt;"))
+
+
+def _font_face_css(ctx: RenderContext) -> str:
+    """Base64 ``@font-face`` rules for every font actually used."""
+    import base64
+
+    from .fonts import get_font
+
+    rules = []
+    seen = set()
+    for family, weight, style in sorted(ctx.fonts_used, key=lambda t: str(t)):
+        font = get_font(family, weight, style)
+        if not font.available or font.path in seen:
+            continue
+        data = font.font_data()
+        if not data or len(data) > 6_000_000:
+            continue
+        seen.add(font.path)
+        ext = os.path.splitext(font.path)[1].lower()
+        fmt_name = {".otf": "opentype", ".ttf": "truetype",
+                    ".woff": "woff", ".woff2": "woff2"}.get(ext, "truetype")
+        b64 = base64.b64encode(data).decode("ascii")
+        primary = str(family).split(",")[0].strip().strip("'\"")
+        rules.append(
+            f"@font-face{{font-family:'{primary}';"
+            f"font-weight:{font.weight};font-style:{font.style};"
+            f"src:url(data:font/{fmt_name};base64,{b64}) format('{fmt_name}');}}")
+    return "\n".join(rules)