pidraw 1.2.0__py3-none-any.whl

pidraw/__init__.py

@@ -0,0 +1,192 @@
+"""PiDraw — universal diagram rendering platform.
+
+Converts diagram source code from many diagram languages into
+optimised SVG through a plugin-based renderer architecture.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pidraw")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+
+import pidraw.engines  # noqa: F401 — trigger auto-registration
+from pidraw.async_api import arender, arender_file
+from pidraw.backend.png import svg_to_png
+from pidraw.backend.svg import SvgBackend
+from pidraw.benchmark import BenchmarkReport, BenchmarkResult, run_benchmarks
+from pidraw.cache import CacheManager, CacheStats
+from pidraw.core.converters import (
+    ASCIIConverter,
+    D2Converter,
+    GraphvizConverter,
+    MermaidConverter,
+    PlantUMLConverter,
+    convert,
+    get_converter,
+    list_converters,
+)
+from pidraw.core.models import (
+    ArrowStyle,
+    Diagram,
+    Edge,
+    EdgeStyle,
+    FontWeight,
+    Group,
+    Label,
+    Layout,
+    LayoutType,
+    Node,
+    Point,
+    Position,
+    Shape,
+    ShapeType,
+    Size,
+    Style,
+    TextAlign,
+    Viewport,
+)
+from pidraw.detector import detect, detect_language
+from pidraw.diagnostics import analyze
+from pidraw.engines.base import BaseRenderer
+from pidraw.engines.d2 import D2Renderer
+from pidraw.engines.graphviz import GraphvizRenderer
+from pidraw.engines.mermaid import MermaidRenderer
+from pidraw.engines.plantuml import PlantUMLRenderer
+from pidraw.exceptions import (
+    EngineNotAvailableError,
+    LanguageNotSupportedError,
+    LayoutError,
+    OptimizationError,
+    ParseError,
+    PiDrawError,
+    PluginError,
+    PngConversionError,
+    RecoverableRenderingError,
+    RendererNotFoundError,
+    RenderError,
+    RenderingError,
+    RenderTimeoutError,
+    UnsupportedLanguageError,
+)
+from pidraw.formats import FormatInfo, format_table, list_formats
+from pidraw.incremental import IncrementalRenderer
+from pidraw.large import render_large_file
+from pidraw.layout import apply_layout
+from pidraw.models import AnalysisResult, DetectionResult, DiagramLanguage
+from pidraw.optimizer import (
+    OptimizationResult,
+    optimize_by_level,
+    optimize_many,
+    optimize_svg,
+)
+from pidraw.pipeline import ExportPipeline, render_native, render_native_from_diagram
+from pidraw.pool import RenderPool
+from pidraw.quality import QualityProcessor
+from pidraw.registry import (
+    clear_registry,
+    discover_plugins,
+    get_renderer,
+    list_renderers,
+    register_renderer,
+)
+from pidraw.renderer import render, render_file, render_many
+from pidraw.renderer_class import Renderer
+from pidraw.result import RenderResult
+from pidraw.themes import apply_theme, get_theme, list_themes
+from pidraw.typography import FontSpec, estimate_text_size
+
+__all__ = [
+    "render",
+    "render_file",
+    "render_many",
+    "render_large_file",
+    "render_native",
+    "render_native_from_diagram",
+    "Renderer",
+    "RenderResult",
+    "arender",
+    "arender_file",
+    "detect",
+    "detect_language",
+    "analyze",
+    "register_renderer",
+    "get_renderer",
+    "list_renderers",
+    "clear_registry",
+    "discover_plugins",
+    "BaseRenderer",
+    "MermaidRenderer",
+    "GraphvizRenderer",
+    "PlantUMLRenderer",
+    "D2Renderer",
+    "DiagramLanguage",
+    "DetectionResult",
+    "AnalysisResult",
+    "optimize_svg",
+    "optimize_many",
+    "optimize_by_level",
+    "OptimizationResult",
+    "CacheManager",
+    "CacheStats",
+    "RenderPool",
+    "QualityProcessor",
+    "IncrementalRenderer",
+    "FormatInfo",
+    "list_formats",
+    "format_table",
+    "run_benchmarks",
+    "BenchmarkReport",
+    "BenchmarkResult",
+    "RecoverableRenderingError",
+    "svg_to_png",
+    "SvgBackend",
+    "ExportPipeline",
+    "Diagram",
+    "Node",
+    "Edge",
+    "Label",
+    "Shape",
+    "ShapeType",
+    "Style",
+    "EdgeStyle",
+    "ArrowStyle",
+    "Layout",
+    "LayoutType",
+    "Group",
+    "Viewport",
+    "Position",
+    "Size",
+    "Point",
+    "FontWeight",
+    "TextAlign",
+    "FontSpec",
+    "estimate_text_size",
+    "apply_layout",
+    "apply_theme",
+    "get_theme",
+    "list_themes",
+    "convert",
+    "get_converter",
+    "list_converters",
+    "MermaidConverter",
+    "PlantUMLConverter",
+    "GraphvizConverter",
+    "D2Converter",
+    "ASCIIConverter",
+    "PiDrawError",
+    "LanguageNotSupportedError",
+    "EngineNotAvailableError",
+    "RenderError",
+    "ParseError",
+    "LayoutError",
+    "RenderTimeoutError",
+    "OptimizationError",
+    "PngConversionError",
+    "UnsupportedLanguageError",
+    "RendererNotFoundError",
+    "RenderingError",
+    "PluginError",
+]

pidraw/async_api.py

@@ -0,0 +1,93 @@
+"""Async rendering API for PiDraw.
+
+Provides ``arender`` and ``arender_file`` as async counterparts to
+the synchronous ``render`` / ``render_file`` functions.
+"""
+
+from __future__ import annotations
+
+from pidraw.renderer import render
+from pidraw.result import RenderResult
+
+
+async def arender(
+    source: str,
+    *,
+    language: str | None = None,
+    optimize: str | None = None,
+    output_format: str = "svg",
+    timeout: float = 30.0,
+    theme: str = "light",
+) -> RenderResult:
+    """Async version of :func:`render`. Safe to call from any async framework.
+
+    Parameters
+    ----------
+    source : str
+        The diagram source code.
+    language : str | None
+        Explicit language identifier.  Auto-detected when ``None``.
+    optimize : str | None
+        Optimisation level (``"fast"``, ``"balanced"``, ``"maximum"``).
+    output_format : str
+        Output format.  ``"svg"`` (default) or ``"png"``.
+    timeout : float
+        Maximum render time in seconds.
+    theme : str
+        Theme name to apply.
+
+    Returns
+    -------
+    RenderResult
+        The rendered output.
+
+    Raises
+    ------
+    PiDrawError
+        On any rendering failure.
+    """
+    import asyncio
+
+    loop = asyncio.get_event_loop()
+
+    def _sync_render() -> RenderResult:
+        return render(
+            source,
+            language=language,
+            format=output_format,
+            optimize=optimize or False,
+            timeout=timeout,
+            theme=theme,
+        )
+
+    return await loop.run_in_executor(None, _sync_render)
+
+
+async def arender_file(path: str, **kwargs: object) -> RenderResult:
+    """Async version of :func:`render_file`.
+
+    Parameters
+    ----------
+    path : str
+        Path to the diagram source file.
+    **kwargs
+        Forwarded to :func:`arender`.
+
+    Returns
+    -------
+    RenderResult
+        The rendered output.
+    """
+    import asyncio
+
+    source: str
+    try:
+        import aiofiles  # noqa: F401
+
+        async with aiofiles.open(path, encoding="utf-8") as f:  # type: ignore[union-attr]
+            source = await f.read()  # type: ignore[union-attr]
+    except ImportError:
+        source = await asyncio.to_thread(
+            lambda: open(path, "r", encoding="utf-8").read()
+        )
+    return await arender(source, **kwargs)

pidraw/backend/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from pidraw.backend.svg import SvgBackend
+
+__all__ = ["SvgBackend"]

pidraw/backend/png.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from importlib import util as importlib_util
+from io import BytesIO
+from typing import Callable, Optional
+
+from pidraw.exceptions import PngConversionError
+
+
+# Pattern to match SVG background rectangles (solid fills that cover the full viewport)
+_BG_RECT_RE = re.compile(
+    r"<rect\s[^>]*?(?:width\s*=\s*['\"]100%(?:[^>]*?height\s*=\s*['\"]100%['\"])"
+    r"|height\s*=\s*['\"]100%(?:[^>]*?width\s*=\s*['\"]100%['\"]))[^>]*?\/?\s*>",
+    re.IGNORECASE,
+)
+
+
+def strip_svg_background(svg: str) -> str:
+    return _BG_RECT_RE.sub("", svg)
+
+
+def trim_png(png_bytes: bytes, padding: int = 0) -> bytes:
+    try:
+        from PIL import Image
+
+        Image.MAX_IMAGE_PIXELS = None
+        img = Image.open(BytesIO(png_bytes))
+        if img.mode != "RGBA":
+            img = img.convert("RGBA")
+        bbox = img.getbbox()
+        if bbox is None:
+            return png_bytes
+        if padding <= 0:
+            padding = max(50, int(min(img.width, img.height) * 0.08))
+        left = max(0, bbox[0] - padding)
+        upper = max(0, bbox[1] - padding)
+        right = min(img.width, bbox[2] + padding)
+        lower = min(img.height, bbox[3] + padding)
+        cropped = img.crop((left, upper, right, lower))
+        buf = BytesIO()
+        cropped.save(buf, format="PNG")
+        buf.seek(0)
+        return buf.read()
+    except Exception:
+        return png_bytes
+
+
+def svg_to_png(
+    svg: str,
+    scale: float = 1.0,
+    background_color: Optional[str] = None,
+    output_width: Optional[int] = None,
+    output_height: Optional[int] = None,
+    transparent: bool = True,
+    trim: bool = True,
+) -> bytes:
+    if transparent:
+        svg = strip_svg_background(svg)
+    backend = _detect_backend()
+    try:
+        result = backend(
+            svg,
+            scale=scale,
+            background_color=background_color if not transparent else None,
+            output_width=output_width,
+            output_height=output_height,
+            transparent=transparent,
+        )
+    except Exception as exc:
+        raise PngConversionError(
+            f"{backend.__name__} failed: {exc}"
+        ) from exc
+    if transparent and trim:
+        result = trim_png(result)
+    return result
+
+
+BackendFn = Callable[..., bytes]
+
+
+def _detect_backend() -> BackendFn:
+    errors: list[str] = []
+
+    if shutil.which("resvg") is not None:
+        return _render_resvg
+    else:
+        errors.append("resvg CLI not found on PATH")
+
+    if importlib_util.find_spec("cairosvg") is not None:
+        try:
+            import cairosvg  # type: ignore[import-not-found, import-untyped]
+
+            cairosvg.svg2png
+            return _render_cairosvg
+        except OSError as e:
+            errors.append(f"cairosvg (Cairo library not found: {e})")
+    else:
+        errors.append("cairosvg not installed")
+
+    if importlib_util.find_spec("playwright") is not None:
+        return _render_playwright
+    else:
+        errors.append("playwright not installed")
+
+    raise ImportError(
+        "No SVG-to-PNG backend available.\n\n"
+        "Options:\n"
+        "  Install resvg CLI:  https://github.com/RazrFalcon/resvg/releases\n"
+        "  pip install pidraw[png-playwright] && playwright install chromium\n"
+        "  pip install pidraw[png]        (cairosvg - needs Cairo DLLs)\n\n"
+        "Detected issues:\n"
+        + "\n".join(f"  - {e}" for e in errors)
+    )
+
+
+def _render_resvg(
+    svg: str,
+    scale: float = 1.0,
+    background_color: Optional[str] = None,
+    output_width: Optional[int] = None,
+    output_height: Optional[int] = None,
+    transparent: bool = True,
+) -> bytes:
+    tmp_dir: Optional[str] = None
+    try:
+        tmp_dir = tempfile.mkdtemp(prefix="pidraw_resvg_")
+        input_path = os.path.join(tmp_dir, "input.svg")
+        output_path = os.path.join(tmp_dir, "output.png")
+        with open(input_path, "w", encoding="utf-8") as f:
+            f.write(svg)
+        cmd = ["resvg", input_path, output_path]
+        if output_width is not None and output_height is not None:
+            cmd.extend(["--width", str(output_width), "--height", str(output_height)])
+        if scale != 1.0:
+            cmd.extend(["--dpi", str(int(96 * scale))])
+        subprocess.run(cmd, capture_output=True, timeout=60, check=True)
+        with open(output_path, "rb") as f:
+            return f.read()
+    except subprocess.TimeoutExpired:
+        raise PngConversionError("resvg timed out after 60s")
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.decode("utf-8", errors="replace") if exc.stderr else ""
+        raise PngConversionError(f"resvg failed: {stderr}")
+    except FileNotFoundError:
+        raise PngConversionError("resvg executable not found")
+    finally:
+        if tmp_dir is not None and os.path.isdir(tmp_dir):
+            try:
+                shutil.rmtree(tmp_dir)
+            except OSError:
+                pass
+
+
+def _render_cairosvg(
+    svg: str,
+    scale: float = 1.0,
+    background_color: Optional[str] = None,
+    output_width: Optional[int] = None,
+    output_height: Optional[int] = None,
+    transparent: bool = True,
+) -> bytes:
+    import cairosvg  # type: ignore[import-untyped]
+
+    kwargs: dict = {"scale": scale}
+    bg = None if transparent else background_color
+    if bg is not None:
+        kwargs["background_color"] = bg
+    elif transparent:
+        kwargs["background_color"] = "transparent"
+    if output_width is not None:
+        kwargs["output_width"] = output_width
+    if output_height is not None:
+        kwargs["output_height"] = output_height
+
+    return cairosvg.svg2png(bytestring=svg.encode("utf-8"), **kwargs)
+
+
+def _render_playwright(
+    svg: str,
+    scale: float = 1.0,
+    background_color: Optional[str] = None,
+    output_width: Optional[int] = None,
+    output_height: Optional[int] = None,
+    transparent: bool = True,
+) -> bytes:
+    from playwright.sync_api import sync_playwright  # type: ignore[import-not-found, import-untyped]
+
+    has_bg = background_color is not None and not transparent
+    bg_css = f"background: {background_color};" if has_bg else ""
+    html_parts = [
+        "<!DOCTYPE html><html><head><style>",
+        f"  body {{ margin: 0; {bg_css} }}",
+        "  svg { max-width: 100%; height: auto; }",
+        "</style></head><body>",
+        svg,
+        "</body></html>",
+    ]
+    html = "\n".join(html_parts)
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page(
+            device_scale_factor=scale,
+            viewport={"width": output_width or 800, "height": output_height or 600},
+        )
+        page.set_content(html)
+        png_bytes = page.screenshot(full_page=True, omit_background=transparent)
+        browser.close()
+
+    return png_bytes