dataface 0.1.5.dev206__py3-none-any.whl → 0.1.5.dev215__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -346,7 +346,7 @@ queries:
       - [Bob, 87.1]
 ```
 
-Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema_resolver` is internal-only and not part of the authored surface.
+Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema` is internal-only and not part of the authored surface.
 
 Common fields (all query types):
 

dataface/agent_api/docs/yaml-reference.md

@@ -72,7 +72,7 @@ AuthoredQuery definition from YAML.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `type` | enum: "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema_resolver" | ✓ | Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema_resolver. |
+| `type` | enum: "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema" | ✓ | Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema. |
 | `source` | str \| dict[str, Any] | ✓ | Database source reference (name string) or inline source config dict. |
 | `target` | str | ✓ | dbt target name for dbt_model queries (defaults to 'dev'). |
 | `sql` | str | ✓ | SQL query string. Supports Jinja2 templates referencing variables. |
@@ -92,9 +92,9 @@ AuthoredQuery definition from YAML.
 | `filter` | dict[str, Any] | ✓ | Row-level filter applied to CSV or values data. |
 | `delimiter` | str | ✓ | Column delimiter for CSV queries. Default: comma (','). |
 | `encoding` | str | ✓ | File encoding for CSV queries. Default: UTF-8. |
-| `schema` | str | ✓ | Schema name for schema_resolver queries (YAML key: schema). |
-| `table` | str | ✓ | Table name for schema_resolver queries. |
-| `column` | str | ✓ | Column name for schema_resolver queries. |
+| `schema` | str | ✓ | Schema name for schema queries (YAML key: schema). |
+| `table` | str | ✓ | Table name for schema queries. |
+| `column` | str | ✓ | Column name for schema queries. |
 | `rows` | list[dict[str, Any]] | ✓ | Inline data rows for values-type queries (list of row dicts). |
 | `values` | list[list[Any]] | ✓ | Inline column-oriented data for values-type queries (list of lists). |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |

dataface/agent_api/project.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import sys
 from dataclasses import dataclass
+from functools import cached_property
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -55,7 +56,6 @@ class Project:
     project_root: Path
     cache: DuckDBCache | None
     _owns_registry: bool
-    _adapter_registry: AdapterRegistry | None
     _read_only: bool
     _dbt_project_path: Path | None
     _connection_string: str | None
@@ -64,8 +64,8 @@ class Project:
     _duckdb_config: dict[str, Any] | None
     _allow_external_access_in_readonly: bool
     _resolver: SourceResolver | None
-    _sources_cache: ProjectSourcesConfig | None
-    _warnings_ignore_cache: frozenset[str] | None
+    _sources: ProjectSourcesConfig
+    _warnings_ignore: frozenset[str]
 
     def __init__(
         self,
@@ -78,7 +78,10 @@ class Project:
         # We own the registry only when we'll lazy-build it ourselves. An injected
         # registry belongs to the caller; we use it but don't close it on their behalf.
         self._owns_registry = adapter_registry is None
-        self._adapter_registry = adapter_registry
+        if adapter_registry is not None:
+            # cached_property stores in __dict__; pre-populating makes the descriptor
+            # short-circuit the build on first access.
+            self.__dict__["adapter_registry"] = adapter_registry
         self._read_only = True
         self._dbt_project_path = None
         self._connection_string = None
@@ -87,8 +90,8 @@ class Project:
         self._duckdb_config = None
         self._allow_external_access_in_readonly = False
         self._resolver = None
-        self._sources_cache = None
-        self._warnings_ignore_cache = None
+        self._sources = get_project_sources(self.project_root)
+        self._warnings_ignore = get_project_warnings_ignore(self.project_root)
 
     @classmethod
     def open(
@@ -133,7 +136,7 @@ class Project:
     def __exit__(self, *exc_info: object) -> None:
         self.close()
 
-    @property
+    @cached_property
     def adapter_registry(self) -> AdapterRegistry:
         """Lazily build the registry on first access; cached thereafter.
 
@@ -141,57 +144,49 @@ class Project:
         own it (i.e. it was not injected at construction time).
         When constructed with an injected registry, returns it directly.
         """
-        if self._adapter_registry is None:
-            self._adapter_registry = build_adapter_registry(
-                self.project_root,
-                read_only=self._read_only,
-                dbt_project_path=self._dbt_project_path,
-                connection_string=self._connection_string,
-                profile_type=self._dialect,
-                target=self._target,
-                duckdb_config=self._duckdb_config,
-                allow_external_access_in_readonly=self._allow_external_access_in_readonly,
-                resolver=self._resolver,
-            )
-        return self._adapter_registry
+        return build_adapter_registry(
+            self.project_root,
+            read_only=self._read_only,
+            dbt_project_path=self._dbt_project_path,
+            connection_string=self._connection_string,
+            profile_type=self._dialect,
+            target=self._target,
+            duckdb_config=self._duckdb_config,
+            allow_external_access_in_readonly=self._allow_external_access_in_readonly,
+            resolver=self._resolver,
+        )
 
     def refresh(self) -> None:
         """Policy-free rebuild primitive.
 
         For projects opened via ``open()``: closes the current registry (if built)
-        and clears it so the next access rebuilds from disk. Also clears the
-        sources and warnings_ignore caches so the next call re-reads from disk.
+        and clears it so the next access rebuilds from disk. Also re-reads
+        sources and warnings_ignore from disk.
 
         For projects constructed with an injected ``adapter_registry``: skips the
-        registry rebuild (build arguments are not available), but still clears the
-        config caches.
+        registry rebuild (build arguments are not available), but still re-reads
+        the config fields.
         """
-        if self._owns_registry:
-            if self._adapter_registry is not None:
-                self._adapter_registry.close()
-                self._adapter_registry = None
-        self._sources_cache = None
-        self._warnings_ignore_cache = None
+        if self._owns_registry and "adapter_registry" in self.__dict__:
+            self.adapter_registry.close()
+            del self.__dict__["adapter_registry"]
+        self._sources = get_project_sources(self.project_root)
+        self._warnings_ignore = get_project_warnings_ignore(self.project_root)
 
     def close(self) -> None:
         """Close the adapter registry iff we own it. The cache is the caller's to close."""
-        if self._owns_registry and self._adapter_registry is not None:
-            self._adapter_registry.close()
-            self._adapter_registry = None
-
-    # ── Config accessors ─────────────────────────────────────────────────────
+        if self._owns_registry and "adapter_registry" in self.__dict__:
+            self.adapter_registry.close()
+            del self.__dict__["adapter_registry"]
 
+    # Read-only views: project lifecycle owns these; external writers go through refresh().
+    @property
     def sources(self) -> ProjectSourcesConfig:
-        """Project-level sources config. Cached on the instance; refresh() invalidates."""
-        if self._sources_cache is None:
-            self._sources_cache = get_project_sources(self.project_root)
-        return self._sources_cache
+        return self._sources
 
+    @property
     def warnings_ignore(self) -> frozenset[str]:
-        """Warning codes to suppress. Cached on the instance; refresh() invalidates."""
-        if self._warnings_ignore_cache is None:
-            self._warnings_ignore_cache = get_project_warnings_ignore(self.project_root)
-        return self._warnings_ignore_cache
+        return self._warnings_ignore
 
     # ── Verb forwarders ──────────────────────────────────────────────────────
 
@@ -300,6 +295,7 @@ class Project:
             variables=variables,
             adapter_registry=self.adapter_registry,
             project_dir=self.project_root,
+            project_sources=self.sources,
             duckdb_cache=self.cache,
             format=format,
             use_cache=use_cache,
@@ -308,5 +304,5 @@ class Project:
             scale=scale,
             ignore_codes=ignore_codes,
             max_workers=max_workers,
-            warnings_ignore=self.warnings_ignore(),
+            warnings_ignore=self.warnings_ignore,
         )

dataface/ai/tools/__init__.py

@@ -113,7 +113,7 @@ def _handle_render(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, An
         adapter_registry=ctx.project.adapter_registry,
         duckdb_cache=ctx.project.cache,
         server_port=ctx.server_port,
-        warnings_ignore=ctx.project.warnings_ignore(),
+        warnings_ignore=ctx.project.warnings_ignore,
     ).model_dump(mode="json", exclude_none=True)
 
 

dataface/cli/commands/serve.py

@@ -7,6 +7,10 @@ from pathlib import Path
 import typer
 import uvicorn
 
+from dataface.cli._error_format import print_structured_errors
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.errors import DF_SERVE_STARTUP_FAILED
+
 
 def serve_command(
     port: int | None = None,
@@ -52,8 +56,8 @@ def serve_command(
     # Apply DFT_DEFAULT_THEME before anything else — fails fast on invalid names.
     try:
         apply_default_theme_from_env()
-    except ValueError as e:
-        typer.echo(f"Error: {e}", err=True)
+    except DatafaceError as e:
+        print_structured_errors([e.to_structured()])
         raise typer.Exit(1) from None
 
     # Resolve port: --port > DFT_PORT > dataface.yml > hash(project_dir)
@@ -108,6 +112,7 @@ def serve_command(
     except KeyboardInterrupt:
         typer.echo("\n👋 Server stopped")
         sys.exit(0)
-    except Exception as e:  # noqa: BLE001
-        typer.echo(f"Error starting server: {e}", err=True)
+    except Exception as e:  # noqa: BLE001 — uvicorn surface
+        err = DatafaceError.from_code(DF_SERVE_STARTUP_FAILED, detail=str(e))
+        print_structured_errors([err.to_structured()])
         raise typer.Exit(1) from None

dataface/core/compile/__init__.py

@@ -20,7 +20,11 @@ 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.compiler import (
+    CompileResult,
+    compile,
+    compile_file,
+)
 from dataface.core.compile.config import (
     AccessConfig,
     MetaConfig,

dataface/core/compile/compiler.py

@@ -38,6 +38,10 @@ import yaml
 from pydantic import ValidationError as PydanticValidationError
 
 from dataface.core.compile.authoring_warnings import detect_authoring_warnings
+from dataface.core.compile.config import (
+    ProjectSourcesConfig,
+    get_project_sources,
+)
 from dataface.core.compile.errors import (
     CompilationError,
     JinjaError,
@@ -80,35 +84,6 @@ def _to_plain_dict(obj: Any) -> Any:
     return obj
 
 
-def resolve_project_source_paths(
-    sources: dict[str, dict[str, Any]],
-    project_dir: Path,
-) -> dict[str, dict[str, Any]]:
-    """Resolve relative file/database paths in project-level source configs."""
-    resolved_sources: dict[str, dict[str, Any]] = {}
-
-    for name, config in sources.items():
-        resolved_config = dict(config)
-        source_type = resolved_config.get("type")
-
-        if source_type == "duckdb":
-            path_value = resolved_config.get("path")
-            if (
-                isinstance(path_value, str)
-                and path_value != ":memory:"
-                and not Path(path_value).is_absolute()
-            ):
-                resolved_config["path"] = str((project_dir / path_value).resolve())
-        elif source_type in {"csv", "parquet", "json"}:
-            file_value = resolved_config.get("file")
-            if isinstance(file_value, str) and not Path(file_value).is_absolute():
-                resolved_config["file"] = str((project_dir / file_value).resolve())
-
-        resolved_sources[name] = resolved_config
-
-    return resolved_sources
-
-
 @dataclass
 class CompileResult:
     """Result of compilation.
@@ -160,7 +135,7 @@ def compile(
     yaml_content: str,
     options: dict[str, Any] | None = None,
     base_dir: Path | None = None,
-    project_dir: Path | None = None,
+    project_sources: ProjectSourcesConfig | None = None,
 ) -> CompileResult:
     """Compile YAML content to a Face.
 
@@ -177,7 +152,9 @@ def compile(
         yaml_content: YAML string to compile
         options: Optional compilation options
         base_dir: Base directory for resolving file references
-        project_dir: Project directory for resolving project-level sources
+        project_sources: Project-level sources, ready to use. Callers that
+            hold a ``Project`` thread ``project.sources``; one-shot callers
+            pre-load via ``get_project_sources(project_dir)``.
 
     Returns:
         CompileResult with compiled face or errors
@@ -234,13 +211,8 @@ def compile(
     # ════════════════════════════════════════════════════════════════════
     # STEP 3: Get Default Source and Extract Named Sources
     # ════════════════════════════════════════════════════════════════════
-    # Get project-level sources when available so named source references and
-    # project defaults behave consistently for file-based compiles.
-    project_sources = None
-    if project_dir is not None:
-        from dataface.core.compile.config import get_project_sources
-
-        project_sources = get_project_sources(project_dir)
+    # project_sources is supplied by the caller (Project verb or file-based
+    # entry point); its sources dict is already path-resolved.
 
     # Get the face's default source to pass to query normalization.
     default_source = face.get_default_source()
@@ -249,12 +221,9 @@ def compile(
 
     # Extract named source configurations from the sources section
     # These are used to resolve source references in queries (e.g., source: profiles)
-    sources_registry = {}
+    sources_registry: dict[str, dict[str, Any]] = {}
     if project_sources is not None:
-        assert project_dir is not None
-        sources_registry.update(
-            resolve_project_source_paths(project_sources.sources, project_dir)
-        )
+        sources_registry.update(project_sources.sources)
     sources_registry.update(_extract_sources(face))
 
     # ════════════════════════════════════════════════════════════════════
@@ -446,6 +415,7 @@ def compile_file(
     options: dict[str, Any] | None = None,
     apply_meta: bool = True,
     root_path: Path | None = None,
+    project_sources: ProjectSourcesConfig | None = None,
 ) -> CompileResult:
     """Compile a YAML file to a Face.
 
@@ -457,6 +427,9 @@ def compile_file(
         options: Optional compilation options
         apply_meta: If True, resolve and apply meta.yaml chain (default: True)
         root_path: Project root for meta resolution (default: auto-detect)
+        project_sources: Pre-loaded project sources. When None, ``compile_file``
+            loads once from the derived project root. ``Project.render_dashboard``
+            threads its cached ``self.sources`` here to avoid the disk read.
 
     Returns:
         CompileResult with compiled face or errors
@@ -541,12 +514,15 @@ def compile_file(
                 e,
             )
 
-    project_dir = root_path
-    if project_dir is None:
-        from dataface.core.project_roots import discover_render_context
+    if project_sources is None:
+        project_dir = root_path
+        if project_dir is None:
+            from dataface.core.project_roots import discover_render_context
+
+            compile_boundary = Path(file_path.anchor) if file_path.anchor else None
+            project_dir, _ = discover_render_context(file_path.parent, compile_boundary)
 
-        compile_boundary = Path(file_path.anchor) if file_path.anchor else None
-        project_dir, _ = discover_render_context(file_path.parent, compile_boundary)
+        project_sources = get_project_sources(project_dir)
 
     # Thread meta lint config through to compile for query diagnostics
     compile_options = dict(options) if options else {}
@@ -557,7 +533,7 @@ def compile_file(
         yaml_content,
         options=compile_options,
         base_dir=file_path.parent,
-        project_dir=project_dir,
+        project_sources=project_sources,
     )
     # Stamp file path and add validate next_command on each compile error so
     # UI surfaces and CLI can surface "dft validate <file>" without re-deriving the path.

dataface/core/compile/config.py

@@ -484,10 +484,12 @@ def get_palette(name: str = "default") -> list[str]:
 
 
 def get_project_sources(project_dir: Path) -> ProjectSourcesConfig:
-    """Get project-level sources configuration.
+    """Get project-level sources configuration with file paths absolutized.
 
     Reads disk every call — no cache. _sources.yaml / dataface.yml edits are
-    visible to the next call.
+    visible to the next call. Relative ``path:`` (duckdb) and ``file:`` (csv /
+    parquet / json) values resolve against ``project_dir`` so callers can pass
+    the returned config straight into ``compile()`` without further work.
     """
     project_dir = project_dir.resolve()
     config = get_config()
@@ -542,10 +544,37 @@ def get_project_sources(project_dir: Path) -> ProjectSourcesConfig:
 
     return ProjectSourcesConfig(
         default=default_source,
-        sources=_normalize_project_sources(all_sources),
+        sources=_absolutize_source_paths(
+            _normalize_project_sources(all_sources), project_dir
+        ),
     )
 
 
+def _absolutize_source_paths(
+    sources: dict[str, dict[str, Any]],
+    project_dir: Path,
+) -> dict[str, dict[str, Any]]:
+    """Absolutize relative file/database paths against ``project_dir``."""
+    resolved: dict[str, dict[str, Any]] = {}
+    for name, config in sources.items():
+        cfg = dict(config)
+        source_type = cfg.get("type")
+        if source_type == "duckdb":
+            path_value = cfg.get("path")
+            if (
+                isinstance(path_value, str)
+                and path_value != ":memory:"
+                and not Path(path_value).is_absolute()
+            ):
+                cfg["path"] = str((project_dir / path_value).resolve())
+        elif source_type in {"csv", "parquet", "json"}:
+            file_value = cfg.get("file")
+            if isinstance(file_value, str) and not Path(file_value).is_absolute():
+                cfg["file"] = str((project_dir / file_value).resolve())
+        resolved[name] = cfg
+    return resolved
+
+
 # ============================================================================
 # PROJECT WARNINGS IGNORE
 # ============================================================================

dataface/core/compile/models/query/authored.py

@@ -97,13 +97,11 @@ class AuthoredQuery(BaseModel):
     model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
     type: (
-        Literal[
-            "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema_resolver"
-        ]
+        Literal["sql", "metricflow", "dbt_model", "http", "csv", "values", "schema"]
         | None
     ) = Field(
         default=None,
-        description="Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema_resolver.",
+        description="Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema.",
     )
 
     # Source field - can be a string reference or inline source config
@@ -194,21 +192,21 @@ class AuthoredQuery(BaseModel):
         description="File encoding for CSV queries. Default: UTF-8.",
     )
 
-    # schema_resolver fields
+    # schema fields
     # alias="schema" so YAML authors write `schema: analytics`; Python code uses
     # schema_name to avoid shadowing BaseModel.schema (a Pydantic v2 legacy classmethod).
     schema_name: str | None = Field(
         default=None,
         alias="schema",
-        description="Schema name for schema_resolver queries (YAML key: schema).",
+        description="Schema name for schema queries (YAML key: schema).",
     )
     table: str | None = Field(
         default=None,
-        description="Table name for schema_resolver queries.",
+        description="Table name for schema queries.",
     )
     column: str | None = Field(
         default=None,
-        description="Column name for schema_resolver queries.",
+        description="Column name for schema queries.",
     )
 
     # Values fields (inline data)

dataface/core/compile/models/query/normalized.py

@@ -494,7 +494,7 @@ class DbtModelQuery(Query):
         return f"dbt Model: {self.model}"
 
 
-class SchemaResolverQuery(Query):
+class SchemaQuery(Query):
     """Query the LayeredSchemaResolver in-process.
 
     Dispatches to list_schemas / list_tables / profile_table / profile_column
@@ -537,24 +537,24 @@ class SchemaResolverQuery(Query):
     def _no_jinja(cls, v: Any) -> Any:
         if isinstance(v, str) and any(tok in v for tok in ("{{", "{%", "{#")):
             raise ValueError(
-                "schema_resolver fields must be literal strings; "
+                "schema fields must be literal strings; "
                 "Jinja templates ({{ }}, {% %}, {# #}) are not supported."
             )
         return v
 
     @model_validator(mode="after")
-    def _field_prerequisites(self) -> "SchemaResolverQuery":
+    def _field_prerequisites(self) -> "SchemaQuery":
         if self.table is not None and self.schema_name is None:
-            raise ValueError("schema_resolver: 'table' requires 'schema' to be set")
+            raise ValueError("schema: 'table' requires 'schema' to be set")
         if self.column is not None and self.table is None:
             raise ValueError(
-                "schema_resolver: 'column' requires 'table' (and 'schema') to be set"
+                "schema: 'column' requires 'table' (and 'schema') to be set"
             )
         return self
 
     @property
     def query_type(self) -> str:
-        return "schema_resolver"
+        return "schema"
 
     @property
     def source_description(self) -> str:
@@ -565,7 +565,7 @@ class SchemaResolverQuery(Query):
             parts.append(self.table)
         if self.column:
             parts.append(self.column)
-        return f"schema_resolver: {'.'.join(parts)}"
+        return f"schema: {'.'.join(parts)}"
 
 
 # ============================================================================
@@ -582,7 +582,7 @@ AnyQuery = (
     | HttpQuery
     | DbtModelQuery
     | ValuesQuery
-    | SchemaResolverQuery
+    | SchemaQuery
 )
 
 
@@ -594,7 +594,7 @@ VALID_QUERY_TYPES: set[str] = {
     "http",
     "dbt_model",
     "values",
-    "schema_resolver",
+    "schema",
 }
 
 
@@ -715,13 +715,13 @@ def is_values_query(query: AnyQuery) -> TypeGuard[ValuesQuery]:
     return query.query_type == "values"
 
 
-def is_schema_resolver_query(query: AnyQuery) -> TypeGuard[SchemaResolverQuery]:
-    """Type guard for schema resolver queries.
+def is_schema_query(query: AnyQuery) -> TypeGuard[SchemaQuery]:
+    """Type guard for schema queries.
 
     Args:
         query: Any compiled query
 
     Returns:
-        True if query is a SchemaResolverQuery
+        True if query is a SchemaQuery
     """
-    return query.query_type == "schema_resolver"
+    return query.query_type == "schema"

dataface/core/compile/normalize_queries.py

@@ -17,7 +17,7 @@ from dataface.core.compile.models.query.normalized import (
     DbtModelQuery,
     HttpQuery,
     MetricFlowQuery,
-    SchemaResolverQuery,
+    SchemaQuery,
     SqlQuery,
     ValuesQuery,
     is_sql_query,
@@ -62,7 +62,7 @@ def normalize_query(
             HttpQuery,
             DbtModelQuery,
             ValuesQuery,
-            SchemaResolverQuery,
+            SchemaQuery,
         ),
     ):
         return query_def
@@ -90,13 +90,13 @@ def normalize_query(
         query_type = query_dict.pop("type")
 
         # Apply default source if query doesn't have one.
-        # ValuesQuery is inline data; SchemaResolverQuery's source is a dbt source name,
+        # ValuesQuery is inline data; SchemaQuery's source is a dbt source name,
         # not a connection reference; HttpQuery uses url, not source — all three are excluded.
         has_source = query_dict.get("source") is not None
         if (
             not has_source
             and default_source
-            and query_type not in {"values", "dbt_model", "schema_resolver", "http"}
+            and query_type not in {"values", "dbt_model", "schema", "http"}
         ):
             query_dict["source"] = default_source
 
@@ -140,8 +140,8 @@ def normalize_query(
             query = DbtModelQuery(**query_dict)
         elif query_type == "values":
             query = ValuesQuery(**query_dict)
-        elif query_type == "schema_resolver":
-            query = SchemaResolverQuery(**query_dict)
+        elif query_type == "schema":
+            query = SchemaQuery(**query_dict)
         else:
             # Default to SQL
             query = SqlQuery(**query_dict)