dataface 0.3.1.dev132__py3-none-any.whl → 0.3.2.dev111__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/__init__.py

@@ -28,8 +28,12 @@ Quick Start:
     ...     svg = render(face, executor, format="svg")
 """
 
+from __future__ import annotations
+
+import importlib
 import logging
 from importlib.metadata import version as _v
+from typing import TYPE_CHECKING, Any
 
 __version__ = _v("dataface")
 
@@ -41,29 +45,31 @@ logger = logging.getLogger("dataface")
 # Actual handlers should be configured by the application entry points (CLI, serve)
 logger.addHandler(logging.NullHandler())
 
-# Re-export from core for convenience
-from dataface.core import validate
-from dataface.core.compile import (
-    AnyQuery,
-    AuthoredFace,
-    CompilationError,
-    CompileResult,
-    Face,
-    Layout,
-    LayoutItem,
-    Variable,
-    compile,
-    compile_file,
-)
-from dataface.core.execute import (
-    ExecutionError,
-    Executor,
-)
-
-# Import from render submodule
-# Note: We import `render` function but this shadows `dataface.render` module access
-# Tests that need to patch `dataface.core.render.renderer` should import the module directly
-from dataface.core.render import RenderError, render
+if TYPE_CHECKING:
+    # Import-time-only: PEP 562 __getattr__ below resolves these lazily at
+    # runtime, so `import dataface` (or `import dataface.<anything>`, which
+    # always runs this file first) doesn't eagerly pull in the whole
+    # compile/execute/render stack just for this convenience re-export.
+    from dataface.core import validate as validate
+    from dataface.core.compile import (
+        AnyQuery as AnyQuery,
+        AuthoredFace as AuthoredFace,
+        CompilationError as CompilationError,
+        CompileResult as CompileResult,
+        Face as Face,
+        Layout as Layout,
+        LayoutItem as LayoutItem,
+        Variable as Variable,
+        compile as compile,
+        compile_file as compile_file,
+    )
+    from dataface.core.execute import (
+        ExecutionError as ExecutionError,
+        Executor as Executor,
+    )
+
+    # `render` shadows `dataface.render` module access — see _LAZY_ATTRS note below.
+    from dataface.core.render import RenderError as RenderError, render as render
 
 __all__ = [
     # Version
@@ -90,3 +96,44 @@ __all__ = [
     # Validate
     "validate",
 ]
+
+# name -> (module dotted path, attribute name in that module). PEP 562
+# __getattr__ below resolves these on first access instead of importing the
+# entire compile/execute/render stack just because something did
+# `import dataface` or `import dataface.<anything>` (this file runs first,
+# always, regardless of which submodule was actually requested).
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "validate": ("dataface.core", "validate"),
+    "AnyQuery": ("dataface.core.compile", "AnyQuery"),
+    "AuthoredFace": ("dataface.core.compile", "AuthoredFace"),
+    "CompilationError": ("dataface.core.compile", "CompilationError"),
+    "CompileResult": ("dataface.core.compile", "CompileResult"),
+    "Face": ("dataface.core.compile", "Face"),
+    "Layout": ("dataface.core.compile", "Layout"),
+    "LayoutItem": ("dataface.core.compile", "LayoutItem"),
+    "Variable": ("dataface.core.compile", "Variable"),
+    "compile": ("dataface.core.compile", "compile"),
+    "compile_file": ("dataface.core.compile", "compile_file"),
+    "ExecutionError": ("dataface.core.execute", "ExecutionError"),
+    "Executor": ("dataface.core.execute", "Executor"),
+    # `render` shadows `dataface.render` module access (pre-existing, not
+    # introduced by laziness) — tests patching render internals import
+    # dataface.core.render.renderer directly instead.
+    "RenderError": ("dataface.core.render", "RenderError"),
+    "render": ("dataface.core.render", "render"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_path, attr_name = _LAZY_ATTRS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = importlib.import_module(module_path)
+    value = getattr(module, attr_name)
+    globals()[name] = value  # cache: repeated access is O(1) and `is` identity holds
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_ATTRS))

dataface/agent_api/__init__.py

@@ -36,70 +36,83 @@ rendering) belongs here, not in the CLI or MCP layer.  Code review blocks
 CLI/MCP files that contain logic beyond parse-and-dispatch.
 """
 
-from dataface.agent_api import skills as skills
-from dataface.agent_api._paths import (
-    project_sources_for_face as project_sources_for_face,
-)
-from dataface.agent_api.describe import (
-    DescribeFaceArgs,
-    DescribeFaceResult,
-    describe_face,
-)
-from dataface.agent_api.docs import DocsArgs, DocsResult, DocsSearchHit, Topic
-from dataface.agent_api.init import (
-    InitResult as InitResult,
-    init_project as init_project,
-)
-from dataface.agent_api.migrate import (
-    MigrateError as MigrateError,
-    MigrateSummary as MigrateSummary,
-    migrate_paths as migrate_paths,
-)
-from dataface.agent_api.project_session import ProjectSession as ProjectSession
-from dataface.agent_api.query import QueryFaceResult, query_face
-from dataface.agent_api.schema_hints import (
-    SchemaHints as SchemaHints,
-    schema_hints as schema_hints,
-)
-from dataface.agent_api.validate import (
-    ValidateDashboardArgs,
-    ValidateResult,
-)
-from dataface.agent_api.validate_query import (
-    QueryDiagnostic as QueryDiagnostic,
-    validate_query as validate_query,
-)
-from dataface.core.compile.compiler import (
-    CompileResult as CompileResult,
-    compile as compile,
-)
-from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
-from dataface.core.dashboard import (
-    RenderedDashboard as RenderedDashboard,
-    render_dashboard as render_dashboard,
-)
-from dataface.core.diagnostics import Diagnostic as Diagnostic
-
-# Execution extension seams: the protocols a composition root injects, plus the
-# resolver base impls it subclasses. Re-exported so roots (CLI, MCP, serve,
-# Cloud, A lIe, Playground) compose against agent_api, not dataface.core.*.
-# AdapterRegistry is intentionally absent — it is built via ProjectSession /
-# build_adapter_registry, not subclassed as an extension contract.
-from dataface.core.execute.cache_backend import QueryResultCache as QueryResultCache
-from dataface.core.execute.observability import WarehouseObserver as WarehouseObserver
-from dataface.core.execute.source_resolver import (
-    AllowlistedSourceResolver as AllowlistedSourceResolver,
-    DefaultSourceResolver as DefaultSourceResolver,
-    SourceResolver as SourceResolver,
-)
-from dataface.core.fonts import get_inter_font_path as get_inter_font_path
-from dataface.core.project import (
-    FaceFile as FaceFile,
-    InMemoryFace as InMemoryFace,
-    Project as Project,
-)
-from dataface.core.render.board_links import LinkContext as LinkContext
-from dataface.core.render.errors import RenderError as RenderError
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Import-time-only: PEP 562 __getattr__ below resolves these lazily at
+    # runtime. Kept here so mypy/pyright still see concrete types instead of
+    # falling back to Any on every re-export.
+    from dataface.agent_api import skills as skills
+    from dataface.agent_api._paths import (
+        project_sources_for_face as project_sources_for_face,
+    )
+    from dataface.agent_api.describe import (
+        DescribeFaceArgs as DescribeFaceArgs,
+        DescribeFaceResult as DescribeFaceResult,
+        describe_face as describe_face,
+    )
+    from dataface.agent_api.docs import (
+        DocsArgs as DocsArgs,
+        DocsResult as DocsResult,
+        DocsSearchHit as DocsSearchHit,
+        Topic as Topic,
+    )
+    from dataface.agent_api.init import (
+        InitResult as InitResult,
+        init_project as init_project,
+    )
+    from dataface.agent_api.migrate import (
+        MigrateError as MigrateError,
+        MigrateSummary as MigrateSummary,
+        migrate_paths as migrate_paths,
+    )
+    from dataface.agent_api.project_session import ProjectSession as ProjectSession
+    from dataface.agent_api.query import (
+        QueryFaceResult as QueryFaceResult,
+        query_face as query_face,
+    )
+    from dataface.agent_api.schema_hints import SchemaHints as SchemaHints
+    from dataface.agent_api.validate import (
+        ValidateDashboardArgs as ValidateDashboardArgs,
+        ValidateResult as ValidateResult,
+    )
+    from dataface.agent_api.validate_query import QueryDiagnostic as QueryDiagnostic
+    from dataface.core.attribution import set_surface as set_surface
+    from dataface.core.compile.compiler import (
+        CompileResult as CompileResult,
+        compile as compile,
+    )
+    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
+    from dataface.core.execute.cache_backend import (
+        QueryResultCache as QueryResultCache,
+    )
+    from dataface.core.execute.observability import (
+        WarehouseObserver as WarehouseObserver,
+    )
+    from dataface.core.execute.source_resolver import (
+        AllowlistedSourceResolver as AllowlistedSourceResolver,
+        DefaultSourceResolver as DefaultSourceResolver,
+        SourceResolver as SourceResolver,
+    )
+    from dataface.core.fonts import get_fonts_dir as get_fonts_dir
+    from dataface.core.project import (
+        FaceFile as FaceFile,
+        InMemoryFace as InMemoryFace,
+        Project as Project,
+    )
+    from dataface.core.render.board_links import LinkContext as LinkContext
+    from dataface.core.render.errors import RenderError as RenderError
 
 __all__ = [
     "compile",
@@ -118,11 +131,13 @@ __all__ = [
     "MigrateSummary",
     "Project",
     "ProjectSession",
+    "set_surface",
     "ProjectSourcesConfig",
     "QueryDiagnostic",
     "QueryFaceResult",
     "RenderedDashboard",
     "RenderError",
+    "RenderFormat",
     "SchemaHints",
     "Topic",
     "ValidateDashboardArgs",
@@ -134,11 +149,94 @@ __all__ = [
     "SourceResolver",
     "WarehouseObserver",
     "describe_face",
-    "get_inter_font_path",
+    "get_fonts_dir",
     "init_project",
     "migrate_paths",
     "query_face",
     "render_dashboard",
-    "schema_hints",
-    "validate_query",
 ]
+
+# `schema_hints` and `validate_query` (the functions) are deliberately NOT
+# re-exported here: both names collide with their own defining submodule
+# (`dataface.agent_api.schema_hints`, `dataface.agent_api.validate_query`).
+# Importing that submodule for any reason binds it onto this package under
+# that exact name as a side effect of Python's own import machinery — a
+# rebind PEP 562 __getattr__ cannot see or prevent — so a lazy alias sharing
+# a submodule's leaf name silently flips from function to module depending on
+# import order. Import the function directly from its submodule instead:
+# `from dataface.agent_api.schema_hints import schema_hints`,
+# `from dataface.agent_api.validate_query import validate_query`.
+
+# name -> (module dotted path, attribute name in that module; "" means the
+# module itself). PEP 562 __getattr__ below resolves these on first access
+# instead of importing every submodule (and the compile/execute/dbt_common
+# stack several of them drag in) eagerly at `import dataface.agent_api` time.
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "skills": ("dataface.agent_api.skills", ""),
+    "project_sources_for_face": (
+        "dataface.agent_api._paths",
+        "project_sources_for_face",
+    ),
+    "DescribeFaceArgs": ("dataface.agent_api.describe", "DescribeFaceArgs"),
+    "DescribeFaceResult": ("dataface.agent_api.describe", "DescribeFaceResult"),
+    "describe_face": ("dataface.agent_api.describe", "describe_face"),
+    "DocsArgs": ("dataface.agent_api.docs", "DocsArgs"),
+    "DocsResult": ("dataface.agent_api.docs", "DocsResult"),
+    "DocsSearchHit": ("dataface.agent_api.docs", "DocsSearchHit"),
+    "Topic": ("dataface.agent_api.docs", "Topic"),
+    "InitResult": ("dataface.agent_api.init", "InitResult"),
+    "init_project": ("dataface.agent_api.init", "init_project"),
+    "MigrateError": ("dataface.agent_api.migrate", "MigrateError"),
+    "MigrateSummary": ("dataface.agent_api.migrate", "MigrateSummary"),
+    "migrate_paths": ("dataface.agent_api.migrate", "migrate_paths"),
+    "ProjectSession": ("dataface.agent_api.project_session", "ProjectSession"),
+    "QueryFaceResult": ("dataface.agent_api.query", "QueryFaceResult"),
+    "query_face": ("dataface.agent_api.query", "query_face"),
+    "SchemaHints": ("dataface.agent_api.schema_hints", "SchemaHints"),
+    "ValidateDashboardArgs": ("dataface.agent_api.validate", "ValidateDashboardArgs"),
+    "ValidateResult": ("dataface.agent_api.validate", "ValidateResult"),
+    "QueryDiagnostic": ("dataface.agent_api.validate_query", "QueryDiagnostic"),
+    "set_surface": ("dataface.core.attribution", "set_surface"),
+    "compile": ("dataface.core.compile.compiler", "compile"),
+    "CompileResult": ("dataface.core.compile.compiler", "CompileResult"),
+    "ProjectSourcesConfig": ("dataface.core.compile.config", "ProjectSourcesConfig"),
+    "RenderedDashboard": ("dataface.core.dashboard", "RenderedDashboard"),
+    "RenderFormat": ("dataface.core.render_format", "RenderFormat"),
+    "render_dashboard": ("dataface.core.dashboard", "render_dashboard"),
+    "Diagnostic": ("dataface.core.diagnostics", "Diagnostic"),
+    "QueryResultCache": ("dataface.core.execute.cache_backend", "QueryResultCache"),
+    "WarehouseObserver": (
+        "dataface.core.execute.observability",
+        "WarehouseObserver",
+    ),
+    "AllowlistedSourceResolver": (
+        "dataface.core.execute.source_resolver",
+        "AllowlistedSourceResolver",
+    ),
+    "DefaultSourceResolver": (
+        "dataface.core.execute.source_resolver",
+        "DefaultSourceResolver",
+    ),
+    "SourceResolver": ("dataface.core.execute.source_resolver", "SourceResolver"),
+    "get_fonts_dir": ("dataface.core.fonts", "get_fonts_dir"),
+    "FaceFile": ("dataface.core.project", "FaceFile"),
+    "InMemoryFace": ("dataface.core.project", "InMemoryFace"),
+    "Project": ("dataface.core.project", "Project"),
+    "LinkContext": ("dataface.core.render.board_links", "LinkContext"),
+    "RenderError": ("dataface.core.render.errors", "RenderError"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_path, attr_name = _LAZY_ATTRS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = importlib.import_module(module_path)
+    value = module if not attr_name else getattr(module, attr_name)
+    globals()[name] = value  # cache: repeated access is O(1) and `is` identity holds
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_ATTRS))

dataface/agent_api/_paths.py

@@ -5,10 +5,10 @@ from __future__ import annotations
 import os
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
 
 # tach-ignore(agent_api->cli: runtime host-type guard in resolve_face_or_error / _relpath_for_fs_location; the local-filesystem check needs a non-cli signal on Project — deferred)
 from dataface.cli.filesystem_project import FilesystemProject
-from dataface.core.compile.config import ProjectSourcesConfig
 from dataface.core.diagnostics import (
     ERR_FILE_NOT_FOUND,
     ERR_INTERNAL,
@@ -21,12 +21,18 @@ from dataface.core.project import (
     Project,
     ProjectPath,
     assert_relpath,
+    posix_relpath,
 )
 from dataface.core.project_roots import (
+    DFT_ROOT_MARKERS as DFT_ROOT_MARKERS,
     find_dft_root as find_dft_root,
     find_project_root as find_project_root,
+    find_repo_root as find_repo_root,
 )
 
+if TYPE_CHECKING:
+    from dataface.core.compile.config import ProjectSourcesConfig
+
 
 def resolve_face_relpath(relpath: PurePosixPath, project: Project) -> ProjectPath:
     """Project-relative face identity -> ProjectPath, with the faces-first retry.
@@ -83,12 +89,12 @@ def _relpath_for_fs_location(path: Path, project: Project) -> str:
     root = project.root
     resolved = path.resolve()
     try:
-        return str(resolved.relative_to(root))
+        return posix_relpath(resolved, root)
     except ValueError:
         pass
     normalized = Path(os.path.normpath(path.absolute()))
     try:
-        return str(normalized.relative_to(root))
+        return posix_relpath(normalized, root)
     except ValueError:
         raise ValueError(f"Path {path!r} is outside project root {root!r}") from None
 

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,