dataface 0.3.1.dev132__py3-none-any.whl → 0.3.2.dev22__py3-none-any.whl

d3_format/spec.py

@@ -49,6 +49,51 @@ class FormatSpec:
     trim: bool = False  # ~ flag
     type: str = ""  # "" means default (g-ish) behavior
 
+    def __str__(self) -> str:
+        """Serialize back to a d3-format spec string, in grammar order.
+
+        Omits every default-valued token, so a parsed spec serializes back to
+        something an author would write rather than a fully-explicit
+        expansion. ``zero`` implies ``fill == "0"`` and ``align == "="`` (the
+        collapse in ``parse``), so the zero-pad flag is emitted alone rather
+        than alongside a redundant ``0=`` fill and align.
+
+        Raises:
+            ValueError: If ``zero`` is set but ``fill``/``align`` have been
+                mutated away from ``"0"``/``"="``. The d3 grammar cannot
+                express that combination -- ``parse`` collapses ``zero`` back
+                to ``fill="0"``, ``align="="`` unconditionally -- so silently
+                keeping the flag and dropping the fill would misrepresent the
+                spec. Clear ``zero`` first if an explicit fill/align is wanted.
+        """
+        if self.zero and (self.fill != "0" or self.align != "="):
+            raise ValueError(
+                "FormatSpec has zero=True with fill="
+                f"{self.fill!r}, align={self.align!r}; the d3 grammar can "
+                "only express zero-pad as fill='0', align='='. Clear zero "
+                "if you want this fill/align combination."
+            )
+        tokens: list[str] = []
+        if not self.zero and (self.fill != " " or self.align != ">"):
+            tokens.append(self.fill)
+            tokens.append(self.align)
+        if self.sign != "-":
+            tokens.append(self.sign)
+        if self.symbol:
+            tokens.append(self.symbol)
+        if self.zero:
+            tokens.append("0")
+        if self.width is not None:
+            tokens.append(str(self.width))
+        if self.comma:
+            tokens.append(",")
+        if self.precision is not None:
+            tokens.append(f".{self.precision}")
+        if self.trim:
+            tokens.append("~")
+        tokens.append(self.type)
+        return "".join(tokens)
+
 
 def parse(spec: str) -> FormatSpec:
     """Parse a d3-format spec string into a FormatSpec.

dataface/agent_api/__init__.py

@@ -69,6 +69,7 @@ from dataface.agent_api.validate_query import (
     QueryDiagnostic as QueryDiagnostic,
     validate_query as validate_query,
 )
+from dataface.core.attribution import set_surface as set_surface
 from dataface.core.compile.compiler import (
     CompileResult as CompileResult,
     compile as compile,
@@ -76,6 +77,7 @@ from dataface.core.compile.compiler import (
 from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
 from dataface.core.dashboard import (
     RenderedDashboard as RenderedDashboard,
+    RenderFormat as RenderFormat,
     render_dashboard as render_dashboard,
 )
 from dataface.core.diagnostics import Diagnostic as Diagnostic
@@ -92,7 +94,7 @@ from dataface.core.execute.source_resolver import (
     DefaultSourceResolver as DefaultSourceResolver,
     SourceResolver as SourceResolver,
 )
-from dataface.core.fonts import get_inter_font_path as get_inter_font_path
+from dataface.core.fonts import get_fonts_dir as get_fonts_dir
 from dataface.core.project import (
     FaceFile as FaceFile,
     InMemoryFace as InMemoryFace,
@@ -118,11 +120,13 @@ __all__ = [
     "MigrateSummary",
     "Project",
     "ProjectSession",
+    "set_surface",
     "ProjectSourcesConfig",
     "QueryDiagnostic",
     "QueryFaceResult",
     "RenderedDashboard",
     "RenderError",
+    "RenderFormat",
     "SchemaHints",
     "Topic",
     "ValidateDashboardArgs",
@@ -134,7 +138,7 @@ __all__ = [
     "SourceResolver",
     "WarehouseObserver",
     "describe_face",
-    "get_inter_font_path",
+    "get_fonts_dir",
     "init_project",
     "migrate_paths",
     "query_face",

dataface/agent_api/board_artifact.py

@@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict
 
 from dataface.agent_api._paths import resolve_face_or_error
 from dataface.core.compile import compile_file
+from dataface.core.compile.variables import normalize_multiselect_values
 from dataface.core.diagnostics import ERR_FILE_NOT_FOUND, Diagnostic
 from dataface.core.diagnostics.base import DatafaceError
 from dataface.core.execute.executor import Executor
@@ -105,7 +106,16 @@ def emit_board_artifact(
     face = compile_result.face
     assert face is not None  # compile_result.success guarantees this
 
-    merged_variables: dict[str, Any] = {**face.variable_defaults, **(variables or {})}
+    # `emit-board` merges its own variables — it never goes through `render()`,
+    # whose prologue does this — and this dict is both rendered from and stored
+    # verbatim in the recording that `render_board_from_files` replays. `--var`
+    # values are always strings, so a scalar is the only shape a caller can
+    # supply for a multiselect here; unnarrowed, a bare `| join` would iterate
+    # it character by character.
+    merged_variables: dict[str, Any] = normalize_multiselect_values(
+        {**face.variable_defaults, **(variables or {})},
+        face.variable_registry or {},
+    )
 
     executor = Executor(
         face,

dataface/agent_api/docs/yaml-reference.md

@@ -2852,6 +2852,7 @@ Postgres source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | Database port number. |
 | `schema` | str | ✓ | Default schema for queries. |
 | `connect_timeout` | int | ✓ | Connection timeout in seconds. |
@@ -2878,6 +2879,7 @@ Snowflake source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `user` | str | ✓ | Snowflake user name. Omit for token-based authentication when supported. |
 | `password` | str | ✓ | Snowflake password. Omit when using OAuth or key-pair auth. |
 | `warehouse` | str | ✓ | Snowflake virtual warehouse name. |
@@ -2919,6 +2921,7 @@ BigQuery source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `keyfile` | str | ✓ | Path to service account JSON key file. |
 | `keyfile_json` | dict[str, str \| int \| float \| bool] | ✓ | Inline service account JSON dict. |
 | `location` | str | ✓ | Dataset location (e.g. US, EU). |
@@ -2961,6 +2964,7 @@ Redshift source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | Redshift port number. |
 | `schema` | str | ✓ | Default schema for queries. |
 | `user` | str | ✓ | Redshift user name. Omit for IAM-based authentication when supported. |
@@ -3009,6 +3013,7 @@ MySQL source configuration.
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | MySQL port number. |
 | `schema` | str | ✓ | Default schema for queries. |
 
@@ -3105,6 +3110,7 @@ Reference to a dbt profile.
 | `type` | enum: "dbt_profile" |  | Source type identifier. |
 | `profile` | str |  | dbt profile name from profiles.yml. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `target` | str | ✓ | dbt target to use; defaults to the profile's default target. |
 | `profiles_dir` | str | ✓ | Directory containing profiles.yml, relative to the dataface project root. Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → project root → ~/.dbt. |
 

dataface/cli/commands/render.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import typer
 
-from dataface.agent_api import Diagnostic, InMemoryFace, ProjectSession
+from dataface.agent_api import Diagnostic, InMemoryFace, ProjectSession, RenderFormat
 from dataface.agent_api._paths import (
     build_face_render_context,
     build_yaml_render_context,
@@ -19,9 +19,6 @@ from dataface.cli._error_format import print_diagnostics
 from dataface.cli._project import with_project
 from dataface.cli.filesystem_project import FilesystemProject
 
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.dashboard import RenderFormat
-
 # Maps common file extensions to render formats for format inference.
 _EXT_TO_FORMAT: dict[str, RenderFormat] = {
     "svg": "svg",

dataface/cli/commands/serve.py

@@ -67,6 +67,8 @@ def serve_command(
     Returns:
         None (exits with code 0 on success, 1 on errors)
     """
+    from dataface.agent_api import set_surface
+
     # tach-ignore(cli->core debt: route via agent_api; burn-down task)
     from dataface.core.compile.config import list_built_in_themes, load_config
 
@@ -82,6 +84,10 @@ def serve_command(
     # tach-ignore(cli->core debt: route via agent_api; burn-down task)
     from dataface.core.serve.server import create_server
 
+    # Narrows the root callback's "cli": a served dashboard's queries are a
+    # different cost story from a one-shot `dft render`.
+    set_surface("serve")
+
     project_dir = project.root
 
     # Validate DFT_DEFAULT_THEME at startup — fail fast before serving any request.

dataface/cli/main.py

@@ -12,6 +12,7 @@ from rich.console import Console
 from rich.panel import Panel
 from typer.core import TyperGroup
 
+from dataface.agent_api import RenderFormat, set_surface
 from dataface.cli._console import is_plain_output
 from dataface.cli._extras import require_extras
 from dataface.cli._parsing import parse_kv_pairs
@@ -34,9 +35,6 @@ from dataface.cli.commands import (
 from dataface.cli.commands.mcp_init import run_init as _mcp_run_init
 from dataface.cli.commands.skills_init import run_init_skills as _skills_run_init
 
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.dashboard import RenderFormat
-
 # tach-ignore(cli->core debt: route via agent_api; burn-down task)
 from dataface.core.project_roots import find_dft_root
 
@@ -1499,7 +1497,9 @@ def main(
     ] = None,
 ) -> None:
     """dft - Declarative, dbt-native dashboards in YAML."""
-    pass
+    # Runs before any subcommand, so every warehouse query this process sends is
+    # attributed to the CLI. `dft serve` narrows it to "serve" in its own command.
+    set_surface("cli")
 
 
 if __name__ == "__main__":

dataface/core/attribution.py

@@ -0,0 +1,191 @@
+"""Warehouse query attribution — what ran this query, and whose budget it belongs to.
+
+Stage: leaf (no compile/execute/render dependencies).
+
+Every query Dataface sends carries an attribution payload so a warehouse cost model
+can tell a Dataface query apart from ad-hoc human querying. Without it a dashboard
+render is indistinguishable from someone typing SQL into a console, and cost
+attribution has to guess.
+
+Two halves, with different owners:
+
+- **Identity** is engine-owned and derived — the app, the surface, the face and query
+  that caused the call. Authoring it would create a second source of truth that drifts
+  on the first rename, so authors cannot set it. Most of it sits under the ``dft_``
+  namespace; ``app`` deliberately does not, because dbt emits ``app=dbt`` and sharing
+  that one key lets a cost model ask "which tool ran this" once instead of per tool.
+- **Ownership** (``team``, ``cost_center``, …) cannot be derived from anything the
+  engine knows. It is authored per source via ``attribution:``.
+
+The payload reaches the warehouse through ``execute/adapters/query_header.py``; this
+module stays free of any dbt import so the compile layer can share its vocabulary.
+
+Engine-owned values are *normalized* to the label charset (we generate them, so a face
+slug of ``gtm/weekly-revenue`` becoming ``gtm-weekly-revenue`` is our own bookkeeping).
+Authored values are *validated* and rejected — silently rewriting what an author typed
+is the failure mode where a cost model quietly attributes spend to the wrong team.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Generator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from types import MappingProxyType
+
+# The engine's namespace. Authors cannot write keys under it, so a cost model can
+# trust that a `dft_` key means the engine said so.
+RESERVED_PREFIX = "dft_"
+
+# `app` is deliberately NOT prefixed: it is the cross-tool discriminator dbt also
+# emits (`app=dbt`), so one predicate answers "which tool ran this" across both. That
+# leaves it inside the space an author could otherwise write, so it is reserved by
+# name — without this, `attribution: {app: looker}` would shadow the engine's value,
+# since authored pairs merge over engine ones.
+RESERVED_KEYS = frozenset({"app"})
+
+# BigQuery's job-label rules are the strictest of any warehouse we emit to, so every
+# key and value is held to them regardless of dialect: one rule set means the same
+# source config behaves identically everywhere, instead of a value that works on
+# Snowflake and is silently truncated on BigQuery.
+_KEY_PATTERN = re.compile(r"^[a-z][a-z0-9_-]{0,62}$")
+_VALUE_PATTERN = re.compile(r"^[a-z0-9_-]{0,63}$")
+_NON_LABEL_CHARS = re.compile(r"[^a-z0-9_-]")
+_MAX_VALUE_LENGTH = 63
+
+# A frozen empty mapping, not `{}`: a mutable ContextVar default is shared across
+# every context that never sets one, so a stray write would leak between them.
+_NO_ATTRIBUTION: Mapping[str, str] = MappingProxyType({})
+
+_runtime: ContextVar[Mapping[str, str]] = ContextVar(
+    "dft_attribution", default=_NO_ATTRIBUTION
+)
+
+# Set once by the entry point (see set_surface); empty until one declares itself.
+_process_surface: dict[str, str] = {}
+
+# The dimensions a scope may establish. `surface` is here too so a narrower scope
+# (the inspector, say) can override what the entry point declared.
+SCOPE_DIMENSIONS = frozenset({"surface", "face", "query", "target"})
+
+
+def validate_attribution(attribution: Mapping[str, str]) -> None:
+    """Raise ``ValueError`` on a reserved or malformed authored attribution pair.
+
+    Runs at the compile boundary, on values already rendered through dbt Jinja, so an
+    ``{{ env_var(...) }}`` result is held to the same rules as a literal.
+    """
+    for key, value in attribution.items():
+        if key.startswith(RESERVED_PREFIX) or key in RESERVED_KEYS:
+            raise ValueError(
+                f"attribution key {key!r} is reserved: the engine sets it. Keys "
+                f"beginning with {RESERVED_PREFIX!r}, and "
+                f"{', '.join(sorted(repr(k) for k in RESERVED_KEYS))}, are engine-owned"
+            )
+        if not _KEY_PATTERN.match(key):
+            raise ValueError(
+                f"attribution key {key!r} is invalid: keys must match "
+                f"[a-z][a-z0-9_-]{{0,62}}"
+            )
+        if not _VALUE_PATTERN.match(value):
+            raise ValueError(
+                f"attribution value for {key!r} is invalid: values must match "
+                f"[a-z0-9_-]{{0,63}}"
+            )
+
+
+def engine_attribution() -> dict[str, str]:
+    """The constant half of the engine's identity: what produced this query."""
+    from dataface import __version__
+
+    return {
+        # `app` matches dbt's own default query comment, which emits `app=dbt` — so a
+        # cost model can filter one key across both tools instead of two.
+        "app": "dataface",
+        "dft_version": _normalize(__version__),
+    }
+
+
+def connection_identity() -> dict[str, str]:
+    """The attribution stable enough to ride a pooled connection.
+
+    Engine constants plus the process surface — deliberately *not*
+    :func:`current_attribution`, which also carries the per-query scope. A pooled
+    connection is shared by every source with the same connection identity and a
+    worker holds it across renders, so anything written at connect time must be true
+    for every source and every query that will use it. The face, the query, and the
+    source's authored ``attribution:`` are none of those things; they ride the query
+    comment, which is rebuilt per call.
+    """
+    return {**engine_attribution(), **_process_surface}
+
+
+def current_attribution() -> dict[str, str]:
+    """The engine identity in effect: the process surface plus enclosing scopes."""
+    return {**_process_surface, **_runtime.get()}
+
+
+def set_surface(surface: str) -> None:
+    """Declare which Dataface entry point this process is: ``cli``, ``serve``, ``cloud``…
+
+    The surface is a property of the running process, not of a request or a session,
+    so it is set once at the entry point rather than threaded through every registry
+    construction. Nothing is assumed when no entry point declares one — the payload
+    omits ``dft_surface`` rather than inventing a value, so a cost model never reads a
+    surface nobody set.
+
+    Deliberately process-wide: unlike a tenant or a user, every session in a given
+    process shares the same entry point, so there is no cross-tenant leak here.
+    """
+    _process_surface[f"{RESERVED_PREFIX}surface"] = _normalize(surface)
+
+
+@contextmanager
+def attribute(pairs: Mapping[str, str], authored: Mapping[str, str]) -> Generator[None]:
+    """Establish attribution for every warehouse call made inside the scope.
+
+    *pairs* holds the engine dimensions this scope actually knows — a composition root
+    knows the surface but not yet the face; the execute boundary knows the face and
+    query. Scopes nest and merge, innermost wins, and a dimension nobody set is simply
+    absent from the payload rather than emitted empty. Keys are bare dimension names
+    (``face``, not ``dft_face``); the prefix is added here, which is what makes the
+    reserved namespace unreachable from anywhere else. An unknown name is a caller
+    bug, so it raises rather than silently vanishing.
+
+    *authored* is the resolved source's own ``attribution:`` block, already validated
+    at the compile boundary, merged in unprefixed. It rides this per-call scope rather
+    than being captured when the adapter is built: connection pools are shared by
+    every source with the same *connection* identity, so an adapter-captured value
+    would label one source's queries with a different source's team.
+
+    Values are normalized to the label charset here rather than at emission, so the
+    payload is already warehouse-safe wherever it is read.
+
+    Note for callers dispatching onto their own threads: ``ContextVar`` does not cross
+    ``ThreadPoolExecutor.submit`` on its own — pass ``contextvars.copy_context().run``
+    or the scope is invisible to the worker.
+    """
+    unknown = sorted(set(pairs) - SCOPE_DIMENSIONS)
+    if unknown:
+        raise ValueError(
+            f"unknown attribution dimension(s) {unknown}: "
+            f"expected any of {sorted(SCOPE_DIMENSIONS)}"
+        )
+    established = {
+        **dict(authored),
+        **{
+            f"{RESERVED_PREFIX}{name}": _normalize(value)
+            for name, value in pairs.items()
+        },
+    }
+    token = _runtime.set({**_runtime.get(), **established})
+    try:
+        yield
+    finally:
+        _runtime.reset(token)
+
+
+def _normalize(value: str) -> str:
+    """Coerce an engine-generated value into the label charset."""
+    return _NON_LABEL_CHARS.sub("-", value.strip().lower())[:_MAX_VALUE_LENGTH]