dataface 0.1.2__py3-none-any.whl

dataface/core/compile/vega_config.py

@@ -0,0 +1,98 @@
+"""Pure Vega-Lite config compilation — theme name → merged VL config dict.
+
+Stage: COMPILE (pure, no executor, no data access)
+Purpose: Resolve theme + style sheet into the concrete Vega-Lite config dict
+that resolve_face() bakes into MergedFace.vega_config.
+
+Moved from render/chart/presentation.py so that resolve_face.py (which sits at
+the compile/execute/render boundary) can import it without touching render/.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def _to_plain_dict(obj: object) -> Any:
+    """Recursively convert Pydantic models and nested objects to plain dicts.
+
+    Inlined from render/chart/presentation.py to avoid a compile→render import.
+    """
+    if isinstance(obj, BaseModel):
+        return obj.model_dump(by_alias=True, exclude_unset=True)
+    if isinstance(obj, dict):
+        return {k: _to_plain_dict(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_to_plain_dict(v) for v in obj]
+    return obj
+
+
+def _overlay_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge overlay into base, returning a new dict."""
+    merged: dict[str, Any] = dict(base)
+    for key, value in overlay.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _overlay_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def compile_effective_vega_config(theme: str | None = None) -> dict[str, Any]:
+    """Compile the merged Vega-Lite config from base defaults + unified theme.
+
+    Pure function — no executor, no data access, no side effects.
+    Same inputs always produce the same output.
+
+    Primary path: unified themes (themes/*.yaml) → Style → style_to_vega_lite().
+    Fallback path: user-defined themes in config.themes (old VL camelCase format)
+    are overlaid on top for backward compatibility.
+
+    Args:
+        theme: Theme name (e.g. "dark", "stark") or None for the configured default.
+
+    Returns:
+        Merged Vega-Lite config dict ready to embed in VL spec as ``config:``.
+    """
+    from dataface.core.compile.config import (
+        get_compiled_theme,
+        get_config,
+        get_default_theme_name,
+        get_theme_dict,
+    )
+    from dataface.core.compile.models.style.merged import (
+        resolve_style,
+        style_to_vega_lite,
+    )
+
+    result = copy.deepcopy(_to_plain_dict(get_config().vega.config))
+
+    # Resolve "default" alias to the configured default theme name so
+    # get_compiled_theme() can find it in themes/*.yaml.
+    resolved_theme = theme if theme and theme != "default" else get_default_theme_name()
+
+    try:
+        compiled = get_compiled_theme(resolved_theme)
+        resolved = resolve_style(compiled)
+        vl_config = _to_plain_dict(style_to_vega_lite(resolved.charts))
+        # Include the board-level background at the root of the VL config dict.
+        # Previously this came from chart_themes/*.yml (now deleted).
+        if compiled.background is not None and "background" not in vl_config:
+            vl_config["background"] = compiled.background
+        if vl_config:
+            result = _overlay_merge(result, vl_config)
+    except (ValueError, FileNotFoundError):
+        # Theme not found in unified themes dir — fall through to old-format overlay.
+        pass
+
+    effective_theme = (
+        theme if theme and theme != "default" else get_default_theme_name()
+    )
+    old_vl = get_theme_dict(effective_theme)
+    if old_vl:
+        result = _overlay_merge(result, old_vl)
+
+    return result

dataface/core/compile/vega_lite/__init__.py

@@ -0,0 +1,6 @@
+"""Vega-Lite schema version constant and validation utilities."""
+
+# Single source of truth for the Vega-Lite schema version Dataface targets.
+# Bumping this is a code change (model/contract updates may be required), so
+# it lives as a Python constant rather than authorable YAML.
+VEGA_LITE_SCHEMA_URL = "https://vega.github.io/schema/vega-lite/v6.4.2.json"

dataface/core/compile/vega_lite/validation.py

@@ -0,0 +1,95 @@
+"""Helpers for validating Vega-Lite contracts (projection input + emission boundary)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import TypeAdapter, ValidationError
+
+from dataface.core.compile.models.vega_lite.contracts import (
+    Projection,
+    TopLevelCompositeSpec,
+    TopLevelSpec,
+    TopLevelUnitSpec,
+)
+
+_PROJECTION_ADAPTER: TypeAdapter[Any] = TypeAdapter(Projection)
+_TOP_LEVEL_SPEC_ADAPTER: TypeAdapter[Any] = TypeAdapter(TopLevelSpec)
+
+
+def vl_field_name(field_name: str) -> str:
+    if field_name == "schema_":
+        return "$schema"
+    if field_name.endswith("_"):
+        return field_name[:-1]
+    return field_name
+
+
+SYSTEM_OWNED_TOP_LEVEL_SPEC_FIELDS = frozenset(
+    {
+        "$schema",
+        "data",
+        "mark",
+        "encoding",
+        "config",
+        "projection",
+        "transform",
+        "params",
+    }
+)
+TOP_LEVEL_SPEC_PASSTHROUGH_FIELDS = frozenset(
+    vl_field_name(field_name)
+    for field_name in (
+        set(TopLevelUnitSpec.model_fields) | set(TopLevelCompositeSpec.model_fields)
+    )
+    if vl_field_name(field_name) not in SYSTEM_OWNED_TOP_LEVEL_SPEC_FIELDS
+)
+
+
+def _validate_with_adapter(
+    value: Any,
+    adapter: TypeAdapter[Any],
+    field_name: str,
+) -> Any:
+    try:
+        validated = adapter.validate_python(value)
+    except ValidationError as exc:
+        raise ValueError(
+            f"{field_name} must conform to the Vega-Lite contract"
+        ) from exc
+    return validated
+
+
+def _validate_with_adapter_plain(
+    value: Any,
+    adapter: TypeAdapter[Any],
+    field_name: str,
+) -> Any:
+    """Validate and convert back to plain Python containers (for spec passthrough)."""
+    from dataface.core.render.chart.presentation import to_plain_dict
+
+    return to_plain_dict(
+        _validate_with_adapter(value, adapter=adapter, field_name=field_name)
+    )
+
+
+def validate_projection_definition(value: Any) -> str | Projection | None:
+    """Validate authored projection against the Projection contract."""
+    if value is None or isinstance(value, str):
+        return value
+    if isinstance(value, Projection):
+        return value
+    return _validate_with_adapter(
+        value, adapter=_PROJECTION_ADAPTER, field_name="projection"
+    )
+
+
+def validate_top_level_spec(value: dict[str, Any]) -> dict[str, Any]:
+    """Validate an emitted Vega-Lite spec against the top-level contract.
+
+    Returns a plain dict — this is the final emission boundary where the
+    spec must be a JSON-serializable dict for the Vega-Lite renderer.
+    """
+    return _validate_with_adapter_plain(
+        value, adapter=_TOP_LEVEL_SPEC_ADAPTER, field_name="spec"
+    )