dataface 0.1.2__py3-none-any.whl

dataface/integrations/markdown.py

@@ -0,0 +1,537 @@
+"""Superfences handlers for embedding Dataface boards in markdown.
+
+Two handlers for use with ``pymdownx.superfences`` custom fences:
+
+- ``fence_dataface`` — render-only: YAML in, SVG/HTML out.
+- ``fence_dataface_example`` — code + render: syntax-highlighted YAML
+  alongside rendered output, with playground links.
+
+Register in ``mkdocs.yml``::
+
+    markdown_extensions:
+      - pymdownx.superfences:
+          custom_fences:
+            - name: dataface
+              class: dataface
+              format: !!python/name:dataface.integrations.markdown.fence_dataface
+            - name: dataface-example
+              class: dataface-example
+              format: !!python/name:dataface.integrations.markdown.fence_dataface_example
+
+Then in any ``.md`` page::
+
+    ```dataface
+    charts:
+      revenue:
+        type: bar
+        x: product
+        y: revenue
+    ```
+
+    ```dataface-example {file=charts/examples/bar-charts/minimum.yml}
+    ```
+"""
+
+from __future__ import annotations
+
+import base64
+import functools
+import hashlib
+import html
+import logging
+import os
+import re
+import zlib
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from dataface.core.render.errors import RenderError
+from dataface.core.render.face_api import compile_and_render, render_face
+from dataface.integrations.highlighting import highlight_face_yaml
+
+logger = logging.getLogger("dataface.integrations.markdown")
+
+_PLAYGROUND_DEFAULT_URL = "https://play.dataface.com"
+_VALID_LAYOUTS = {"side-by-side", "stacked", "render-only", "yaml-only"}
+_EXTERNAL_QUERY_NOT_FOUND_RE = re.compile(r"External query file not found", re.I)
+
+_PROJECT_DIR_OVERRIDE: ContextVar[Path | None] = ContextVar(
+    "dataface_markdown_project_dir", default=None
+)
+
+
+@contextmanager
+def project_dir_override(path: Path) -> Iterator[None]:
+    """Pin fence rendering to *path* instead of walking up from ``cwd``."""
+    token = _PROJECT_DIR_OVERRIDE.set(path.resolve())
+    try:
+        yield
+    finally:
+        _PROJECT_DIR_OVERRIDE.reset(token)
+
+
+@functools.cache
+def _cached_project_dir_from_cwd() -> Path:
+    """Walk up from ``cwd`` for a ``pyproject.toml`` or ``dbt_project.yml``."""
+    cwd = Path.cwd().resolve()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / "pyproject.toml").exists() or (
+            parent / "dbt_project.yml"
+        ).exists():
+            return parent
+    raise RuntimeError(
+        "Cannot resolve project root: no pyproject.toml or dbt_project.yml "
+        "found above cwd"
+    )
+
+
+def _resolve_project_dir() -> Path:
+    """Resolve the project root for markdown fence rendering."""
+    override = _PROJECT_DIR_OVERRIDE.get()
+    if override is not None:
+        return override
+    return _cached_project_dir_from_cwd()
+
+
+def _highlight_yaml(source: str) -> str:
+    """Syntax-highlight Dataface face YAML using DatafaceYamlLexer.
+
+    SQL inside ``sql: |`` and ``query: |`` block scalars is delegated to
+    SqlLexer so SQL keywords receive keyword styling.
+
+    Returns HTML wrapped in ``<div class="yaml"><pre><code>...</code></pre></div>``.
+    """
+    highlighted = highlight_face_yaml(source)
+    return (
+        f'<div class="yaml"><pre><code class="language-yaml">'
+        f"{highlighted}</code></pre></div>"
+    )
+
+
+def _playground_url(
+    yaml_source: str,
+    base_url: str | None = None,
+) -> str:
+    """Generate a playground URL with compressed YAML payload."""
+    resolved_base_url = base_url or os.getenv(
+        "DFT_PLAYGROUND_URL", _PLAYGROUND_DEFAULT_URL
+    )
+    compressed = zlib.compress(yaml_source.encode("utf-8"), level=9)
+    encoded = base64.urlsafe_b64encode(compressed).decode("ascii").rstrip("=")
+    return f"{resolved_base_url}/?y={encoded}"
+
+
+def _resolve_file(file_path: str, project_dir: Path) -> Path:
+    """Resolve a file= path against project_dir with traversal guard."""
+    resolved = (project_dir / file_path).resolve()
+    if not resolved.is_relative_to(project_dir.resolve()):
+        raise ValueError(f"Path escapes project directory: {file_path}")
+    if not resolved.exists():
+        raise FileNotFoundError(f"File not found: {resolved}")
+    return resolved
+
+
+def _fence_options(
+    options: dict[str, Any],
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    """Merge legacy ``options`` with SuperFences attr-list kwargs."""
+    merged = dict(options)
+    attrs = kwargs.get("attrs") or {}
+    for key, value in attrs.items():
+        merged.setdefault(key, value)
+    return merged
+
+
+def _shared_examples_dir(project_dir: Path) -> Path | None:
+    """Return ``examples/`` when it ships the shared ``_sources.yaml`` project root."""
+    examples_dir = project_dir / "examples"
+    if examples_dir.is_dir() and (examples_dir / "_sources.yaml").is_file():
+        return examples_dir
+    return None
+
+
+def _inline_render_contexts(project_dir: Path) -> list[tuple[Path, Path]]:
+    """Return candidate ``(project_root, base_dir)`` contexts for inline YAML."""
+    examples_dir = _shared_examples_dir(project_dir)
+    if examples_dir is not None:
+        # Docs inline examples resolve shared queries and named sources from here.
+        return [(examples_dir, examples_dir), (project_dir, project_dir)]
+    candidates: list[tuple[Path, Path]] = [(project_dir, project_dir)]
+    fallback = project_dir / "examples"
+    if fallback.is_dir():
+        candidates.append((fallback, fallback))
+    return candidates
+
+
+def _file_render_contexts(
+    face_path: Path, project_dir: Path
+) -> list[tuple[Path, Path]]:
+    """Return candidate ``(project_root, base_dir)`` contexts for file-backed YAML."""
+    file_ctx = (project_dir, face_path.parent)
+    examples_dir = _shared_examples_dir(project_dir)
+    if examples_dir is not None:
+        return [(examples_dir, examples_dir), file_ctx]
+    candidates: list[tuple[Path, Path]] = [file_ctx]
+    fallback = project_dir / "examples"
+    if fallback.is_dir():
+        candidates.append((fallback, fallback))
+    return candidates
+
+
+_SOURCE_NOT_FOUND_RE = re.compile(
+    r"Source .+ not found|No source profiles are configured",
+    re.I,
+)
+
+
+def _should_retry_with_examples(exc: Exception, current_project_dir: Path) -> bool:
+    """Retry against ``examples/`` for shared docs fixtures the repo root lacks."""
+    if current_project_dir.name == "examples":
+        return False
+    message = str(exc)
+    return bool(
+        _EXTERNAL_QUERY_NOT_FOUND_RE.search(message)
+        or _SOURCE_NOT_FOUND_RE.search(message)
+    )
+
+
+def _render_inline_with_fallback(yaml_source: str, project_dir: Path) -> str:
+    """Render inline YAML, retrying against ``examples/`` when docs shared queries need it."""
+    last_exc: Exception | None = None
+    for candidate_project_dir, candidate_base_dir in _inline_render_contexts(
+        project_dir
+    ):
+        try:
+            result = compile_and_render(
+                yaml_source,
+                project_root=candidate_project_dir,
+                dbt_project_path=None,
+                base_dir=candidate_base_dir,
+                format="svg",
+            )
+            return cast(str, result)
+        except (FileNotFoundError, ValueError, OSError, RenderError) as exc:
+            last_exc = exc
+            if not _should_retry_with_examples(exc, candidate_project_dir):
+                raise
+    assert last_exc is not None
+    raise last_exc
+
+
+def _render_file_with_fallback(face_path: Path, project_dir: Path) -> str:
+    """Render a face file, retrying against ``examples/`` when docs shared queries need it."""
+    last_exc: Exception | None = None
+    for candidate_project_dir, candidate_base_dir in _file_render_contexts(
+        face_path, project_dir
+    ):
+        try:
+            result = render_face(
+                face_path,
+                format="svg",
+                project_dir=candidate_project_dir,
+                base_dir=candidate_base_dir,
+            )
+            return cast(str, result)
+        except (FileNotFoundError, ValueError, OSError, RenderError) as exc:
+            last_exc = exc
+            if not _should_retry_with_examples(exc, candidate_project_dir):
+                raise
+    assert last_exc is not None
+    raise last_exc
+
+
+def _candidate_external_bases(
+    project_dir: Path,
+    source_base_dir: Path | None,
+) -> list[Path]:
+    """Return candidate base dirs for resolving external query references."""
+    candidates: list[Path] = []
+    for candidate in (
+        source_base_dir,
+        project_dir,
+        project_dir / "examples",
+    ):
+        if candidate is None:
+            continue
+        resolved = candidate.resolve()
+        if resolved not in candidates:
+            candidates.append(resolved)
+    return candidates
+
+
+def _load_external_query_definition(
+    query_ref: str,
+    project_dir: Path,
+    source_base_dir: Path | None,
+) -> tuple[str, Any]:
+    """Load a raw external query definition for playground-link inlining."""
+    file_part, query_name = query_ref.split("#", 1)
+
+    for candidate_base in _candidate_external_bases(project_dir, source_base_dir):
+        candidate_file = (candidate_base / file_part).resolve()
+        if not candidate_file.exists():
+            continue
+
+        raw = yaml.safe_load(candidate_file.read_text(encoding="utf-8")) or {}
+        queries = raw.get("queries", {}) if isinstance(raw, dict) else {}
+        if query_name in queries:
+            return query_name, queries[query_name]
+        raise ValueError(
+            f"Query '{query_name}' not found in '{candidate_file}'. "
+            f"Available queries: {', '.join(sorted(queries)) if queries else 'none'}"
+        )
+
+    raise FileNotFoundError(
+        f"External query file not found for playground link: {file_part}"
+    )
+
+
+def _inline_playground_queries(
+    yaml_source: str,
+    project_dir: Path,
+    source_base_dir: Path | None,
+) -> str:
+    """Rewrite external query refs into local inline queries for playground URLs."""
+    doc = yaml.safe_load(yaml_source)
+    if not isinstance(doc, dict):
+        return yaml_source
+
+    query_defs = doc.get("queries")
+    if query_defs is None:
+        query_defs = {}
+        doc["queries"] = query_defs
+    if not isinstance(query_defs, dict):
+        return yaml_source
+
+    inlined_any = False
+
+    def visit(node: Any) -> None:
+        nonlocal inlined_any
+        if isinstance(node, dict):
+            query_ref = node.get("query")
+            if isinstance(query_ref, str) and "#" in query_ref:
+                query_name, query_def = _load_external_query_definition(
+                    query_ref,
+                    project_dir,
+                    source_base_dir,
+                )
+                existing = query_defs.get(query_name)
+                if existing is None:
+                    query_defs[query_name] = query_def
+                elif existing != query_def:
+                    suffix = 2
+                    rewritten_name = f"{query_name}_{suffix}"
+                    while (
+                        rewritten_name in query_defs
+                        and query_defs[rewritten_name] != query_def
+                    ):
+                        suffix += 1
+                        rewritten_name = f"{query_name}_{suffix}"
+                    query_defs.setdefault(rewritten_name, query_def)
+                    query_name = rewritten_name
+                node["query"] = query_name
+                inlined_any = True
+
+            for value in node.values():
+                visit(value)
+        elif isinstance(node, list):
+            for item in node:
+                visit(item)
+
+    visit(doc)
+    if not inlined_any:
+        return yaml_source
+    return yaml.safe_dump(doc, sort_keys=False)
+
+
+def _pg_link(pg_url: str, extra_class: str = "") -> str:
+    """Generate a playground link anchor tag."""
+    cls = f"playground-link {extra_class}".strip()
+    return (
+        f'<a href="{pg_url}" target="_blank" class="{cls}" '
+        f'rel="noopener noreferrer" title="Try in Playground">'
+        f'<span class="playground-icon">\u25b6</span></a>'
+    )
+
+
+def _error_div(message: str) -> str:
+    escaped = html.escape(message)
+    return (
+        f'<div class="dataface-error">'
+        f"<strong>Dataface render error:</strong> {escaped}</div>"
+    )
+
+
+# ---------------------------------------------------------------------------
+# fence_dataface — render-only
+# ---------------------------------------------------------------------------
+
+
+def fence_dataface(
+    source: str,
+    language: str,
+    class_name: str,
+    options: dict[str, Any],
+    md: Any,
+    **kwargs: Any,
+) -> str:
+    """Superfences handler: render YAML to embedded SVG/HTML.
+
+    Usage::
+
+        ```dataface
+        charts:
+          c1:
+            type: bar
+            x: product
+            y: revenue
+        ```
+
+        ```dataface {file=path/to/face.yml}
+        ```
+    """
+    try:
+        project_dir = _resolve_project_dir()
+    except RuntimeError as exc:
+        return _error_div(str(exc))
+
+    resolved_options = _fence_options(options, kwargs)
+    file_opt = resolved_options.get("file")
+    try:
+        if file_opt:
+            resolved = _resolve_file(file_opt, project_dir)
+            rendered = _render_file_with_fallback(resolved, project_dir)
+        else:
+            yaml_source = source.strip()
+            if not yaml_source:
+                return _error_div(
+                    "no YAML source provided (use inline content or file= option)"
+                )
+            rendered = _render_inline_with_fallback(yaml_source, project_dir)
+        return f'<div class="dataface-embed">{rendered}</div>'
+    except (FileNotFoundError, ValueError, OSError, RenderError) as exc:
+        logger.warning("Dataface render failed: %s", exc)
+        return _error_div(str(exc))
+
+
+# ---------------------------------------------------------------------------
+# fence_dataface_example — code + render
+# ---------------------------------------------------------------------------
+
+
+def fence_dataface_example(
+    source: str,
+    language: str,
+    class_name: str,
+    options: dict[str, Any],
+    md: Any,
+    **kwargs: Any,
+) -> str:
+    """Superfences handler: code-plus-render example layout.
+
+    Options (via ``{key=value}`` in the info string):
+
+    - ``file=path`` — read YAML from a file instead of inline
+    - ``format=side-by-side`` (default), ``stacked``, ``render-only``, ``yaml-only``
+
+    Usage::
+
+        ```dataface-example {file=charts/examples/bar-charts/minimum.yml}
+        ```
+
+        ```dataface-example {format=stacked}
+        charts:
+          c1:
+            type: bar
+        ```
+    """
+    try:
+        project_dir = _resolve_project_dir()
+    except RuntimeError as exc:
+        return _error_div(str(exc))
+
+    resolved_options = _fence_options(options, kwargs)
+    layout = resolved_options.get("format", "side-by-side")
+    if layout not in _VALID_LAYOUTS:
+        return _error_div(
+            f"unknown format {layout!r}, expected one of: "
+            f"{', '.join(sorted(_VALID_LAYOUTS))}"
+        )
+
+    # Resolve source: file or inline
+    file_opt = resolved_options.get("file")
+    resolved_path: Path | None = None
+    if file_opt:
+        try:
+            resolved_path = _resolve_file(file_opt, project_dir)
+            yaml_source = resolved_path.read_text(encoding="utf-8").strip()
+        except (FileNotFoundError, ValueError, OSError) as exc:
+            return _error_div(str(exc))
+    else:
+        yaml_source = source.strip()
+
+    if not yaml_source:
+        return _error_div("no YAML source provided")
+
+    example_id = hashlib.md5(yaml_source.encode(), usedforsecurity=False).hexdigest()[
+        :12
+    ]
+    playground_yaml = yaml_source
+    try:
+        playground_yaml = _inline_playground_queries(
+            yaml_source,
+            project_dir,
+            resolved_path.parent if resolved_path else project_dir,
+        )
+    except (FileNotFoundError, ValueError, OSError, yaml.YAMLError) as exc:
+        logger.warning("Playground payload rewrite failed: %s", exc)
+    pg_url = _playground_url(playground_yaml)
+
+    # yaml-only: no rendering
+    if layout == "yaml-only":
+        highlighted = _highlight_yaml(yaml_source)
+        return (
+            f'<div class="example-container example-yaml-only" '
+            f'id="example-container-{example_id}">\n'
+            f'<div class="example-code">\n{highlighted}\n'
+            f"{_pg_link(pg_url, 'playground-link-inline')}\n"
+            f"</div>\n</div>"
+        )
+
+    # Render the face
+    rendered_html: str
+    try:
+        if resolved_path:
+            rendered = _render_file_with_fallback(resolved_path, project_dir)
+        else:
+            rendered = _render_inline_with_fallback(yaml_source, project_dir)
+        rendered_html = f'<div class="rendered-dashboard">{rendered}</div>'
+    except (FileNotFoundError, ValueError, OSError, RenderError) as exc:
+        logger.warning("Dataface render failed: %s", exc)
+        rendered_html = _error_div(str(exc))
+
+    # render-only: no code panel
+    if layout == "render-only":
+        return (
+            f'<div class="example-container example-render-only" '
+            f'id="example-container-{example_id}">\n'
+            f'<div class="example-render" id="example-render-{example_id}">\n'
+            f"{rendered_html}\n{_pg_link(pg_url)}\n</div>\n</div>"
+        )
+
+    # side-by-side (default) or stacked
+    highlighted = _highlight_yaml(yaml_source)
+    layout_class = " example-stacked" if layout == "stacked" else ""
+    return (
+        f'<div class="example-container{layout_class}" '
+        f'id="example-container-{example_id}">\n'
+        f'<div class="example-code">\n{highlighted}\n</div>\n'
+        f'<div class="example-render" id="example-render-{example_id}">\n'
+        f"{rendered_html}\n{_pg_link(pg_url)}\n</div>\n</div>"
+    )