dataface 0.1.2__py3-none-any.whl

dataface/core/render/renderer.py

@@ -0,0 +1,467 @@
+"""Dataface renderer module.
+
+Stage: RENDER
+Purpose: Render compiled datafaces to various output formats.
+
+Entry Points:
+    - render(face, executor, format, variables, **options) -> str | bytes
+    - render_chart(chart, data, **options) -> str
+
+This is the main rendering orchestration module. It:
+1. Takes a Face from compile stage
+2. Delegates SVG rendering to faces.py
+3. Delegates format conversion to converters/
+4. Produces output in requested format
+
+Dependencies:
+    - dataface.compile (for Face, Chart)
+    - dataface.execute (for Executor)
+    - .faces (for SVG rendering)
+    - .charts (for chart rendering)
+    - .converters (for format conversion)
+"""
+
+import contextlib
+from pathlib import Path
+from typing import Any
+
+from dataface.core.compile.config import (
+    get_config,
+    get_project_warnings_ignore,
+    get_rendering_config,
+)
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.compile.models.face.compiled import Face, VariableValues
+from dataface.core.compile.normalizer import sync_face_resolved_style
+from dataface.core.compile.variables import parse_variable_json_strings
+from dataface.core.errors import StructuredError
+from dataface.core.execute.batch import collect_layout_chart_query_names
+from dataface.core.execute.executor import Executor
+from dataface.core.execute.parallel import (
+    execute_queries_parallel,
+    execute_queries_sequential,
+    plan_query_execution_phases,
+)
+from dataface.core.render.chart.renderers import SVG_RENDERERS
+from dataface.core.render.converters import to_html, to_pdf, to_png
+from dataface.core.render.errors import (
+    FormatError,
+    MissingRequiredVariablesError,
+    MissingVariable,
+    RenderError,
+)
+from dataface.core.render.faces import render_face_svg
+from dataface.core.render.layout_sizing import calculate_data_aware_layout
+from dataface.core.render.render_result import RenderResult
+from dataface.core.render.warnings import (
+    RenderWarning,
+    WarningContext,
+    registry as _warnings_registry,
+    run_all,
+)
+from dataface.core.render.warnings.suppression import partition as _partition_warnings
+from dataface.core.resolve_face import resolve_face
+
+# Formats that produce SVG output (require vl-convert chart rendering).
+_SVG_FORMATS = frozenset({"svg", "html", "png", "pdf"})
+
+# Chart types that do NOT produce a Vega-Lite spec (own SVG renderer).
+# vega_specs in WarningContext is sparse: these chart ids are omitted.
+_NON_VEGA_CHART_TYPES = frozenset(SVG_RENDERERS.keys())
+
+
+def _collect_render_warnings(
+    face: Face,
+    executor: Executor,
+    variables: VariableValues,
+) -> list[RenderWarning]:
+    """Build WarningContext from cached query results and run all detectors.
+
+    Called after queries have already executed (results are in the executor
+    cache). Only charts reachable from the layout tree are included — orphan
+    charts (present in face.charts but absent from the layout) were never
+    pre-executed and are intentionally excluded so this function never
+    triggers a fresh adapter call.
+    """
+    # Fast path: skip all spec/query work when no detectors are registered.
+    # Avoids double-building vega specs on every SVG render for zero benefit.
+    if not _warnings_registry.DETECTORS:
+        return []
+
+    # Restrict to charts the layout actually renders — same set that
+    # execute_queries_parallel / execute_queries_sequential pre-executed.
+    # Orphan charts (in face.charts but absent from the layout) were never
+    # pre-cached; including them would trigger a fresh adapter call.
+    pre_executed_query_names = collect_layout_chart_query_names(face)
+
+    chart_results: dict[str, list[dict[str, Any]]] = {}
+    for chart_id, chart in face.charts.items():
+        if chart.query_name not in pre_executed_query_names:
+            continue
+        # Omit failed charts so detectors can distinguish failure from genuine
+        # zero rows: absent from chart_results = failed execute.
+        with contextlib.suppress(
+            Exception
+        ):  # noqa: BLE001 — query failure already recorded elsewhere
+            chart_results[chart_id] = executor.execute_chart(chart, variables)
+
+    from dataface.core.render.chart import generate_vega_lite_spec
+
+    vega_specs: dict[str, dict[str, Any]] = {}
+    for chart_id, chart in face.charts.items():
+        if chart.query_name not in pre_executed_query_names:
+            continue
+        if chart.type in _NON_VEGA_CHART_TYPES:
+            continue
+        data = chart_results.get(chart_id, [])
+        # Spec generation failure must not block the render — omit from vega_specs.
+        with contextlib.suppress(
+            Exception
+        ):  # noqa: BLE001 — spec failure must not block render
+            vega_specs[chart_id] = generate_vega_lite_spec(chart, data)
+
+    ctx = WarningContext(
+        face_spec=face, chart_results=chart_results, vega_specs=vega_specs
+    )
+    return run_all(ctx)
+
+
+def render(
+    face: Face,
+    executor: Executor,
+    format: str = "svg",
+    variables: VariableValues | None = None,
+    ignore_codes: set[str] | None = None,
+    project_dir: Path | None = None,
+    **options: Any,
+) -> RenderResult:
+    """Render a compiled dataface.
+
+    Stage: RENDER (Main Entry Point)
+
+    This is the main rendering function. It walks the layout structure,
+    renders each chart (triggering lazy query execution), and produces
+    output in the requested format.
+
+    Args:
+        face: Compiled dataface to render
+        executor: Executor for query execution
+        format: Output format (svg, html, png, pdf, terminal, json, text, yaml)
+        variables: Variable values for queries
+        ignore_codes: Caller-supplied set of warning codes to suppress (CLI seam).
+        project_dir: Project directory for reading dataface.yml warnings.ignore.
+        **options: Format-specific options
+            - background: Background color
+            - scale: Scale factor (for png)
+            - grid: Show grid overlay (for debugging)
+
+    Returns:
+        RenderResult with:
+            - output: rendered content (str or bytes)
+            - chart_errors: per-chart runtime failures (face still rendered)
+            - face_error: post-validation fatal (None when render succeeded)
+            - render_warnings: active (non-suppressed) warnings
+            - suppressed_warnings: warnings dropped by any ignore layer
+
+    Raises:
+        RenderError: If a face-level invariant is violated before rendering starts
+        FormatError: If format is unknown
+    """
+    # Compile warns on orphans; render hard-fails the empty-layout-with-charts
+    # case so the dashboard never silently renders with nothing visible.
+    if face.charts and not face.layout.items:
+        from dataface.core.errors import DF_RENDER_NO_LAYOUT
+
+        chart_list = ", ".join(sorted(face.charts.keys()))
+        raise RenderError.from_code(DF_RENDER_NO_LAYOUT, charts=chart_list)
+
+    # Trust the normalizer - use pre-computed variable_defaults
+    variable_registry = face.variable_registry or {}
+
+    # Merge variables: start with None for all vars, then defaults, then user values
+    all_variables: dict[str, Any] = dict.fromkeys(variable_registry)
+    all_variables.update(face.variable_defaults)  # Pre-computed by normalizer
+    # Parse JSON strings in variables (from URL parameters) and merge
+    parsed_variables = parse_variable_json_strings(variables or {})
+    merged_variables = {**all_variables, **parsed_variables}
+
+    # Face-level precondition: required variables must have a value before any query runs.
+    # None, empty string, and empty list all count as "not provided" — URL params arrive
+    # as strings so ?var= produces "" which is as unscoped as no value at all.
+    if variable_registry:
+
+        def _is_absent(v: Any) -> bool:
+            if v is None:
+                return True
+            if isinstance(v, str):
+                return not v.strip()
+            if isinstance(v, (list, tuple, set)):
+                return len(v) == 0
+            return False
+
+        missing = [
+            MissingVariable(
+                key=key,
+                label=var.label,
+                description=var.description,
+                input_type=var.input,
+            )
+            for key, var in variable_registry.items()
+            if var.required is True and _is_absent(merged_variables.get(key))
+        ]
+        if missing:
+            raise MissingRequiredVariablesError(missing)
+
+    # Pre-render query execution — authoritative, not a fallback.
+    # Queries run BEFORE calculate_data_aware_layout so the sizing pass can
+    # use cached results (render-first sizing reads query data from the executor
+    # cache without re-executing).
+    # Phase 1: chart-direct queries without {{ results.X }} run in parallel.
+    # Phase 2: chart-direct {{ results.X }} queries run sequentially once
+    # their upstream results are cached.
+    # Errors are stored on the executor (executor._query_errors) so that
+    # execute_chart() during the render walk raises the stored error
+    # instead of re-executing.  The render walk never retries a failed query.
+    query_names = collect_layout_chart_query_names(face)
+    parallel_query_names, sequential_query_names = plan_query_execution_phases(
+        face, query_names
+    )
+    execute_queries_parallel(executor, face, parallel_query_names, merged_variables)
+    execute_queries_sequential(executor, sequential_query_names, merged_variables)
+
+    # Run warning detectors now that queries are cached.
+    # Partition into active vs suppressed using the union of three ignore layers.
+    _all_warnings = _collect_render_warnings(face, executor, merged_variables)
+    _project_codes = get_project_warnings_ignore(project_dir)
+    _per_chart_codes: dict[str, set[str]] = {
+        chart_id: set(chart.warnings_ignore)
+        for chart_id, chart in face.charts.items()
+        if chart.warnings_ignore
+    }
+    render_warnings, suppressed_warnings = _partition_warnings(
+        _all_warnings,
+        cli_codes=ignore_codes or set(),
+        project_codes=set(_project_codes),
+        per_chart_codes=_per_chart_codes,
+    )
+
+    # Sync face.resolved_style (and all nested sub-board faces) from face.theme
+    # before layout sizing so calculate_data_aware_layout reads the live value.
+    sync_face_resolved_style(face)
+
+    # Calculate layout with data awareness — table heights use actual row counts,
+    # and Vega-Lite charts are rendered to get true heights (render-first sizing).
+    # Render-first sizing is skipped for non-SVG formats (yaml/json/text) since
+    # those formats don't render charts and don't benefit from actual heights.
+    # Returns (face, render_cache) where render_cache holds pre-rendered SVGs.
+    face, render_cache = calculate_data_aware_layout(
+        face,
+        executor,
+        merged_variables,
+        render_first=format in _SVG_FORMATS,
+    )
+
+    # Resolve the sized face: bake board config constants, style, and Vega config.
+    # Called after data-aware sizing so resolved dimensions reflect actual heights.
+    config = get_config()
+    resolved_face = resolve_face(face, config)
+
+    # Resolve SVG canvas background: API override wins, otherwise use the
+    # cascaded face background (theme default or authored override, already merged).
+    override = options.get("background")
+    if override is not None:
+        background = None if override == "transparent" else override
+    else:
+        resolved_bg = resolved_face.style.background
+        background = None if resolved_bg == "transparent" else resolved_bg
+
+    # Per-chart error collector: single append site in render_chart_item.
+    # All formats share this collector so callers get chart_errors regardless of format.
+    error_collector: list[StructuredError] = []
+
+    # JSON/text formats: skip SVG rendering entirely — walk layout tree directly
+    if format == "json":
+        from dataface.core.render.json_format import render_face_json
+
+        output = render_face_json(
+            face, executor, merged_variables, error_collector=error_collector
+        )
+        return RenderResult(
+            output=output,
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    if format == "text":
+        from dataface.core.render.text_format import render_face_text
+
+        output = render_face_text(
+            face, executor, merged_variables, error_collector=error_collector
+        )
+        return RenderResult(
+            output=output,
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    if format == "yaml":
+        from dataface.core.render.yaml_format import render_face_yaml
+
+        output = render_face_yaml(
+            face, executor, merged_variables, error_collector=error_collector
+        )
+        return RenderResult(
+            output=output,
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    # Render layout to SVG
+    # Format determines whether variables are interactive (foreignObject) or read-only (static text)
+    # PNG/PDF export requires read-only because svglib doesn't support foreignObject
+    # HTML format supports foreignObject, so it should also get interactive variables
+    interactive = format in ("svg", "html")
+
+    # Board link rewriting: set context for the duration of this render pass
+    from dataface.core.render.board_links import set_link_context
+
+    link_context = options.get("link_context")
+    set_link_context(link_context)
+
+    try:
+        grid_enabled = options.get("grid", False)
+        margins_enabled = options.get("margins", False)
+        svg_content = render_face_svg(
+            resolved_face,
+            executor,
+            merged_variables,
+            background,
+            grid_enabled,
+            interactive,
+            render_cache=render_cache,
+            margins=margins_enabled,
+            error_collector=error_collector,
+        )
+    except DatafaceError as e:
+        # Face-level fatal: a DF-RENDER-* code escaped chart isolation
+        # (e.g. DF_RENDER_NO_LAYOUT, MissingRequiredVariablesError). Surface as
+        # face_error so callers see the structured code unwrapped.
+        set_link_context(None)
+        return RenderResult(
+            output=None,
+            chart_errors=error_collector,
+            face_error=e.to_structured(),
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+    except Exception as e:  # noqa: BLE001
+        from dataface.core.errors import DF_RENDER_INTERNAL
+
+        set_link_context(None)
+        wrapped = RenderError.from_code(DF_RENDER_INTERNAL, inner_message=str(e))
+        return RenderResult(
+            output=None,
+            chart_errors=error_collector,
+            face_error=wrapped.to_structured(),
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+    finally:
+        set_link_context(None)
+
+    # Convert to requested format
+    if format == "svg":
+        return RenderResult(
+            output=svg_content,
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    elif format == "html":
+        html_output = to_html(
+            face,
+            svg_content,
+            background,
+            executor,
+            merged_variables,
+        )
+        return RenderResult(
+            output=html_output,
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    elif format == "png":
+        png_scale = options.get("scale")
+        if png_scale is None:
+            png_scale = get_rendering_config().png.scale
+        return RenderResult(
+            output=to_png(svg_content, png_scale),
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    elif format == "pdf":
+        return RenderResult(
+            output=to_pdf(svg_content),
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    elif format == "terminal":
+        return RenderResult(
+            output=_to_terminal(face, executor, merged_variables, **options),
+            chart_errors=error_collector,
+            render_warnings=render_warnings,
+            suppressed_warnings=suppressed_warnings,
+        )
+
+    else:
+        from dataface.core.errors import DF_RENDER_FORMAT_UNSUPPORTED
+
+        raise FormatError.from_code(DF_RENDER_FORMAT_UNSUPPORTED, format=format)
+
+
+def _to_terminal(
+    face: Face,
+    executor: Executor,
+    variables: VariableValues,
+    **options: Any,
+) -> str:
+    """Render face to terminal output.
+
+    Args:
+        face: Face to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        **options: Terminal-specific options
+            - width: Terminal width in characters
+            - height: Terminal height in characters
+            - colors: Whether to use ANSI colors (default: True)
+
+    Returns:
+        Terminal-formatted string
+    """
+    from dataface.core.render.terminal import render_face_terminal
+
+    return render_face_terminal(
+        face,
+        executor,
+        variables=variables,
+        width=options.get("width"),
+        height=options.get("height"),
+        colors=options.get("colors", True),
+        **{k: v for k, v in options.items() if k not in ("width", "height", "colors")},
+    )
+
+
+__all__ = [
+    "render",
+]

dataface/core/render/script_embedding.py

@@ -0,0 +1,16 @@
+"""Helpers for embedding JavaScript into rendered SVG output."""
+
+
+def escape_cdata(content: str) -> str:
+    """Escape sequences that would terminate a CDATA section."""
+    return content.replace("]]>", "]]]]><![CDATA[>")
+
+
+def embed_svg_script(script: str) -> str:
+    """Wrap JavaScript for safe inline SVG execution."""
+    script = escape_cdata(script)
+    return f"""<script type="text/javascript">
+<![CDATA[
+{script}
+]]>
+</script>"""

dataface/core/render/svg_utils.py

@@ -0,0 +1,212 @@
+"""SVG utility functions for rendering.
+
+Stage: RENDER
+Purpose: Provide SVG-specific utilities for dataface rendering.
+
+This module handles:
+- Grid pattern generation (loaded from template file)
+- SVG styles generation (loaded from template file)
+- Title rendering (using mdsvg)
+- Error message rendering (using template file)
+- SVG content extraction and dimension parsing
+
+Dependencies:
+    - .template_loader (for Jinja2 template loading)
+    - .themes (for theme colors)
+    - mdsvg (required, for markdown rendering and text wrapping)
+"""
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+# ---------------------------------------------------------------------------
+# Pixel snapping
+# ---------------------------------------------------------------------------
+
+
+def _px(v: float) -> int:
+    """Snap a float coordinate to the nearest integer pixel.
+
+    SVG transforms are applied before pixel rasterization: a sub-pixel ancestor
+    translate pushes a 1px-tall rule onto fractional rows and the rasterizer
+    splits it across two pixels at reduced opacity — reading visually as "thin"
+    or "faded". Rounding each emitted translate keeps every cumulative transform
+    on an integer boundary, so rules, rects, and other 1px structural marks stay
+    crisp.
+
+    Uses Python's built-in ``round()``, which applies banker's rounding
+    (round-half-to-even): ``_px(24.5) == 24``, ``_px(25.5) == 26``. Values
+    that fall exactly on a .5 boundary may round either direction; this is
+    non-monotonic but produces the least cumulative drift over long sequences.
+    """
+    return int(round(v))
+
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedStyle
+
+from dataface.core.render.template_loader import render_template
+
+# Compiled regex patterns for SVG parsing - avoids recompilation on each call
+_SVG_CONTENT_RE = re.compile(r"<svg[^>]*>(.*)</svg>", re.DOTALL)
+_SVG_WIDTH_RE = re.compile(r'width=["\'](\d+(?:\.\d+)?)["\']')
+_SVG_HEIGHT_RE = re.compile(r'height=["\'](\d+(?:\.\d+)?)["\']')
+_SVG_VIEWBOX_RE = re.compile(
+    r'viewBox=["\']0\s+0\s+(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)["\']'
+)
+
+
+@dataclass
+class SVGDimensions:
+    """Dimensions extracted from an SVG string."""
+
+    width: float
+    height: float
+
+
+def extract_svg_inner_content(svg: str) -> str:
+    """Extract inner content from an SVG string (strip the <svg> wrapper).
+
+    Args:
+        svg: Full SVG string with wrapper
+
+    Returns:
+        Inner content without <svg>...</svg> wrapper
+
+    Raises:
+        ValueError: If SVG content cannot be extracted
+
+    TODO(mdsvg#10): Replace with structured RenderResult when available.
+    See: https://github.com/davefowler/markdown-svg/issues/10
+    """
+    match = _SVG_CONTENT_RE.search(svg)
+    if not match:
+        raise ValueError(f"Failed to extract SVG content from: {svg[:100]}...")
+    return match.group(1)
+
+
+def extract_svg_dimensions(
+    svg: str, default_width: float = 0.0, default_height: float = 0.0
+) -> SVGDimensions:
+    """Extract width and height from an SVG string.
+
+    Checks viewBox first (more reliable for Vega-Lite output), then falls back
+    to width/height attributes.
+
+    Args:
+        svg: SVG string to parse
+        default_width: Default width if not found
+        default_height: Default height if not found
+
+    Returns:
+        SVGDimensions with extracted or default values
+    """
+    # Prefer viewBox dimensions (more reliable for Vega-Lite output)
+    viewbox_match = _SVG_VIEWBOX_RE.search(svg)
+    if viewbox_match:
+        return SVGDimensions(
+            width=float(viewbox_match.group(1)),
+            height=float(viewbox_match.group(2)),
+        )
+
+    # Fall back to explicit width/height attributes
+    width = default_width
+    height = default_height
+
+    width_match = _SVG_WIDTH_RE.search(svg)
+    if width_match:
+        width = float(width_match.group(1))
+
+    height_match = _SVG_HEIGHT_RE.search(svg)
+    if height_match:
+        height = float(height_match.group(1))
+
+    return SVGDimensions(width=width, height=height)
+
+
+def create_grid_pattern() -> str:
+    """Create an SVG pattern definition for a 100x100 grid.
+
+    Returns:
+        SVG <pattern> element for 100x100 grid overlay.
+    """
+    return render_template("svg/grid_pattern.svg")
+
+
+def generate_svg_styles(
+    emoji_mode: Literal["monochrome", "color", "system-default", "disabled"],
+) -> str:
+    """Generate CSS styles for SVG charts and interactions.
+
+    Args:
+        emoji_mode: One of monochrome / color / system-default / disabled.
+            Controls whether the @font-face emoji partial and font-variant-emoji
+            rule are included in the embedded SVG stylesheet.
+
+    Returns:
+        SVG <style> element with CSS rules
+    """
+    return render_template("svg/styles.css", emoji_mode=emoji_mode)
+
+
+def render_title(
+    title: str,
+    width: float,
+    text_align: Literal["left", "center", "right"] = "left",
+    *,
+    level: int = 1,
+    prose: bool = False,
+    resolved_style: "MergedStyle | None" = None,
+) -> str:
+    """Render face title using mdsvg for proper text handling.
+
+    Font size is determined by card pixel width (width-based tier).
+    When ``prose=True`` the title uses the serif family (Source Serif 4)
+    regardless of width, matching the prose body text.
+
+    Args:
+        title: Title text to render
+        width: Available width (drives tier selection: narrow/medium/wide)
+        text_align: Text alignment ("left", "center", "right")
+        prose: When True, render in serif to match prose body text.
+
+    Returns:
+        SVG string for the title
+    """
+    from dataface.core.compile.config import get_config
+    from dataface.core.compile.models.style.merged import resolve_style
+    from dataface.core.compile.sizing import get_compact_style
+    from dataface.core.compile.typography import face_title_markdown
+    from dataface.core.fonts import get_inter_font_path
+    from mdsvg import render as render_markdown
+
+    markdown_title, h1_size, heading_weight = face_title_markdown(
+        title, width, level=level
+    )
+
+    if prose:
+        assert resolved_style is not None
+        font_family = str(resolved_style.title.font.family)
+    else:
+        font_family = None
+    _ms = (
+        resolved_style
+        if resolved_style is not None
+        else resolve_style(get_config().style)
+    )
+    style = get_compact_style(
+        _ms,
+        text_align=text_align,
+        h1_size=h1_size,
+        heading_font_weight=heading_weight,
+        font_family=font_family,
+    )
+    font_path = str(get_inter_font_path())
+    return render_markdown(
+        markdown_title,
+        width=width,
+        padding=0.0,
+        style=style,
+        font_path=font_path,
+    )