dataface 0.1.2__py3-none-any.whl

dataface/core/defaults/themes/stark.yaml

@@ -0,0 +1,134 @@
+# Unified theme: stark
+# Structural root for the built-in theme cascade — every other built-in theme
+# transitively extends this file (`editorial` extends `stark`; `cream` via
+# `editorial`; `carbong100` via `dark`; `dark`/`light`/`bi`/`looker` directly).
+# Stark itself is opt-in for users: "stripped-back / utilitarian / sans-only"
+# — pick it when you want the pre-editorial bones without the refined
+# hierarchy that the shipped `editorial` theme adds on top.
+
+extends: _base
+style:
+  # ── Colors ─────────────────────────────────────────────────────────────────
+  background: '#FFFFFF'
+  accent: '#3b82f6'
+  muted: '#e5e7eb'
+
+  font:
+    family: &font_sans '''Inter Variable'', Inter, system-ui, sans-serif'
+    color: &color_ink dft-grays.heading
+
+  border:
+    color: *color_ink
+
+  title:
+    font:
+      family: *font_sans
+      color: *color_ink
+    subtitle:
+      font:
+        family: *font_sans
+        color: *color_ink
+
+  charts:
+    axis:
+      domain:
+        color: *color_ink
+      ticks:
+        color: *color_ink
+      grid:
+        color: *color_ink
+        zero:
+          color: *color_ink
+      label:
+        font:
+          color: *color_ink
+      title:
+        font:
+          color: *color_ink
+
+    legend:
+      label:
+        font:
+          color: *color_ink
+      title:
+        font:
+          color: *color_ink
+
+    table:
+      border:
+        color: '#e0e0e0'
+      paginator:
+        color_active: dft-grays.ink
+        color_inactive: dft-grays.inactive
+        color_disabled: dft-grays.disabled
+      header:
+        font:
+          color: *color_ink
+      spark:
+        empty:
+          stroke:
+            color: '#d1d5db'
+
+    marks:
+      text:
+        font:
+          family: *font_sans
+          color: *color_ink
+      rule:
+        stroke:
+          color: *color_ink
+      tick:
+        stroke:
+          color: *color_ink
+
+    kpi:
+      font:
+        family: '''DFT Sans Tabular'', Inter, system-ui, sans-serif'
+
+    data_table:
+      font:
+        family: '''DFT Sans Tabular'', Inter, system-ui, sans-serif'
+        color: *color_ink
+      divider:
+        color: *color_ink
+      label:
+        font:
+          color: *color_ink
+
+    axis_quantitative:
+      label:
+        font:
+          family: '''DFT Sans Tabular'', Inter, system-ui, sans-serif'
+
+    pie:
+      total:
+        value:
+          font:
+            family: '''DFT Sans Tabular'', Inter, system-ui, sans-serif'
+            color: *color_ink
+        label:
+          font:
+            color: *color_ink
+
+  text:
+    font:
+      family: *font_sans
+      color: *color_ink
+
+  variables:
+    font:
+      color: *color_ink
+    border:
+      color: *color_ink
+    input:
+      border:
+        color: *color_ink
+
+  page:
+    background: '#FFFFFF'
+
+  placeholder:
+    overlay:
+      background: 'rgba(255, 255, 255, 0.5)'
+      font:
+        color: '#666666'

dataface/core/errors/__init__.py

@@ -0,0 +1,67 @@
+"""Global error registry: codes, doc pointers, and did-you-mean hints.
+
+Importing this package side-effect-registers every code module so a single
+``from dataface.core.errors import REGISTRY`` is enough to look up any code
+by string at runtime.
+"""
+
+from __future__ import annotations
+
+# Side-effect imports — required for REGISTRY self-registration.
+from dataface.core.errors.codes_compile import (
+    DF_COMPILE_EXTRA_FIELD,
+    DF_COMPILE_UNKNOWN_QUERY,
+)
+from dataface.core.errors.codes_execute import (
+    DF_EXECUTE_COLUMN_NOT_FOUND,
+    DF_EXECUTE_MUTATING_SQL,
+    DF_EXECUTE_NO_DEFAULT_SOURCE,
+    DF_EXECUTE_SCHEMA_NOT_FOUND,
+    DF_EXECUTE_SOURCE_NOT_FOUND,
+    DF_EXECUTE_SOURCE_NOT_FOUND_EMPTY,
+    DF_EXECUTE_TABLE_NOT_FOUND,
+    DF_EXECUTE_UNPARSEABLE_SQL,
+)
+from dataface.core.errors.codes_render import (
+    DF_RENDER_BAR_DUPLICATE_ROWS,
+    DF_RENDER_FORMAT_UNSUPPORTED,
+    DF_RENDER_INPUT_INVALID,
+    DF_RENDER_INTERNAL,
+    DF_RENDER_KPI_MULTIROW,
+    DF_RENDER_NO_LAYOUT,
+    DF_RENDER_UNKNOWN_CHART_TYPE,
+)
+from dataface.core.errors.codes_unknown import DF_UNKNOWN_INTERNAL
+from dataface.core.errors.registry import REGISTRY, ErrorCode, build_doc_url
+from dataface.core.errors.structured import (
+    NextCommand,
+    StructuredError,
+    build_structured,
+)
+
+__all__ = [
+    "ErrorCode",
+    "REGISTRY",
+    "StructuredError",
+    "NextCommand",
+    "build_structured",
+    "build_doc_url",
+    "DF_UNKNOWN_INTERNAL",
+    "DF_COMPILE_EXTRA_FIELD",
+    "DF_COMPILE_UNKNOWN_QUERY",
+    "DF_EXECUTE_COLUMN_NOT_FOUND",
+    "DF_EXECUTE_MUTATING_SQL",
+    "DF_EXECUTE_NO_DEFAULT_SOURCE",
+    "DF_EXECUTE_SCHEMA_NOT_FOUND",
+    "DF_EXECUTE_SOURCE_NOT_FOUND",
+    "DF_EXECUTE_SOURCE_NOT_FOUND_EMPTY",
+    "DF_EXECUTE_TABLE_NOT_FOUND",
+    "DF_EXECUTE_UNPARSEABLE_SQL",
+    "DF_RENDER_BAR_DUPLICATE_ROWS",
+    "DF_RENDER_FORMAT_UNSUPPORTED",
+    "DF_RENDER_INPUT_INVALID",
+    "DF_RENDER_INTERNAL",
+    "DF_RENDER_KPI_MULTIROW",
+    "DF_RENDER_NO_LAYOUT",
+    "DF_RENDER_UNKNOWN_CHART_TYPE",
+]

dataface/core/errors/codes_compile.py

@@ -0,0 +1,56 @@
+"""DF-COMPILE-* error codes.
+
+Covers compile-domain raise sites migrated off DF-UNKNOWN-INTERNAL:
+- DF-COMPILE-UNKNOWN-QUERY: chart references a query name that does not exist
+- DF-COMPILE-EXTRA-FIELD: YAML contains a field not recognised by the schema
+- DF-COMPILE-SQL-LITERAL-NEWLINES: SQL contains literal \\n from single-quoted YAML
+"""
+
+from __future__ import annotations
+
+from dataface.core.errors.registry import REGISTRY, ErrorCode, build_doc_url
+
+DF_COMPILE_UNKNOWN_QUERY = REGISTRY.register(
+    ErrorCode(
+        code="DF-COMPILE-UNKNOWN-QUERY",
+        domain="compile",
+        message_template=(
+            "Chart {chart_name!r} references unknown query {query_name!r}. "
+            "Declare the query under `queries:` or fix the typo in `query:`."
+        ),
+        doc_url=build_doc_url("DF-COMPILE-UNKNOWN-QUERY"),
+        docs_topic="compile.errors",
+    )
+)
+
+DF_COMPILE_EXTRA_FIELD = REGISTRY.register(
+    ErrorCode(
+        code="DF-COMPILE-EXTRA-FIELD",
+        domain="compile",
+        message_template=(
+            "Unknown field {field_path!r} in face YAML. "
+            "Remove it or check the schema for supported keys."
+        ),
+        doc_url=build_doc_url("DF-COMPILE-EXTRA-FIELD"),
+        docs_topic="compile.errors",
+    )
+)
+
+DF_COMPILE_SQL_LITERAL_NEWLINES = REGISTRY.register(
+    ErrorCode(
+        code="DF-COMPILE-SQL-LITERAL-NEWLINES",
+        domain="compile",
+        message_template=(
+            "Query {query_name!r} {field_label} contains literal \\n (backslash + n). "
+            "Use YAML block scalar `{field_label}: |` to write multiline SQL:\n\n"
+            "  queries:\n"
+            "    my_query:\n"
+            "      {field_label}: |\n"
+            "        SELECT\n"
+            "          col\n"
+            "        FROM t"
+        ),
+        doc_url=build_doc_url("DF-COMPILE-SQL-LITERAL-NEWLINES"),
+        docs_topic="compile.errors",
+    )
+)

dataface/core/errors/codes_execute.py

@@ -0,0 +1,177 @@
+"""DF-EXECUTE-* error codes for the execute layer.
+
+Covers source-resolution failures in AdapterRegistry — the most common
+class of error agents hit when misconfiguring sources in dataface.yml.
+"""
+
+from __future__ import annotations
+
+from dataface.core.errors.hints import (
+    suggest_close_column,
+    suggest_close_schema,
+    suggest_close_source,
+    suggest_close_table,
+)
+from dataface.core.errors.registry import REGISTRY, ErrorCode, build_doc_url
+
+DF_EXECUTE_SOURCE_NOT_FOUND = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SOURCE-NOT-FOUND",
+        domain="execute",
+        message_template=(
+            "Source {source!r} not found in configured adapters. "
+            "Available sources: {available}. "
+            "dft sources are declared under `sources:` in your dataface.yml — "
+            "the source name is not the dbt project name."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SOURCE-NOT-FOUND"),
+        docs_topic="configuration.sources",
+        hint_generator=suggest_close_source,
+    )
+)
+
+DF_EXECUTE_SOURCE_NOT_FOUND_EMPTY = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SOURCE-NOT-FOUND-EMPTY",
+        domain="execute",
+        message_template=(
+            "Source {source!r} not found. No source profiles are configured. "
+            "Declare sources under `sources:` in your dataface.yml."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SOURCE-NOT-FOUND"),
+        docs_topic="configuration.sources",
+    )
+)
+
+DF_EXECUTE_NO_DEFAULT_SOURCE = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-NO-DEFAULT-SOURCE",
+        domain="execute",
+        message_template=(
+            "Source name required: no default DuckDB adapter is configured. "
+            "Pass an explicit source name from the `sources:` block in your dataface.yml."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-NO-DEFAULT-SOURCE"),
+        docs_topic="configuration.sources",
+    )
+)
+
+DF_EXECUTE_SOURCE_INLINE_FORBIDDEN = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SOURCE-INLINE-FORBIDDEN",
+        domain="execute",
+        message_template=(
+            "Inline source definition at {yaml_path!r} is not allowed — "
+            "use a named source from the project allowlist. "
+            "Inline connection parameters: {offending_value!r}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SOURCE-INLINE-FORBIDDEN"),
+        docs_topic="configuration.sources",
+    )
+)
+
+DF_EXECUTE_SOURCE_CROSS_FILE_FORBIDDEN = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SOURCE-CROSS-FILE-FORBIDDEN",
+        domain="execute",
+        message_template=(
+            "Cross-file source reference at {yaml_path!r} "
+            "(`#` anchor form) is not allowed: {offending_value!r}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SOURCE-CROSS-FILE-FORBIDDEN"),
+        docs_topic="configuration.sources",
+    )
+)
+
+DF_EXECUTE_SOURCE_INVALID_TYPE = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SOURCE-INVALID-TYPE",
+        domain="execute",
+        message_template=(
+            "Unknown source type {offending_value!r}. Valid types: {available}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SOURCE-INVALID-TYPE"),
+        docs_topic="configuration.sources",
+        hint_generator=suggest_close_source,
+    )
+)
+
+DF_EXECUTE_SOURCE_MISSING_TYPE = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SOURCE-MISSING-TYPE",
+        domain="execute",
+        message_template=(
+            "Source is missing the required `type` field: {offending_value!r}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SOURCE-MISSING-TYPE"),
+        docs_topic="configuration.sources",
+    )
+)
+
+DF_EXECUTE_MUTATING_SQL = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-MUTATING-SQL",
+        domain="execute",
+        message_template=(
+            "dft refuses to execute non-read-only SQL. "
+            "Statement: {rejected_node_kind}. Preview: {fragment_preview}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-MUTATING-SQL"),
+        docs_topic="security.sql-guard",
+    )
+)
+
+DF_EXECUTE_UNPARSEABLE_SQL = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-UNPARSEABLE-SQL",
+        domain="execute",
+        message_template=(
+            "dft could not statically validate this SQL: {cause}. "
+            "The caller decides whether to defer to runtime or fail closed."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-UNPARSEABLE-SQL"),
+        docs_topic="security.sql-guard",
+    )
+)
+
+DF_EXECUTE_SCHEMA_NOT_FOUND = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-SCHEMA-NOT-FOUND",
+        domain="execute",
+        message_template=(
+            "Schema {schema!r} not found in source {source!r}. "
+            "Available schemas: {available}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-SCHEMA-NOT-FOUND"),
+        docs_topic="configuration.sources",
+        hint_generator=suggest_close_schema,
+    )
+)
+
+DF_EXECUTE_TABLE_NOT_FOUND = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-TABLE-NOT-FOUND",
+        domain="execute",
+        message_template=(
+            "Table {table!r} not found in schema {schema!r} "
+            "(source {source!r}). Available tables: {available}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-TABLE-NOT-FOUND"),
+        docs_topic="configuration.sources",
+        hint_generator=suggest_close_table,
+    )
+)
+
+DF_EXECUTE_COLUMN_NOT_FOUND = REGISTRY.register(
+    ErrorCode(
+        code="DF-EXECUTE-COLUMN-NOT-FOUND",
+        domain="execute",
+        message_template=(
+            "Column {col_name!r} not found in table {schema!r}.{table!r} "
+            "(source {source!r}). Available columns: {available}."
+        ),
+        doc_url=build_doc_url("DF-EXECUTE-COLUMN-NOT-FOUND"),
+        docs_topic="configuration.sources",
+        hint_generator=suggest_close_column,
+    )
+)

dataface/core/errors/codes_render.py

@@ -0,0 +1,106 @@
+"""DF-RENDER-* error codes (wave 1 + bar duplicate rows).
+
+The render-domain raise sites migrated in this PR cover the registry-shape-
+proving subset:
+- DF-RENDER-NO-LAYOUT, DF-RENDER-INTERNAL, DF-RENDER-FORMAT-UNSUPPORTED
+  (renderer.py)
+- DF-RENDER-UNKNOWN-CHART-TYPE (profile.py x2, standard_renderer.py)
+- DF-RENDER-KPI-MULTIROW (kpi.py)
+- DF-RENDER-BAR-DUPLICATE-ROWS (validation.py)
+
+Column-missing and type-mismatch codes are deferred to the consumer task
+(unify-render-error-feedback), which already needs to touch every channel-
+validation raise site to thread structured fields (chart_id, available
+columns, field path) through. The consumer task adds those codes alongside
+its raise-site migration so codes don't ship registered-but-unraised here.
+"""
+
+from __future__ import annotations
+
+from dataface.core.errors.hints import suggest_close_chart_type
+from dataface.core.errors.registry import REGISTRY, ErrorCode, build_doc_url
+
+DF_RENDER_KPI_MULTIROW = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-KPI-MULTIROW",
+        domain="render",
+        message_template=(
+            "KPI chart {chart_id!r} expects exactly 1 row, got {row_count}. "
+            "Use a query that returns a single row (e.g. SELECT SUM(...) or LIMIT 1)."
+        ),
+        doc_url=build_doc_url("DF-RENDER-KPI-MULTIROW"),
+        docs_topic="charts.kpi",
+    )
+)
+
+DF_RENDER_BAR_DUPLICATE_ROWS = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-BAR-DUPLICATE-ROWS",
+        domain="render",
+        message_template=(
+            "{chart_type} chart {chart_id!r} requires pre-aggregated data "
+            "with at most one row per plotted key ({field_list}). "
+            "Found duplicate rows for {duplicate_preview}. "
+            "Aggregate in the query before rendering."
+        ),
+        doc_url=build_doc_url("DF-RENDER-BAR-DUPLICATE-ROWS"),
+        docs_topic="charts.bar",
+    )
+)
+
+DF_RENDER_UNKNOWN_CHART_TYPE = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-UNKNOWN-CHART-TYPE",
+        domain="render",
+        message_template="Unknown chart type: {chart_type!r}",
+        doc_url=build_doc_url("DF-RENDER-UNKNOWN-CHART-TYPE"),
+        docs_topic="charts.types",
+        hint_generator=suggest_close_chart_type,
+    )
+)
+
+DF_RENDER_FORMAT_UNSUPPORTED = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-FORMAT-UNSUPPORTED",
+        domain="render",
+        message_template="Unknown format: {format!r}",
+        doc_url=build_doc_url("DF-RENDER-FORMAT-UNSUPPORTED"),
+        docs_topic="render.formats",
+    )
+)
+
+DF_RENDER_NO_LAYOUT = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-NO-LAYOUT",
+        domain="render",
+        message_template=(
+            "Face defines charts ({charts}) but no layout — would render with no visible "
+            "charts. Add a `rows:`/`cols:`/`grid:`/`tabs:` block that references them."
+        ),
+        doc_url=build_doc_url("DF-RENDER-NO-LAYOUT"),
+        docs_topic="faces.layout",
+    )
+)
+
+DF_RENDER_INTERNAL = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-INTERNAL",
+        domain="render",
+        # Field is named `inner_message` rather than `cause` so it doesn't
+        # shadow StructuredError.cause (which is computed independently
+        # from __cause__).
+        message_template="Failed to render dataface: {inner_message}",
+        doc_url=build_doc_url("DF-RENDER-INTERNAL"),
+        docs_topic="render.errors",
+    )
+)
+
+DF_RENDER_INPUT_INVALID = REGISTRY.register(
+    ErrorCode(
+        code="DF-RENDER-INPUT-INVALID",
+        domain="render",
+        message_template="{message}",
+        doc_url=build_doc_url("DF-RENDER-INPUT-INVALID"),
+        docs_topic="render.errors",
+    )
+)

dataface/core/errors/codes_unknown.py

@@ -0,0 +1,15 @@
+"""DF-UNKNOWN-* fallback code for legacy string-message constructors."""
+
+from __future__ import annotations
+
+from dataface.core.errors.registry import REGISTRY, ErrorCode, build_doc_url
+
+DF_UNKNOWN_INTERNAL = REGISTRY.register(
+    ErrorCode(
+        code="DF-UNKNOWN-INTERNAL",
+        domain="unknown",
+        message_template="{message}",
+        doc_url=build_doc_url("DF-UNKNOWN-INTERNAL"),
+        docs_topic="errors.unknown",
+    )
+)

dataface/core/errors/hints.py

@@ -0,0 +1,74 @@
+"""Hint generators for error codes using difflib close-match suggestions.
+
+Hint generators are kept generic over a comma-separated `available` string so
+the registry stays a leaf module. The raise site is responsible for passing
+the canonical list (e.g. CHART_TYPE_MAP keys for chart-type hints).
+"""
+
+from __future__ import annotations
+
+import difflib
+
+
+def _suggest_close_match(value: str, available: str, cutoff: float) -> str | None:
+    candidates = [c.strip() for c in available.split(",") if c.strip()]
+    if not candidates:
+        return None
+    matches = difflib.get_close_matches(value, candidates, n=1, cutoff=cutoff)
+    if matches:
+        return f"Did you mean {matches[0]!r}?"
+    return None
+
+
+def suggest_close_chart_type(
+    chart_type: str,
+    available: str = "",
+    **_kwargs: object,
+) -> str | None:
+    """Return a 'Did you mean X?' hint for unknown chart types.
+
+    `available` is a comma-separated list passed by the raise site (typically
+    CHART_TYPE_MAP keys); the registry stays decoupled from the chart module.
+    Defaults to "" so a raise site that forgets `available=` still produces a
+    typed-and-coded error rather than crashing the hint pathway.
+    """
+    return _suggest_close_match(chart_type, available, cutoff=0.5)
+
+
+def suggest_close_source(
+    source: str,
+    available: str = "",
+    **_kwargs: object,
+) -> str | None:
+    """Return a 'Did you mean X?' hint for unknown source names.
+
+    `available` is a comma-separated list of configured source names.
+    """
+    return _suggest_close_match(source, available, cutoff=0.5)
+
+
+def suggest_close_schema(
+    schema: str,
+    available: str = "",
+    **_kwargs: object,
+) -> str | None:
+    """Return a 'Did you mean X?' hint for an unknown schema name."""
+    return _suggest_close_match(schema, available, cutoff=0.5)
+
+
+def suggest_close_table(
+    table: str,
+    available: str = "",
+    **_kwargs: object,
+) -> str | None:
+    """Return a 'Did you mean X?' hint for an unknown table name."""
+    return _suggest_close_match(table, available, cutoff=0.5)
+
+
+def suggest_close_column(
+    col_name: str,
+    available: str = "",
+    **_kwargs: object,
+) -> str | None:
+    """Return a 'Did you mean X?' hint for an unknown column name."""
+    return _suggest_close_match(col_name, available, cutoff=0.5)

dataface/core/errors/registry.py

@@ -0,0 +1,42 @@
+"""Global error registry: ErrorCode definitions and lookup."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ErrorCode(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    code: str
+    domain: str
+    message_template: str
+    doc_url: str
+    docs_topic: str | None = None
+    hint_generator: Callable[..., str | None] | None = None
+
+
+class _Registry:
+    def __init__(self) -> None:
+        self._by_code: dict[str, ErrorCode] = {}
+
+    def register(self, ec: ErrorCode) -> ErrorCode:
+        if ec.code in self._by_code:
+            raise ValueError(f"ErrorCode {ec.code!r} already registered")
+        self._by_code[ec.code] = ec
+        return ec
+
+    def get(self, code: str) -> ErrorCode:
+        return self._by_code[code]
+
+
+REGISTRY = _Registry()
+
+DOC_BASE_URL = "https://docs.dataface.dev/errors"
+
+
+def build_doc_url(code: str) -> str:
+    """Build the canonical doc URL for an error code."""
+    return f"{DOC_BASE_URL}/{code}"