dataface 0.3.2.dev22__py3-none-any.whl → 0.3.2.dev150__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -252,8 +252,9 @@ aliases:
 ```
 
 Rules:
-- An alias must not collide with a real face file path — the server raises an error at startup if it does.
-- Each alias must be unique across the project — two faces claiming the same alias is a startup error.
+- Every alias must be absolute (leading `/`) — a relative entry fails validation on that face.
+- An alias must not collide with a real face file path — `dft serve` raises an error at startup if it does.
+- Each alias must be unique across the project — two faces claiming the same alias is a startup error under `dft serve`. A host with no startup step resolves a duplicate to the first face by slug instead of reporting it.
 - Aliasing a generated system route (data or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
 
 #### Parameterized aliases (capture a path segment into a variable)
@@ -613,7 +614,11 @@ Each block below shows the minimum-viable shape for one chart type. They are sta
 type: bar
 x: category
 y: value
-color: group           # Optional second dimension; stacks by default
+color: group           # Optional second dimension; grouped side by side by default
+style:
+  orientation: vertical  # vertical = column chart; horizontal = horizontal bar chart.
+                          # Auto-resolves from x's column type when omitted: categorical x → horizontal.
+  stack: zero            # see the stack table under "area" — bar takes the same values
 
 # line — temporal/ordered x, numeric y
 type: line
@@ -625,8 +630,14 @@ color: segment         # Optional: one line per segment
 type: area
 x: date
 y: value
+color: segment         # Required for stacking — stack modes split by this field
 style:
-  stack: normalize     # 100% stacked
+  # stack names the shape you get. All four values work on bar and area alike:
+  stack: zero          # stacked
+  # stack: none        # overlapping — bar groups side by side, area overlays.
+                        # The default when color: is set.
+  # stack: normalize   # 100% stacked — every column fills the full height
+  # stack: center      # streamgraph — stacked around a centered baseline
 
 # scatter — x and y numeric
 type: scatter

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,72 +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.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
-
-# 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_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
+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",
@@ -143,6 +154,89 @@ __all__ = [
     "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