bideux 0.1.2__py3-none-any.whl

bideux/__init__.py

@@ -0,0 +1,157 @@
+"""Bideux dashboards in one install.
+
+This distribution carries ``dashboard_spec``, ``dashboard_core``,
+``dashboard_engine``, ``dashboard_store``, ``dashboard_server``,
+``dashboard_report`` and ``dashboard_authoring`` under their own names, so
+every import that works against the granular ``bideux-dashboard-*`` wheels
+works unchanged here. This module is the short path: the objects a host
+touches when it wires a dashboard service, runs the engine, or renders a
+report, in one namespace.
+
+Scheduling is not here on purpose. A host owns its schedules, cron and
+delivery and calls :class:`DashboardReportService` for the bytes.
+"""
+
+from __future__ import annotations
+
+from dashboard_authoring import DashboardAuthoringService
+from dashboard_core import slugify
+from dashboard_engine import (
+    DashboardEngine,
+    DashboardEngineError,
+    EngineOptions,
+    ScopeContext,
+    WarehousePort,
+)
+from dashboard_report import (
+    BrandingPort,
+    BuiltReport,
+    CapturePort,
+    DashboardLinkPort,
+    DashboardReportPort,
+    DashboardReportRequest,
+    DashboardReportService,
+    ReportBranding,
+    ReportFormat,
+)
+from dashboard_server import (
+    AccessPolicy,
+    AuditEvent,
+    AuditPort,
+    Caller,
+    DashboardAccessError,
+    DashboardLayoutConflictError,
+    DashboardListing,
+    DashboardNotFoundError,
+    DashboardPermission,
+    DashboardRef,
+    DashboardRender,
+    DashboardRepositoryPort,
+    DashboardService,
+    DashboardServiceError,
+    DefaultAccessPolicy,
+    EngineFactoryPort,
+    InvalidDocumentError,
+    ModelRepositoryPort,
+    Principal,
+    PrincipalDirectoryPort,
+    RenderCachePort,
+    Repositories,
+    ServiceOptions,
+    ShareRepositoryPort,
+    SharingDisabledError,
+    SlugTakenError,
+    SlugUnavailableError,
+    UnitOfWorkPort,
+    WidgetNotFoundError,
+    WidgetRepositoryPort,
+)
+from dashboard_spec import (
+    DashboardSpec,
+    SemanticModel,
+    WidgetSpec,
+    parse_dashboard_yaml,
+    parse_semantic_model_yaml,
+    parse_widget_yaml,
+)
+from dashboard_store import (
+    DashboardModelRepository,
+    ModelRepository,
+    ShareRepository,
+    WidgetRepository,
+)
+
+from bideux._guard import (
+    GRANULAR_DISTRIBUTIONS,
+    BideuxInstallConflict,
+    installed_granular_distributions,
+    warn_on_conflict,
+)
+
+__version__ = "0.1.2"
+
+warn_on_conflict()
+
+__all__ = [
+    "GRANULAR_DISTRIBUTIONS",
+    "AccessPolicy",
+    "AuditEvent",
+    "AuditPort",
+    "BideuxInstallConflict",
+    "BrandingPort",
+    "BuiltReport",
+    "Caller",
+    "CapturePort",
+    "DashboardAccessError",
+    "DashboardAuthoringService",
+    "DashboardEngine",
+    "DashboardEngineError",
+    "DashboardLayoutConflictError",
+    "DashboardLinkPort",
+    "DashboardListing",
+    "DashboardModelRepository",
+    "DashboardNotFoundError",
+    "DashboardPermission",
+    "DashboardRef",
+    "DashboardRender",
+    "DashboardReportPort",
+    "DashboardReportRequest",
+    "DashboardReportService",
+    "DashboardRepositoryPort",
+    "DashboardService",
+    "DashboardServiceError",
+    "DashboardSpec",
+    "DefaultAccessPolicy",
+    "EngineFactoryPort",
+    "EngineOptions",
+    "InvalidDocumentError",
+    "ModelRepository",
+    "ModelRepositoryPort",
+    "Principal",
+    "PrincipalDirectoryPort",
+    "RenderCachePort",
+    "ReportBranding",
+    "ReportFormat",
+    "Repositories",
+    "ScopeContext",
+    "SemanticModel",
+    "ServiceOptions",
+    "ShareRepository",
+    "ShareRepositoryPort",
+    "SharingDisabledError",
+    "SlugTakenError",
+    "SlugUnavailableError",
+    "UnitOfWorkPort",
+    "WarehousePort",
+    "WidgetNotFoundError",
+    "WidgetRepository",
+    "WidgetRepositoryPort",
+    "WidgetSpec",
+    "__version__",
+    "installed_granular_distributions",
+    "parse_dashboard_yaml",
+    "parse_semantic_model_yaml",
+    "parse_widget_yaml",
+    "slugify",
+    "warn_on_conflict",
+]

bideux/_guard.py

@@ -0,0 +1,62 @@
+"""Refuse to run next to the granular distributions this wheel already contains.
+
+``bideux`` and the ``bideux-dashboard-*`` wheels install the same import
+packages (``dashboard_spec``, ``dashboard_server`` and the rest), so having
+both means whichever was installed last silently wins. Python metadata has no
+conflicts field, so the check is done here, once, at import.
+"""
+
+from __future__ import annotations
+
+import warnings
+from importlib import metadata
+
+GRANULAR_DISTRIBUTIONS: tuple[str, ...] = (
+    "bideux-dashboard-spec",
+    "bideux-dashboard-core",
+    "bideux-dashboard-engine",
+    "bideux-dashboard-store",
+    "bideux-dashboard-server",
+    "bideux-dashboard-report",
+    "bideux-dashboard-authoring",
+    "bideux-dashboard-schedule",
+)
+
+
+class BideuxInstallConflict(RuntimeWarning):
+    """Both the bundle and one or more granular distributions are installed."""
+
+
+def installed_granular_distributions() -> tuple[str, ...]:
+    """Return the ``bideux-dashboard-*`` distributions present in this environment."""
+    found: list[str] = []
+    for name in GRANULAR_DISTRIBUTIONS:
+        try:
+            metadata.version(name)
+        except metadata.PackageNotFoundError:
+            continue
+        found.append(name)
+    return tuple(found)
+
+
+def warn_on_conflict() -> tuple[str, ...]:
+    """Warn once when granular distributions share the environment with ``bideux``."""
+    found = installed_granular_distributions()
+    if found:
+        warnings.warn(
+            "bideux is installed alongside "
+            + ", ".join(found)
+            + ". Both provide the same dashboard_* modules; uninstall one family. "
+            "Hosts pick either `bideux` or the `bideux-dashboard-*` packages, never both.",
+            BideuxInstallConflict,
+            stacklevel=3,
+        )
+    return found
+
+
+__all__ = [
+    "GRANULAR_DISTRIBUTIONS",
+    "BideuxInstallConflict",
+    "installed_granular_distributions",
+    "warn_on_conflict",
+]

bideux/authoring.py

@@ -0,0 +1,12 @@
+"""AI assisted authoring of models, widgets and dashboards over host provided ports.
+
+Every public name of ``dashboard_authoring`` re-exported under the ``bideux`` namespace, so a
+host that installs the single ``bideux`` wheel never imports a granular module name.
+"""
+
+from __future__ import annotations
+
+from dashboard_authoring import *  # noqa: F403
+from dashboard_authoring import __all__ as _base
+
+__all__ = [*_base]

bideux/cli.py

@@ -0,0 +1,118 @@
+"""The ``bideux`` command: ``demo``, ``init`` and ``doctor``.
+
+``demo`` and ``init`` need the ``fastapi`` extra (and ``demo`` the ``demo``
+extra for uvicorn); ``doctor`` needs nothing beyond the base install, which is
+why the demo module is loaded only when that subcommand runs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib import import_module
+from importlib.util import find_spec
+from pathlib import Path
+
+from bideux import doctor, init
+from bideux.corpus import find_fixtures
+
+DEMO_PORT = 5477
+
+
+def _demo(args: argparse.Namespace) -> int:
+    missing = [name for name in ("fastapi", "aiosqlite", "uvicorn") if find_spec(name) is None]
+    if missing:
+        print(
+            "bideux demo needs " + ", ".join(missing) + ": uv add 'bideux[demo]'",
+            file=sys.stderr,
+        )
+        return 2
+    fixtures = Path(args.fixtures) if args.fixtures else find_fixtures(Path.cwd())
+    if fixtures is None:
+        print(
+            "no conformance/fixtures directory at or above the working directory; "
+            "pass --fixtures PATH (the corpus lives in the bideux repository)",
+            file=sys.stderr,
+        )
+        return 2
+    element_dir = Path(args.element_dir) if args.element_dir else None
+    demo = import_module("bideux.demo")
+    uvicorn = import_module("uvicorn")
+    app = demo.create_demo_app(
+        fixtures=fixtures,
+        database_url=args.database_url,
+        prefix=args.prefix,
+        element_dir=element_dir,
+    )
+    print(f"Bideux demo at http://{args.host}:{args.port}/  (API under {args.prefix})")
+    uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    for written in init.scaffold(
+        Path(args.target), prefix=args.prefix, port=args.port, force=args.force
+    ):
+        verb = "wrote" if written.created else "kept"
+        print(f"{verb} {written.path}")
+    print(
+        "next: uv add 'bideux[fastapi,sqlite]' uvicorn, fill in MyHost, then "
+        f"uvicorn bideux_host:app --port {args.port} and open dashboard.html"
+    )
+    return 0
+
+
+def _doctor(args: argparse.Namespace) -> int:
+    findings = doctor.run(Path(args.project))
+    for finding in findings:
+        print(finding.line())
+    return 1 if doctor.worst(findings) == "fail" else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bideux", description="Bideux dashboards in one install.")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    demo = commands.add_parser("demo", help="run a seeded dashboard API and page on one port")
+    demo.add_argument("--host", default="127.0.0.1")
+    demo.add_argument("--port", type=int, default=DEMO_PORT)
+    demo.add_argument("--prefix", default="/api/dashboards")
+    demo.add_argument(
+        "--database-url",
+        default="sqlite+aiosqlite:///bideux-demo.sqlite3",
+        help="where the store lives; delete the file to reseed",
+    )
+    demo.add_argument(
+        "--fixtures", help="path to conformance/fixtures; found automatically in the repo"
+    )
+    demo.add_argument(
+        "--element-dir",
+        help="a built packages/bideux/dist to serve instead of loading @dlh.io/bideux from unpkg",
+    )
+    demo.set_defaults(run=_demo)
+
+    scaffold = commands.add_parser(
+        "init", help="write bideux_host.py and dashboard.html to start from"
+    )
+    scaffold.add_argument("target", nargs="?", default=".")
+    scaffold.add_argument("--prefix", default="/api/dashboards")
+    scaffold.add_argument("--port", type=int, default=DEMO_PORT)
+    scaffold.add_argument("--force", action="store_true", help="overwrite files that exist")
+    scaffold.set_defaults(run=_init)
+
+    check = commands.add_parser(
+        "doctor", help="check the Python and Node install for known problems"
+    )
+    check.add_argument("project", nargs="?", default=".", help="directory holding package.json")
+    check.set_defaults(run=_doctor)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    result = args.run(args)
+    return result if isinstance(result, int) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bideux/core.py

@@ -0,0 +1,12 @@
+"""Headless dashboard logic: layout, filters, pivots and tokens.
+
+Every public name of ``dashboard_core`` re-exported under the ``bideux`` namespace, so a
+host that installs the single ``bideux`` wheel never imports a granular module name.
+"""
+
+from __future__ import annotations
+
+from dashboard_core import *  # noqa: F403
+from dashboard_core import __all__ as _base
+
+__all__ = [*_base]

bideux/corpus.py

@@ -0,0 +1,19 @@
+"""Where the conformance corpus is, for the commands that read it."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+FIXTURE_DIRECTORY = Path("conformance") / "fixtures"
+
+
+def find_fixtures(start: Path) -> Path | None:
+    """The corpus directory at or above ``start``, when running inside the repo."""
+    for candidate in (start, *start.parents):
+        found = candidate / FIXTURE_DIRECTORY
+        if (found / "dashboards").is_dir():
+            return found
+    return None
+
+
+__all__ = ["FIXTURE_DIRECTORY", "find_fixtures"]

bideux/demo.py

@@ -0,0 +1,200 @@
+"""``bideux demo``: a working dashboard API and page in one command.
+
+The demo is :func:`bideux.fastapi.mount_bideux` over a sqlite file with a
+:class:`HostAdapter` whose warehouse is the in-memory reference warehouse
+evaluating the corpus rows, seeded with the ``retail_overview`` dashboard from
+``conformance/fixtures``. The page at ``/`` is the custom element from
+``@dlh.io/bideux/element``, loaded from a CDN or from a local ``dist``
+directory. Nothing in it is meant for production; it shows the shape a host
+copies with ``bideux init``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from dashboard_engine import ResolvedLocations, WarehousePort
+from dashboard_engine.reference import ReferenceWarehouse, reference_tables
+from dashboard_engine.results import DataStoreDescriptor, Row
+from dashboard_server import Caller
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+from bideux.corpus import find_fixtures
+from bideux.fastapi.mount import BideuxMount, mount_bideux
+from bideux.hosting import HostAdapter
+from bideux.quickstart import local_caller
+
+DISPLAY_NAMES = {"10001": "Downtown", "10002": "Riverside", "10003": "Airport"}
+DEMO_SLUG = "retail-overview"
+
+
+def load_tables(fixtures: Path) -> dict[str, tuple[Row, ...]]:
+    payload = json.loads((fixtures / "data" / "warehouse_rows.json").read_text())
+    tables: Mapping[str, Mapping[str, Sequence[Row]]] = payload["tables"]
+    rows: dict[str, Sequence[Row]] = {
+        name: [dict(row) for row in table["rows"]] for name, table in tables.items()
+    }
+    return reference_tables(rows)
+
+
+@dataclass(frozen=True, slots=True)
+class DemoDocuments:
+    model_yaml: str
+    dashboard_yaml: str
+    widget_yamls: dict[str, str]
+
+
+def load_documents(fixtures: Path) -> DemoDocuments:
+    widgets = {
+        path.name.removesuffix(".widget.yaml"): path.read_text()
+        for path in sorted((fixtures / "widgets").glob("*.widget.yaml"))
+    }
+    return DemoDocuments(
+        model_yaml=(fixtures / "model" / "retail.model.yaml").read_text(),
+        dashboard_yaml=(fixtures / "dashboards" / "retail_overview.dashboard.yaml").read_text(),
+        widget_yamls=widgets,
+    )
+
+
+class DemoHost(HostAdapter):
+    """Everyone is ``?person=`` (default ``demo``), an admin; rows come from the corpus."""
+
+    model_slug = "retail"
+
+    def __init__(self, fixtures: Path) -> None:
+        self._warehouse = ReferenceWarehouse(
+            tables=load_tables(fixtures),
+            descriptor=DataStoreDescriptor("reference", "snowflake", "MART"),
+            locations=ResolvedLocations(None, None),
+            display_names=DISPLAY_NAMES,
+        )
+
+    async def caller(self, request: Request) -> Caller:
+        return local_caller(request.query_params.get("person", "demo"))
+
+    def warehouse(self, caller: Caller) -> WarehousePort:
+        del caller
+        return self._warehouse
+
+
+def element_script_url(element_dir: Path | None) -> str:
+    if element_dir is not None:
+        return "/element/element/element.js"
+    try:
+        release = version("bideux")
+    except PackageNotFoundError:
+        release = "latest"
+    return f"https://unpkg.com/@dlh.io/bideux@{release}/dist/element/element.js"
+
+
+def stylesheet_urls(element_dir: Path | None) -> tuple[str, str]:
+    if element_dir is not None:
+        return ("/element/styles.css", "/element/theme.css")
+    base = element_script_url(None).removesuffix("/element/element.js")
+    return (f"{base}/styles.css", f"{base}/theme.css")
+
+
+def demo_page(*, prefix: str, element_dir: Path | None) -> str:
+    styles, theme = stylesheet_urls(element_dir)
+    script = element_script_url(element_dir)
+    return f"""<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Bideux demo</title>
+    <link rel="stylesheet" href="{styles}" />
+    <link rel="stylesheet" href="{theme}" />
+    <script type="module" src="{script}"></script>
+    <style>
+      body {{ margin: 0; font-family: system-ui, sans-serif; }}
+    </style>
+  </head>
+  <body>
+    <bideux-dashboard-list id="list" base-url="{prefix}"></bideux-dashboard-list>
+    <bideux-dashboard id="page" base-url="{prefix}" can-edit-model hidden></bideux-dashboard>
+    <script type="module">
+      const list = document.getElementById("list");
+      const page = document.getElementById("page");
+      const open = (dashboardId, editing) => {{
+        page.setAttribute("dashboard-id", dashboardId);
+        page.toggleAttribute("start-in-edit-mode", editing);
+        page.hidden = false;
+        list.hidden = true;
+      }};
+      list.addEventListener("open", (event) =>
+        open(event.detail.dashboardId, event.detail.editing),
+      );
+      page.addEventListener("opendashboard", (event) => open(event.detail.dashboardId, false));
+      page.addEventListener("back", () => {{
+        page.hidden = true;
+        list.hidden = false;
+      }});
+      const wanted = new URL(location.href).searchParams.get("dashboard");
+      if (wanted) open(wanted, false);
+    </script>
+  </body>
+</html>
+"""
+
+
+async def seed(mount: BideuxMount, documents: DemoDocuments) -> None:
+    """Write the corpus model and dashboard once; a second start finds them and stops."""
+    async with mount.service(local_caller("demo")) as service:
+        if await service.dashboard_exists(DEMO_SLUG):
+            return
+        await service.update_global_model(documents.model_yaml, note="bideux demo seed")
+        await service.upsert_from_spec(
+            documents.dashboard_yaml,
+            documents.widget_yamls,
+            visibility="org",
+        )
+
+
+def create_demo_app(
+    *,
+    fixtures: Path,
+    database_url: str,
+    prefix: str = "/api/dashboards",
+    element_dir: Path | None = None,
+) -> FastAPI:
+    """The demo app: routes at ``prefix``, the page at ``/``, seeded on start."""
+    documents = load_documents(fixtures)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        del app
+        await seed(mount, documents)
+        yield
+
+    app = FastAPI(title="Bideux demo", lifespan=lifespan)
+    mount = mount_bideux(app, host=DemoHost(fixtures), database_url=database_url, prefix=prefix)
+    if element_dir is not None:
+        app.mount("/element", StaticFiles(directory=element_dir), name="element")
+
+    page = demo_page(prefix=prefix, element_dir=element_dir)
+
+    @app.get("/", response_class=HTMLResponse, include_in_schema=False)
+    async def index() -> str:
+        return page
+
+    return app
+
+
+__all__ = [
+    "DemoDocuments",
+    "DemoHost",
+    "create_demo_app",
+    "demo_page",
+    "find_fixtures",
+    "load_documents",
+    "load_tables",
+    "seed",
+]