dataface 0.1.2__py3-none-any.whl

dataface/core/render/converters/pdf.py

@@ -0,0 +1,40 @@
+"""PDF format conversion.
+
+Stage: RENDER
+Purpose: Convert SVG output to PDF using vl-convert.
+"""
+
+from dataface.core.render.errors import FormatError
+from dataface.core.render.font_support import (
+    normalize_svg_font_families_for_vl_convert,
+    register_vl_convert_fonts,
+)
+
+
+def to_pdf(svg_content: str) -> bytes:
+    """Convert SVG to PDF using vl-convert.
+
+    Args:
+        svg_content: SVG string to convert
+
+    Returns:
+        PDF document as bytes
+
+    Raises:
+        FormatError: If conversion fails or dependencies missing
+    """
+    try:
+        import vl_convert as vlc
+
+        register_vl_convert_fonts(vlc)
+        normalized_svg = normalize_svg_font_families_for_vl_convert(svg_content)
+        return vlc.svg_to_pdf(normalized_svg)
+    except ImportError:
+        raise FormatError(
+            "PDF export requires vl-convert-python: pip install vl-convert-python",
+            "pdf",
+        ) from None
+    except FormatError:
+        raise
+    except Exception as e:
+        raise FormatError(f"PDF conversion failed: {e}", "pdf") from e

dataface/core/render/converters/png.py

@@ -0,0 +1,41 @@
+"""PNG format conversion.
+
+Stage: RENDER
+Purpose: Convert SVG output to PNG using vl-convert.
+"""
+
+from dataface.core.render.errors import FormatError
+from dataface.core.render.font_support import (
+    normalize_svg_font_families_for_vl_convert,
+    register_vl_convert_fonts,
+)
+
+
+def to_png(svg_content: str, scale: float = 1.0) -> bytes:
+    """Convert SVG to PNG using vl-convert.
+
+    Args:
+        svg_content: SVG string to convert
+        scale: Scale factor for the output image
+
+    Returns:
+        PNG image as bytes
+
+    Raises:
+        FormatError: If conversion fails or dependencies missing
+    """
+    try:
+        import vl_convert as vlc
+
+        register_vl_convert_fonts(vlc)
+        normalized_svg = normalize_svg_font_families_for_vl_convert(svg_content)
+        return vlc.svg_to_png(normalized_svg, scale=scale)
+    except ImportError:
+        raise FormatError(
+            "PNG export requires vl-convert-python: pip install vl-convert-python",
+            "png",
+        ) from None
+    except FormatError:
+        raise
+    except Exception as e:
+        raise FormatError(f"PNG conversion failed: {e}", "png") from e

dataface/core/render/errors.py

@@ -0,0 +1,144 @@
+"""Rendering error types.
+
+Stage: RENDER
+Purpose: Define error types for rendering failures.
+
+These errors are raised during:
+- General rendering failures (RenderError)
+- Format conversion (FormatError)
+- Pre-render required-variable validation (MissingRequiredVariablesError)
+
+All errors inherit from RenderError → DatafaceError for easy catching.
+
+Note: Many render errors are displayed IN the output rather than thrown,
+so users see helpful error messages in the rendered dataface.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from dataface.core.compile.errors import DatafaceError
+
+
+class RenderError(DatafaceError):
+    """Base error for all rendering failures.
+
+    This is the parent class for all rendering-related errors.
+    Catch this to handle any rendering error.
+
+    Attributes:
+        message: Human-readable error description
+        element: Element that failed to render (if applicable)
+    """
+
+    # Class-level None default so `from_code`-constructed instances (which
+    # bypass __init__) still satisfy `e.element` access.
+    element: str | None = None
+
+    def __init__(self, message: str, element: str | None = None):
+        self.message = message
+        self.element = element
+        self.fields: dict[str, Any] = {}
+        super().__init__(self._format_message())
+        if self.code is None:
+            from dataface.core.errors.codes_unknown import DF_UNKNOWN_INTERNAL
+
+            self.code = DF_UNKNOWN_INTERNAL
+
+    def _format_message(self) -> str:
+        """Format error message with optional element."""
+        if self.element:
+            return f"{self.message} (element: {self.element})"
+        return self.message
+
+
+class ChartDataError(RenderError):
+    """Chart received data that doesn't match its requirements.
+
+    Raised when:
+    - KPI chart receives more than 1 row
+    - Chart references a column not present in the data
+    - Data shape doesn't match chart type expectations
+    """
+
+    chart_id: str | None = None
+
+    def __init__(self, message: str, chart_id: str | None = None):
+        self.chart_id = chart_id
+        super().__init__(message, chart_id)
+
+
+class UnknownChartType(RenderError):
+    """Render dispatch received a chart type not in the known registry.
+
+    Raised by both the top-level dispatch and the mark-lookup layer so
+    the caller sees a structured error rather than a bare ValueError.
+    """
+
+    chart_type: str | None = None
+
+    def __init__(self, chart_type: str):
+        self.chart_type = chart_type
+        super().__init__(f"Unknown chart type: {chart_type!r}", chart_type)
+
+
+class FormatError(RenderError):
+    """Error during format conversion.
+
+    Raised when:
+    - Unknown format requested
+    - SVG to PNG/PDF conversion fails
+    - HTML template error
+
+    Example:
+        >>> try:
+        ...     render(face, executor, format="unknown")
+        ... except FormatError as e:
+        ...     print(f"Format error: {e}")
+    """
+
+    format: str | None = None
+
+    def __init__(self, message: str, format: str | None = None):
+        self.format = format
+        super().__init__(f"Format conversion failed: {message}", format)
+
+
+@dataclass
+class MissingVariable:
+    """Metadata for a single required variable that was not provided at render time."""
+
+    key: str
+    label: str | None
+    description: str | None
+    input_type: str | None
+
+
+class MissingRequiredVariablesError(RenderError):
+    """Raised before any query executes when required variables have no value.
+
+    Carries a structured list so callers can render a blocking prompt
+    without parsing the error message. Inherits from ``RenderError`` so
+    existing ``except RenderError`` handlers (markdown integration, activity
+    dashboards, etc.) degrade to a string error block; surfaces that need
+    the structured ``missing`` list catch it explicitly first.
+    """
+
+    def __init__(self, missing: list[MissingVariable]) -> None:
+        self.missing = missing
+        descriptions = ", ".join(
+            f"{mv.key} ({mv.label})" if mv.label else mv.key for mv in missing
+        )
+        super().__init__(f"Missing required variables: {descriptions}")
+        # Populate fields so to_structured() carries per-variable metadata.
+        self.fields = {
+            "missing": [
+                {
+                    "key": mv.key,
+                    "label": mv.label,
+                    "description": mv.description,
+                    "input_type": mv.input_type,
+                }
+                for mv in missing
+            ]
+        }

dataface/core/render/face_api.py

@@ -0,0 +1,160 @@
+"""Face rendering API for external integrations.
+
+Exposes ``render_face`` (file-oriented public API) and
+``compile_and_render`` (shared compile → execute → render pipeline).
+
+External integrations should use ``render_face``.  The CLI uses
+``compile_and_render`` directly for stdin input where no file is involved.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from dataface.core.compile import compile
+from dataface.core.compile.markdown import is_markdown_face, markdown_to_yaml
+from dataface.core.execute import Executor
+from dataface.core.execute.adapters import build_adapter_registry
+from dataface.core.execute.duckdb_cache import open_cache_from_env
+from dataface.core.project_roots import (
+    discover_render_context,
+    discovery_boundary_for_face,
+)
+from dataface.core.render.renderer import render
+
+
+def compile_and_render(
+    yaml_content: str,
+    project_root: Path,
+    dbt_project_path: Path | None,
+    base_dir: Path | None = None,
+    format: str = "svg",
+    variables: dict[str, str] | None = None,
+    use_cache: bool = True,
+    **options: Any,
+) -> str | bytes:
+    """Compile YAML, build an executor, and render.
+
+    This is the shared pipeline that both ``render_face`` and the CLI
+    ``render_command`` call.  External integrations should prefer
+    ``render_face`` which adds file I/O and project discovery on top.
+
+    Raises:
+        ValueError: On compilation errors.
+        RenderError: On rendering or format conversion failures.
+    """
+    result = compile(
+        yaml_content,
+        base_dir=base_dir or project_root,
+        project_dir=project_root,
+    )
+    if result.errors:
+        errors_str = "\n  ".join(e.message for e in result.errors)
+        raise ValueError(f"Compilation errors:\n  {errors_str}")
+    if not result.face:
+        raise ValueError("Compilation produced no face")
+
+    adapter_registry = build_adapter_registry(
+        project_root,
+        read_only=True,
+        dbt_project_path=dbt_project_path,
+    )
+    cache = open_cache_from_env()
+    try:
+        executor = Executor(
+            result.face,
+            adapter_registry=adapter_registry,
+            query_registry=result.query_registry,
+            use_cache=use_cache,
+            duckdb_cache=cache,
+        )
+
+        output = render(
+            result.face,
+            executor,
+            format=format,
+            variables=variables or {},
+            **options,
+        ).output
+        if output is None:
+            raise ValueError("Render produced no output")
+        return output
+    finally:
+        adapter_registry.close()
+        if cache is not None:
+            cache.close()
+
+
+def render_face(
+    face_path: str | Path,
+    format: str = "svg",
+    project_dir: str | Path | None = None,
+    base_dir: str | Path | None = None,
+    variables: dict[str, str] | None = None,
+    use_cache: bool = True,
+    **options: Any,
+) -> str | bytes:
+    """Render a Dataface face file to an embeddable output.
+
+    This is the public API that external integrations (MkDocs plugin,
+    Sphinx directive, etc.) should call.  It handles the full
+    compile → execute → render pipeline and returns the rendered output.
+
+    Args:
+        face_path: Path to a ``.yml`` or ``.md`` face file.
+        format: Output format — ``"svg"`` (default), ``"html"``, ``"png"``, ``"pdf"``.
+        project_dir: Override project root for resolving project-level data paths.
+            When ``None``, discovery walks up from the face file.
+        base_dir: Override the base directory for resolving relative file references
+            inside the face content. Defaults to the face file's parent directory.
+        variables: Variable values to pass into the render.
+        use_cache: Whether to use cached query results. False bypasses all caches.
+        **options: Passed through to the renderer (e.g. ``background``, ``scale``).
+
+    Returns:
+        Rendered content — ``str`` for svg/html, ``bytes`` for png/pdf.
+
+    Raises:
+        FileNotFoundError: If *face_path* does not exist.
+        ValueError: On compilation errors.
+        RenderError: On chart data or rendering failures.
+    """
+    face_file = Path(face_path).resolve()
+    if not face_file.exists():
+        raise FileNotFoundError(f"Face file not found: {face_file}")
+
+    # Read and optionally transform markdown → YAML
+    raw = face_file.read_text(encoding="utf-8")
+    if face_file.suffix.lower() == ".md":
+        if not is_markdown_face(face_file):
+            raise ValueError(
+                "Not a Dataface face file: .md files require YAML frontmatter "
+                "with at least one of: queries, charts, variables, source, sources"
+            )
+        yaml_content = markdown_to_yaml(raw)
+    else:
+        yaml_content = raw
+
+    # Discovery always runs to find dbt_project_path (needed for SQL adapter).
+    # When project_dir is explicitly set, we override project_root but keep
+    # the discovered dbt_project_path.
+    project_root, dbt_project_path = discover_render_context(
+        face_file.parent,
+        discovery_boundary_for_face(
+            face_file.parent,
+            str(project_dir) if project_dir else None,
+        ),
+    )
+    if project_dir:
+        project_root = Path(project_dir).resolve()
+    resolved_base_dir = Path(base_dir).resolve() if base_dir else face_file.parent
+
+    return compile_and_render(
+        yaml_content,
+        project_root=project_root,
+        dbt_project_path=dbt_project_path,
+        base_dir=resolved_base_dir,
+        format=format,
+        variables=variables,
+        use_cache=use_cache,
+        **options,
+    )