dataface 0.1.2__py3-none-any.whl

dataface/core/compile/custom_chart_types.py

@@ -0,0 +1,208 @@
+"""Custom chart type definitions and registry.
+
+Enables users to extend Dataface with project-local chart types by placing
+YAML definitions in a ``chart_types/`` directory.  Each definition names an
+underlying Vega-Lite mark, optional field requirements, and encoding
+overrides that the render pipeline applies automatically.
+
+A custom chart type is a "chart type preset": a named combination of mark,
+encoding rules, and style defaults that routes through the standard
+Vega-Lite rendering path.
+
+Example ``chart_types/funnel.yml``::
+
+    name: funnel
+    description: Funnel chart for conversion visualization
+    mark: bar
+    fields:
+      stage:
+        required: true
+        description: Stage field
+      value:
+        required: true
+        description: Value field
+    encoding_overrides:
+      y:
+        type: nominal
+        sort: null
+      x:
+        type: quantitative
+
+Safety boundaries:
+- Custom types cannot shadow built-in chart types.
+- Mark must be a valid Vega-Lite mark type.
+- Names must be valid Python identifiers (no spaces, no special chars).
+- YAML definitions reject unknown keys (no silent typo swallowing).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, get_args
+
+import yaml
+
+from dataface.core.compile.models.chart.authored import ChartType
+from dataface.core.compile.models.vega_lite.contracts import Mark
+
+# Valid Vega-Lite mark types that custom chart types may use.
+# Derived from the canonical Mark Literal in vega_lite/contracts.py.
+VALID_VL_MARKS: frozenset[str] = frozenset(get_args(Mark))
+
+# Built-in chart type values — single source of truth for both the
+# registry (shadowing check) and the normalizer (unknown-type rejection).
+BUILTIN_CHART_TYPE_VALUES = frozenset(ct.value for ct in ChartType)
+
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+# Known top-level keys in a custom chart type YAML definition.
+_KNOWN_YAML_KEYS = frozenset(
+    {
+        "name",
+        "description",
+        "mark",
+        "fields",
+        "encoding_overrides",
+        "mark_properties",
+    }
+)
+
+
+def _validate_name(name: str, context: str = "") -> None:
+    """Validate a custom chart type name."""
+    if not _NAME_RE.match(name):
+        raise ValueError(
+            f"Custom chart type name {name!r}{context} must be a valid identifier "
+            f"(lowercase letters, digits, underscores; must start with a letter)"
+        )
+
+
+def _validate_mark(mark: str, name: str, context: str = "") -> None:
+    """Validate a Vega-Lite mark type."""
+    if mark not in VALID_VL_MARKS:
+        raise ValueError(
+            f"Custom chart type {name!r}{context} has invalid Vega-Lite mark "
+            f"{mark!r}; must be one of {sorted(VALID_VL_MARKS)}"
+        )
+
+
+@dataclass(frozen=True)
+class FieldDef:
+    """Schema for a single field expected by a custom chart type."""
+
+    required: bool = False
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class CustomChartTypeDef:
+    """Definition of a custom chart type.
+
+    Attributes:
+        name: Unique identifier (valid Python identifier, lowercase).
+        description: Human-readable description for docs and AI prompts.
+        mark: Underlying Vega-Lite mark type (bar, point, arc, etc.).
+        fields: Expected field mappings with requirements.
+        encoding_overrides: Per-channel Vega-Lite encoding properties
+            applied on top of the standard profile mapping.
+        mark_properties: Extra properties merged into the mark dict.
+    """
+
+    name: str
+    description: str
+    mark: str
+    fields: dict[str, FieldDef] = field(default_factory=dict)
+    encoding_overrides: dict[str, Any] = field(default_factory=dict)
+    mark_properties: dict[str, Any] = field(default_factory=dict)
+
+
+class CustomChartTypeRegistry:
+    """Registry of project-local custom chart types."""
+
+    def __init__(self) -> None:
+        self._types: dict[str, CustomChartTypeDef] = {}
+
+    def register(self, defn: CustomChartTypeDef) -> None:
+        """Register a custom chart type definition.
+
+        Raises ValueError if the name shadows a built-in, is already
+        registered, uses an invalid mark, or has an invalid name.
+        """
+        _validate_name(defn.name)
+        if defn.name in BUILTIN_CHART_TYPE_VALUES:
+            raise ValueError(
+                f"Custom chart type {defn.name!r} shadows built-in chart type"
+            )
+        if defn.name in self._types:
+            raise ValueError(f"Custom chart type {defn.name!r} already registered")
+        _validate_mark(defn.mark, defn.name)
+        self._types[defn.name] = defn
+
+    def get(self, name: str) -> CustomChartTypeDef | None:
+        return self._types.get(name)
+
+    def is_registered(self, name: str) -> bool:
+        return name in self._types
+
+    def registered_names(self) -> set[str]:
+        return set(self._types)
+
+    def load_from_directory(self, path: Path) -> None:
+        """Load all YAML chart type definitions from a directory."""
+        if not path.is_dir():
+            return
+        for yaml_file in sorted(path.glob("*.yml")):
+            defn = load_custom_chart_type(yaml_file)
+            self.register(defn)
+        for yaml_file in sorted(path.glob("*.yaml")):
+            defn = load_custom_chart_type(yaml_file)
+            self.register(defn)
+
+
+def load_custom_chart_type(path: Path) -> CustomChartTypeDef:
+    """Load a custom chart type definition from a YAML file.
+
+    Validates name, mark, and rejects unknown keys immediately so
+    typos are caught at load time, not silently ignored.
+    """
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"Custom chart type file {path} must be a YAML mapping")
+    if "name" not in raw:
+        raise ValueError(f"Custom chart type file {path} missing required field: name")
+    if "mark" not in raw:
+        raise ValueError(f"Custom chart type file {path} missing required field: mark")
+
+    # Reject unknown keys — catch typos like "mark_properites" early.
+    unknown = set(raw) - _KNOWN_YAML_KEYS
+    if unknown:
+        raise ValueError(
+            f"Custom chart type file {path} has unknown keys: {sorted(unknown)}. "
+            f"Valid keys: {sorted(_KNOWN_YAML_KEYS)}"
+        )
+
+    # Validate name and mark at load time (not just at registration).
+    context = f" in {path}"
+    _validate_name(raw["name"], context)
+    _validate_mark(raw["mark"], raw["name"], context)
+
+    fields: dict[str, FieldDef] = {}
+    for field_name, field_raw in (raw.get("fields") or {}).items():
+        if isinstance(field_raw, dict):
+            fields[field_name] = FieldDef(
+                required=field_raw.get("required", False),
+                description=field_raw.get("description", ""),
+            )
+        else:
+            fields[field_name] = FieldDef()
+
+    return CustomChartTypeDef(
+        name=raw["name"],
+        description=raw.get("description", ""),
+        mark=raw["mark"],
+        fields=fields,
+        encoding_overrides=raw.get("encoding_overrides") or {},
+        mark_properties=raw.get("mark_properties") or {},
+    )