dataface 0.1.2__py3-none-any.whl

dataface/core/__init__.py

@@ -0,0 +1,75 @@
+"""Dataface Core Engine.
+
+This module provides the core compilation, execution, and rendering
+functionality for Dataface dashboards.
+
+Submodules:
+    - compile/: Transform YAML → Face
+    - execute/: Execute queries and fetch data
+    - render/: Transform Face + data → output
+    - serve/: HTTP server for dashboard serving
+    - inspect/: Database inspection and profiling
+    - validate: Validation utilities
+
+High-Level API:
+    >>> from pathlib import Path
+    >>> from dataface.core import compile, Executor, render
+    >>> from dataface.core.execute.adapters import build_adapter_registry
+    >>> result = compile(yaml_content)
+    >>> registry = build_adapter_registry(Path.cwd())
+    >>> executor = Executor(result.face, registry, query_registry=result.query_registry)
+    >>> html = render(result.face, executor, format="html")
+"""
+
+# Re-export main compile functions and types
+# Re-export validate module
+from dataface.core import validate
+from dataface.core.compile import (
+    AnyQuery,
+    AuthoredFace,
+    Chart,
+    CompilationError,
+    CompileResult,
+    Face,
+    Layout,
+    LayoutItem,
+    Variable,
+    compile,
+    compile_file,
+)
+
+# Re-export execute functions and types
+from dataface.core.execute import (
+    ExecutionError,
+    Executor,
+)
+
+# Re-export render functions and types
+from dataface.core.render import (
+    RenderError,
+    render,
+)
+
+__all__ = [
+    # Compile
+    "compile",
+    "compile_file",
+    "CompileResult",
+    "Face",
+    "Chart",
+    "AnyQuery",
+    "Layout",
+    "LayoutItem",
+    "AuthoredFace",
+    "Chart",
+    "Variable",
+    "CompilationError",
+    # Execute
+    "Executor",
+    "ExecutionError",
+    # Render
+    "render",
+    "RenderError",
+    # Validate
+    "validate",
+]

dataface/core/compile/__init__.py

@@ -0,0 +1,244 @@
+"""AuthoredFace compilation module.
+
+Stage: COMPILE
+Purpose: Transform YAML face definitions into Face objects
+ready for execution and rendering.
+
+Entry Points:
+    - compile(yaml_content: str) -> CompileResult
+    - compile_file(file_path: Path) -> CompileResult
+
+Outputs:
+    - Face: Fully normalized face with all references resolved
+    - CompileResult: Result container with face, errors, and warnings
+
+Dependencies:
+    - yaml (PyYAML)
+    - pydantic
+
+This module is pure - it does NOT import from execute/ or render/.
+"""
+
+from dataface.core.compile.chart_focus import focus_on_chart
+from dataface.core.compile.compiler import CompileResult, compile, compile_file
+from dataface.core.compile.config import (
+    AccessConfig,
+    MetaConfig,
+    ProjectSourcesConfig,
+    get_config,
+    get_project_sources,
+    get_project_warnings_ignore,
+    load_config,
+)
+from dataface.core.compile.errors import (
+    CompilationError,
+    JinjaError,
+    ParseError,
+    ReferenceError,
+    ValidationError,
+)
+from dataface.core.compile.meta import (
+    get_meta_for_face,
+    load_meta_file,
+    merge_meta_with_face,
+    resolve_meta_chain,
+)
+from dataface.core.compile.models.chart.authored import (
+    AreaChart,
+    AuthoredChart,
+    BarChart,
+    CalloutChart,
+    ChartType,
+    GeoshapeChart,
+    HeatmapChart,
+    KpiChart,
+    LayeredChart,
+    LineChart,
+    PieChart,
+    PointMapChart,
+    ScatterChart,
+    SparkBarChart,
+    SparkConfig,
+    SparkTypeLiteral,
+    TableChart,
+    TableColumnConfig,
+)
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+    ChartDependencies,
+    is_chart,
+)
+from dataface.core.compile.models.face.authored import (
+    AuthoredFace,
+    LayoutType,
+    SourcesSection,
+)
+from dataface.core.compile.models.face.compiled import (
+    Face,
+    Layout,
+    LayoutItem,
+    VariableValues,
+    is_face,
+)
+from dataface.core.compile.models.query.authored import AuthoredQuery
+from dataface.core.compile.models.query.compiled import (
+    VALID_QUERY_TYPES,
+    AnyQuery,
+    CsvQuery,
+    DbtModelQuery,
+    HttpQuery,
+    MetricFlowQuery,
+    SqlQuery,
+    is_csv_query,
+    is_dbt_model_query,
+    is_http_query,
+    is_metricflow_query,
+    is_sql_query,
+)
+from dataface.core.compile.models.source import (
+    VALID_SOURCE_TYPES,
+    BigQuerySourceConfig,
+    CsvSourceConfig,
+    DbtProfileSourceConfig,
+    DuckDBSourceConfig,
+    HttpSourceConfig,
+    JsonSourceConfig,
+    MySQLSourceConfig,
+    ParquetSourceConfig,
+    PostgresSourceConfig,
+    RedshiftSourceConfig,
+    SnowflakeSourceConfig,
+    SourceConfig,
+    is_api_source,
+    is_database_source,
+    is_file_source,
+    parse_source_config,
+    resolve_env_var,
+)
+from dataface.core.compile.models.variable.authored import (
+    Variable,
+    VariableInputType,
+)
+from dataface.core.compile.parameterized import (
+    ParameterizedQuery,
+    render_parameterized,
+    render_parameterized_with_queries,
+)
+from dataface.core.compile.sources import (
+    DB_INFO_MAP,
+    detect_database_type_from_registry,
+    detect_dbt_connection_string,
+    detect_dbt_connections,
+    detect_dbt_database_type,
+    get_database_info,
+)
+from dataface.core.compile.variables import parse_variable_json_strings
+
+__all__ = [
+    # Main entry points
+    "compile",
+    "compile_file",
+    "CompileResult",
+    "focus_on_chart",
+    # Input types
+    "AuthoredFace",
+    "AuthoredChart",
+    "BarChart",
+    "LineChart",
+    "AreaChart",
+    "ScatterChart",
+    "HeatmapChart",
+    "PieChart",
+    "KpiChart",
+    "TableChart",
+    "PointMapChart",
+    "GeoshapeChart",
+    "LayeredChart",
+    "CalloutChart",
+    "SparkBarChart",
+    "AuthoredQuery",
+    "Variable",
+    "SourcesSection",
+    # Compiled types
+    "Face",
+    "Chart",
+    "AnyQuery",
+    "Layout",
+    "LayoutItem",
+    "VariableValues",
+    "ChartDependencies",
+    # Unified query types
+    "SqlQuery",
+    "CsvQuery",
+    "MetricFlowQuery",
+    "HttpQuery",
+    "DbtModelQuery",
+    "VALID_QUERY_TYPES",
+    # Source types
+    "SourceConfig",
+    "PostgresSourceConfig",
+    "SnowflakeSourceConfig",
+    "BigQuerySourceConfig",
+    "RedshiftSourceConfig",
+    "MySQLSourceConfig",
+    "DuckDBSourceConfig",
+    "CsvSourceConfig",
+    "ParquetSourceConfig",
+    "JsonSourceConfig",
+    "HttpSourceConfig",
+    "DbtProfileSourceConfig",
+    "VALID_SOURCE_TYPES",
+    "parse_source_config",
+    "is_database_source",
+    "is_file_source",
+    "is_api_source",
+    "resolve_env_var",
+    # Config
+    "ProjectSourcesConfig",
+    "get_config",
+    "load_config",
+    "get_project_sources",
+    "get_project_warnings_ignore",
+    # Meta configuration
+    "MetaConfig",
+    "AccessConfig",
+    "get_meta_for_face",
+    "load_meta_file",
+    "merge_meta_with_face",
+    "resolve_meta_chain",
+    # Type guards
+    "is_face",
+    "is_chart",
+    "is_sql_query",
+    "is_csv_query",
+    "is_metricflow_query",
+    "is_http_query",
+    "is_dbt_model_query",
+    # Enums
+    "ChartType",
+    "LayoutType",
+    "VariableInputType",
+    "SparkTypeLiteral",
+    # Spark charts
+    "SparkConfig",
+    "TableColumnConfig",
+    # Errors
+    "CompilationError",
+    "ParseError",
+    "ValidationError",
+    "ReferenceError",
+    "JinjaError",
+    # Parameterized queries
+    "ParameterizedQuery",
+    "render_parameterized",
+    "render_parameterized_with_queries",
+    # Variable utilities
+    "parse_variable_json_strings",
+    # Source detection utilities
+    "DB_INFO_MAP",
+    "detect_database_type_from_registry",
+    "detect_dbt_connection_string",
+    "detect_dbt_connections",
+    "detect_dbt_database_type",
+    "get_database_info",
+]

dataface/core/compile/_jinja_helpers.py

@@ -0,0 +1,78 @@
+"""Shared Jinja helpers used by compile/parameterized.py and compile/jinja.py.
+
+Both modules need identical lenient-undefined and query-namespace behaviour;
+this module is the single canonical home. Consumers import from here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from jinja2 import Undefined
+
+
+class _LenientUndefined(Undefined):
+    """Lenient undefined for non-strict Jinja rendering.
+
+    Undefined variables become empty strings rather than raising errors.
+    Used in interactive editing contexts where variables may not yet be defined.
+    """
+
+    def __str__(self) -> str:
+        return ""
+
+    def __repr__(self) -> str:
+        return ""
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __iter__(self) -> Any:
+        return iter([])
+
+    def __len__(self) -> int:
+        return 0
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, Undefined) or other is None or other == ""
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
+
+    def __getitem__(self, key: Any) -> _LenientUndefined:  # type: ignore[override]
+        return self
+
+    def __getattr__(self, name: str) -> _LenientUndefined:
+        # Return self for chaining like {{ foo.bar.baz }}; guard dunder lookups.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return self
+
+
+class _QueryNamespace:
+    """Proxy for {{ queries.query_name }} template resolution.
+
+    Returns the SQL body of the named query. Raises AttributeError (the
+    correct Python __getattr__ protocol) when the query is not found.
+    """
+
+    def __init__(self, queries: dict[str, Any]):
+        self._queries = queries
+
+    def __getattr__(self, name: str) -> str:
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        if name not in self._queries:
+            raise AttributeError(f"Query '{name}' not found")
+
+        query = self._queries[name]
+
+        if hasattr(query, "sql"):
+            sql = query.sql
+            return sql if isinstance(sql, str) else ""
+        elif isinstance(query, dict):
+            sql = query.get("sql", "")
+            return sql if isinstance(sql, str) else ""
+
+        return str(query)

dataface/core/compile/channel.py

@@ -0,0 +1,222 @@
+"""Chart style channel parsing and normalization.
+
+Handles the {column, value, scale} grammar for chart-level color
+channels (color, background, opacity, stroke.color, stroke.width).
+
+Rule-driven styling lives in the chart-level ``conditional_formatting:``
+block (indexed by column name), not per-channel. See ``types.py`` for
+``FieldConditionalFormatting``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from dataface.core.compile.models.chart.authored import (
+    GEO_CHART_TYPES,
+    ConditionalRule,
+)
+from dataface.core.compile.models.primitives import ScaleTargetConfig, StyleColorConfig
+
+
+@dataclass(frozen=True)
+class ResolvedStyleChannel:
+    channel: str
+    mode: Literal["series", "literal", "gradient", "conditional"]
+    data_field: str = ""
+    literal_value: Any = None
+    scale: ScaleTargetConfig | None = None
+    rules: tuple[ConditionalRule, ...] = ()
+    # When mode == "conditional", optional gradient fallback used when no
+    # threshold rule matches. Enables Looker-style "scale with rule override"
+    # where threshold rules take priority and scale shows through otherwise.
+    fallback_scale: ScaleTargetConfig | None = None
+
+
+def parse_style_channel(
+    raw: str | dict[str, Any], channel_name: str
+) -> ResolvedStyleChannel:
+    """Parse a raw authored channel value into a typed ResolvedStyleChannel.
+
+    Handles shorthand (string) and four expanded forms.
+    Validates mutual exclusion. Does NOT validate field references (needs data).
+
+    Args:
+        raw: The authored value — string shorthand or {column,value,scale,when} dict
+        channel_name: The channel name for error messages
+
+    Raises:
+        ValueError: On mutual exclusion violations or unknown form
+    """
+    if isinstance(raw, str):
+        return ResolvedStyleChannel(channel=channel_name, mode="series", data_field=raw)
+
+    if not isinstance(raw, dict):
+        raise ValueError(
+            f"Channel '{channel_name}' must be a string or dict, got {type(raw).__name__}"
+        )
+
+    has_column = "column" in raw
+    has_value = "value" in raw
+    has_scale = "scale" in raw
+
+    extra = set(raw.keys()) - {"column", "value", "scale"}
+    if extra:
+        raise ValueError(
+            f"Channel '{channel_name}': unknown keys {sorted(extra)} (supported: column, value, scale)."
+        )
+
+    if has_value and (has_column or has_scale):
+        raise ValueError(
+            f"Channel '{channel_name}': 'value' cannot be combined with 'column' or 'scale'."
+        )
+
+    if has_value:
+        if raw["value"] is None:
+            raise ValueError(
+                f"Channel '{channel_name}': 'value' cannot be None — use a non-null style value."
+            )
+        return ResolvedStyleChannel(
+            channel=channel_name, mode="literal", literal_value=raw["value"]
+        )
+
+    if not has_column:
+        raise ValueError(
+            f"Channel '{channel_name}': must specify 'column' or 'value' (got keys: {list(raw.keys())})."
+        )
+
+    data_field = raw["column"]
+
+    if has_scale:
+        if not isinstance(raw["scale"], dict):
+            raise ValueError(
+                f"Channel '{channel_name}': 'scale' must be a mapping, "
+                f"got {type(raw['scale']).__name__}."
+            )
+        scale_dict = dict(raw["scale"])
+        if channel_name in ("opacity", "stroke_width") and "palette" not in scale_dict:
+            scale_dict["palette"] = [0.2, 1.0]
+        scale_cfg = ScaleTargetConfig.model_validate(scale_dict)
+        return ResolvedStyleChannel(
+            channel=channel_name,
+            mode="gradient",
+            data_field=data_field,
+            scale=scale_cfg,
+        )
+
+    return ResolvedStyleChannel(
+        channel=channel_name, mode="series", data_field=data_field
+    )
+
+
+def validate_channel_fields(
+    channels: dict[str, ResolvedStyleChannel],
+    available_columns: set[str],
+) -> None:
+    """Raise ValueError if any channel references a field not in available_columns.
+
+    Only validates data-bound channels (mode in series/gradient/conditional).
+    """
+    for channel_name, ch in channels.items():
+        if ch.mode == "literal":
+            continue
+        if ch.data_field and ch.data_field not in available_columns:
+            # Common mistake: author writes `color: "#fff"` intending a literal.
+            # The string shorthand parses as series mode with data_field="#fff".
+            if ch.data_field.startswith("#"):
+                raise ValueError(
+                    f"Channel '{channel_name}': '{ch.data_field}' looks like a literal color — "
+                    f'use {{{channel_name}: {{value: "{ch.data_field}"}}}}'
+                )
+            raise ValueError(
+                f"Channel '{channel_name}' column '{ch.data_field}' not found. "
+                f"Available: {sorted(available_columns)}"
+            )
+
+
+_COLOR_CHANNELS = frozenset({"color"})
+_NUMERIC_CHANNELS: frozenset[str] = frozenset()
+
+
+def _validate_palette_types(channels: dict[str, ResolvedStyleChannel]) -> None:
+    """Raise ValueError if palette type doesn't match channel semantics."""
+    for ch_name, ch in channels.items():
+        if ch.mode != "gradient" or ch.scale is None:
+            continue
+        palette = ch.scale.palette
+        if not palette:
+            continue
+        if ch_name in _COLOR_CHANNELS:
+            if not all(isinstance(c, str) for c in palette):
+                raise ValueError(
+                    f"Channel '{ch_name}' expects a color palette (list of strings), "
+                    f"got numeric values. Use strings like '#ffffff'."
+                )
+        elif ch_name in _NUMERIC_CHANNELS:
+            if not all(
+                isinstance(c, (int, float)) and not isinstance(c, bool) for c in palette
+            ):
+                raise ValueError(
+                    f"Channel '{ch_name}' expects a numeric palette (list of floats), "
+                    f"got non-numeric values."
+                )
+
+
+def normalize_chart_channels(
+    chart: Any,
+    available_columns: set[str],
+    style_color: str | StyleColorConfig | None = None,
+) -> dict[str, ResolvedStyleChannel]:
+    """Parse and validate chart-level style channels.
+
+    Only ``color`` is a data channel at chart root. background/opacity/stroke
+    were removed as data channels (they are paint fields, not data bindings).
+
+    ``style_color``: when a ``StyleColorConfig`` with a scale is provided, the
+    series color channel is upgraded to gradient mode.  A plain string value
+    means static paint — no data channel is created.
+
+    Raises ValueError on unresolvable field references or invalid syntax.
+    """
+    channels: dict[str, ResolvedStyleChannel] = {}
+
+    chart_type = getattr(chart, "type", None)
+
+    color_raw = getattr(chart, "color", None)
+    if color_raw is not None:
+        channels["color"] = parse_style_channel(color_raw, "color")
+
+    # Upgrade series channel to gradient when style.color carries a scale.
+    if isinstance(style_color, StyleColorConfig) and style_color.scale is not None:
+        if "color" not in channels:
+            raise ValueError(
+                "style.color: {scale: ...} requires chart.color to name a data field.\n"
+                "Add a data column binding, e.g.:\n"
+                "  color: revenue\n"
+                "  style:\n    color: {scale: {palette: ['#fff', '#00f']}}"
+            )
+        if channels["color"].mode == "series":
+            channels["color"] = ResolvedStyleChannel(
+                channel="color",
+                mode="gradient",
+                data_field=channels["color"].data_field,
+                scale=style_color.scale,
+            )
+
+    # Geo renderers only consume the color field name — gradient/conditional modes
+    # silently drop palette or rules. Raise early so the author gets a clear error.
+    if chart_type in GEO_CHART_TYPES and "color" in channels:
+        color_mode = channels["color"].mode
+        if color_mode not in ("series", "literal"):
+            raise ValueError(
+                f"Geo charts ('{chart_type}') only support series or literal color channels — "
+                f"got mode '{color_mode}'. Use chart.color: <field> or chart.style.color: <hex>."
+            )
+
+    if available_columns:
+        validate_channel_fields(channels, available_columns)
+
+    _validate_palette_types(channels)
+
+    return channels