dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/config.py

@@ -0,0 +1,347 @@
+"""Typed global config contract for compiled runtime defaults.
+
+This module mirrors the style-system pattern:
+
+- ``Config`` is the authoritative required runtime config object
+- ``ConfigPatch`` is the all-optional overlay shape used for authored/default YAML
+
+Dynamic sections such as ``themes`` remain open-ended, but
+they are backed by Pydantic mapping-like nodes that still support mapping access.
+"""
+
+from __future__ import annotations
+
+from collections.abc import ItemsView, Iterator, KeysView, Mapping, ValuesView
+from functools import cache
+from typing import Any
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    create_model,
+    model_validator,
+)
+
+from dataface.core.compile.models.primitives import FontStyle
+from dataface.core.compile.models.style.compiled import Style
+from dataface.core.compile.models.vega_lite.config import VegaLiteConfig
+from dataface.core.compile.vega_lite import VEGA_LITE_SCHEMA_URL
+
+
+def _normalize_node_value(value: object) -> object:
+    """Recursively normalize nested mapping values into ConfigNode objects."""
+    if isinstance(value, BaseModel):
+        return value
+    if isinstance(value, Mapping):
+        return ConfigNode.model_validate(dict(value))
+    if isinstance(value, list):
+        return [_normalize_node_value(item) for item in value]
+    return value
+
+
+class ConfigMappingBase(BaseModel, Mapping[str, Any]):
+    """Pydantic model with mapping-like helpers for config consumers."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Mapping access is a migration shim for dynamic config sections; cache the
+    # assembled top-level view and invalidate when this model's own fields change.
+    _mapping_cache: dict[str, Any] | None = PrivateAttr(default=None)
+
+    def _mapping_data(self) -> dict[str, Any]:
+        mapping_cache = object.__getattribute__(self, "__pydantic_private__").get(
+            "_mapping_cache"
+        )
+        if mapping_cache is not None:
+            return mapping_cache
+
+        data: dict[str, Any] = {}
+        for key, field in type(self).model_fields.items():
+            value = object.__getattribute__(self, key)
+            data[key] = value
+            if field.alias and field.alias != key:
+                data[field.alias] = value
+        extra = object.__getattribute__(self, "__pydantic_extra__") or {}
+        for key, value in extra.items():
+            data[key] = value
+        self._mapping_cache = data
+        return data
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        super().__setattr__(name, value)
+        if name != "_mapping_cache":
+            self._mapping_cache = None
+
+    def __delattr__(self, item: str) -> None:
+        super().__delattr__(item)
+        if item != "_mapping_cache":
+            self._mapping_cache = None
+
+    def __getitem__(self, key: str) -> Any:
+        data = self._mapping_data()
+        if key not in data:
+            raise KeyError(key)
+        return data[key]
+
+    def __iter__(self) -> Iterator[str]:  # type: ignore[override]
+        return iter(self._mapping_data())
+
+    def __len__(self) -> int:
+        return len(self._mapping_data())
+
+    def __bool__(self) -> bool:
+        return bool(self._mapping_data())
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._mapping_data().get(key, default)
+
+    def items(self) -> ItemsView[str, Any]:
+        return self._mapping_data().items()
+
+    def keys(self) -> KeysView[str]:
+        return self._mapping_data().keys()
+
+    def values(self) -> ValuesView[Any]:
+        return self._mapping_data().values()
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        data = self._mapping_data()
+        if name in data:
+            return data[name]
+        raise AttributeError(name)
+
+    def to_plain_dict(self, *, exclude_none: bool = True) -> dict[str, Any]:
+        """Dump config models to plain nested Python dicts."""
+        return self.model_dump(mode="python", exclude_none=exclude_none, by_alias=True)
+
+
+class ConfigNode(ConfigMappingBase):
+    """Open-ended config section that still supports attribute and mapping access."""
+
+    # Accepts arbitrary keys — the config tree is open-ended by design.
+    model_config = ConfigDict(extra="allow")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_input(cls, value: object) -> object:
+        if isinstance(value, ConfigNode):
+            return value
+        if isinstance(value, Mapping):
+            return {key: _normalize_node_value(item) for key, item in value.items()}
+        return value
+
+
+class RenderingConfig(ConfigNode):
+    class TimestampConfig(ConfigNode):
+        font: FontStyle
+        y: float
+
+        @model_validator(mode="after")
+        def _require_font_size_and_color(self) -> RenderingConfig.TimestampConfig:
+            # The timestamp renderer writes `font-size` and `fill` attributes
+            # directly into SVG. Missing values would silently emit the empty
+            # string or the literal "None". Require both at config-load time
+            # so misconfiguration fails loudly.
+            if self.font.size is None:
+                raise ValueError("rendering.timestamp.font.size is required (float)")
+            if self.font.color is None:
+                raise ValueError(
+                    "rendering.timestamp.font.color is required (color string)"
+                )
+            return self
+
+    class FooterConfig(ConfigNode):
+        class RuleConfig(ConfigNode):
+            color: str
+            stroke_width: float
+
+        font: FontStyle
+        y_offset: float
+        # None means "no hairline rule above the footer text" — a legitimate
+        # theme choice distinct from "rule configured but invisible". Theme YAML
+        # supplies a default RuleConfig; users override with `rule: null` to drop it.
+        rule: RuleConfig | None = None
+
+        @model_validator(mode="after")
+        def _require_font_size_and_color(self) -> RenderingConfig.FooterConfig:
+            if self.font.size is None:
+                raise ValueError("rendering.footer.font.size is required (float)")
+            if self.font.color is None:
+                raise ValueError(
+                    "rendering.footer.font.color is required (color string)"
+                )
+            return self
+
+    class SvgRenderingConfig(ConfigNode):
+        preserve_aspect_ratio: str
+        background: str | None = None  # None = renderer uses theme background
+
+    class PngRenderingConfig(ConfigNode):
+        scale: float
+        background: str | None = None  # None = renderer uses theme background
+
+    class PdfRenderingConfig(ConfigNode):
+        background: str | None = None  # None = renderer uses theme background
+        page_size: str
+
+    class HtmlRenderingConfig(ConfigNode):
+        background: str | None = None  # None = renderer uses theme background
+
+    class TerminalRenderingConfig(ConfigNode):
+        background: str | None = None  # None = renderer uses theme background
+
+    timestamp_visible: bool
+    timestamp_format: str
+    timestamp: TimestampConfig
+    footer_text: str
+    footer: FooterConfig
+    svg: SvgRenderingConfig
+    png: PngRenderingConfig
+    pdf: PdfRenderingConfig
+    html: HtmlRenderingConfig
+    terminal: TerminalRenderingConfig
+
+
+class MarkdownConfig(ConfigNode):
+    light: ConfigNode
+    dark: ConfigNode
+
+
+class VegaRuntimeConfig(ConfigNode):
+    default_theme: str
+    config: VegaLiteConfig = Field(default_factory=VegaLiteConfig)
+
+    @property
+    def schema(self) -> str:  # type: ignore[override]
+        return VEGA_LITE_SCHEMA_URL
+
+
+class Config(ConfigMappingBase):
+    """Authoritative required runtime config model.
+
+    Closed top-level fields define the supported global config surface. Some
+    nested sections remain intentionally open-ended because they carry dynamic
+    named entries such as themes, presets, palettes, and chart-type maps.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    chart_rendering: ConfigNode
+    geo_sources: ConfigNode
+    inspector: ConfigNode
+    markdown: MarkdownConfig
+    rendering: RenderingConfig
+    style: Style
+    terminal: ConfigNode
+    themes: ConfigNode = Field(
+        default_factory=ConfigNode
+    )  # legacy VL-format themes; empty after chart_themes/ deletion
+    palettes: ConfigNode
+    vega: VegaRuntimeConfig
+    dft_grays: ConfigNode
+    dft_creams: ConfigNode
+    strict: bool | None = None  # None = strict mode not configured; defaults to off
+    sources: ConfigNode | None = None  # None = no explicit sources section in config
+
+    @model_validator(mode="after")
+    def _validate_theme_and_palette_contract(self) -> Config:
+        # themes dict may be empty now that chart_themes/ is removed; skip check
+        # The unified themes/*.yaml system is the source of truth for theme names.
+        category = self.palettes.get("category-10")
+        if not isinstance(category, list) or not category:
+            raise ValueError("palettes.category-10 must be present and non-empty")
+        return self
+
+
+class ConfigPatchBase(ConfigMappingBase):
+    """Base class for dynamically-derived config patch models."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ConfigNodePatch(ConfigPatchBase):
+    """Open-ended patch node for dynamic config sections."""
+
+    # Accepts arbitrary keys — patch nodes mirror the open-ended config tree.
+    model_config = ConfigDict(extra="allow")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_input(cls, value: object) -> object:
+        if isinstance(value, ConfigNodePatch):
+            return value
+        if isinstance(value, Mapping):
+            return {key: _normalize_node_value(item) for key, item in value.items()}
+        return value
+
+
+def as_plain_mapping(value: ConfigMappingBase | Mapping[str, Any]) -> dict[str, Any]:
+    """Project a compiled config model or raw mapping into a plain dict."""
+    if isinstance(value, ConfigMappingBase):
+        return value.to_plain_dict(exclude_none=False)
+    return dict(value)
+
+
+def is_mapping_like(value: object) -> bool:
+    """Return whether a value can be consumed through mapping helpers."""
+    return isinstance(value, ConfigMappingBase | Mapping)
+
+
+def _optional_annotation(annotation: Any) -> Any:
+    if annotation is Any:
+        return Any
+    if getattr(annotation, "__args__", ()) and type(None) in annotation.__args__:
+        return annotation
+    return annotation | None
+
+
+def _patch_annotation(annotation: Any) -> Any:
+    # Style appears as Config.style. In the patch, accept any
+    # dict (e.g. {extends: "default"}) — the loader resolves it before
+    # Config.model_validate is called.
+    if annotation is Style:
+        return dict[str, Any]
+    if isinstance(annotation, type) and issubclass(annotation, ConfigNode):
+        return _build_patch_model(annotation)
+    if isinstance(annotation, type) and issubclass(annotation, ConfigMappingBase):
+        return _build_patch_model(annotation)
+    return annotation
+
+
+@cache
+def _build_patch_model(model_cls: type[ConfigMappingBase]) -> type[ConfigPatchBase]:
+    """Create an all-optional patch model from a compiled config model.
+
+    Intentionally separate from compile.factories.build_patch_model.
+    Three models.config-specific behaviours make a shared factory impractical:
+      1. Base class: ConfigPatchBase/ConfigNodePatch (not _PatchBase).
+      2. ConfigNode short-circuit: returns ConfigNodePatch directly.
+      3. Style replacement: swaps Style → dict[str, Any] so
+         authored style: {extends: "..."} dicts pass before loader resolution.
+    """
+    if model_cls is ConfigNode:
+        return ConfigNodePatch
+
+    fields: dict[str, tuple[Any, Any]] = {}
+    for name, field in model_cls.model_fields.items():
+        annotation = _optional_annotation(_patch_annotation(field.annotation))
+        field_kwargs: dict[str, Any] = {"default": None}
+        if field.alias and field.alias != name:
+            field_kwargs["alias"] = field.alias
+        fields[name] = (annotation, Field(**field_kwargs))
+
+    patch_name = "ConfigPatch" if model_cls is Config else f"{model_cls.__name__}Patch"
+    base_cls: type[ConfigPatchBase] = ConfigPatchBase
+    if issubclass(model_cls, ConfigNode):
+        base_cls = ConfigNodePatch
+
+    return create_model(  # type: ignore[call-overload]
+        patch_name, __base__=base_cls, **fields
+    )
+
+
+ConfigPatch = _build_patch_model(Config)