hotdata-marimo 0.1.0__py3-none-any.whl

hotdata_marimo/__init__.py

@@ -0,0 +1,80 @@
+"""Marimo-native UI and helpers for Hotdata (built on hotdata-runtime)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hotdata-marimo")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from hotdata_runtime import HotdataClient, QueryResult, from_env
+
+from hotdata_marimo.display import (
+    RecentResults,
+    connection_status,
+    connections_panel,
+    query_result,
+    recent_results,
+    run_history,
+)
+from hotdata_marimo.sql_engine import (
+    HotdataMarimoEngine,
+    register_hotdata_sql_engine,
+    unregister_hotdata_sql_engine,
+)
+from hotdata_marimo.sql_editor import SqlEditor, sql_editor
+from hotdata_marimo.table_browser import TableBrowser, connection_picker, table_browser
+from hotdata_marimo.workspace_selector import WorkspaceSelector, workspace_selector_from_env
+
+__all__ = [
+    "__version__",
+    "HotdataClient",
+    "HotdataMarimoEngine",
+    "QueryResult",
+    "RecentResults",
+    "SqlEditor",
+    "TableBrowser",
+    "WorkspaceSelector",
+    "connection_picker",
+    "connection_status",
+    "connections_panel",
+    "from_env",
+    "hotdata_connection_picker",
+    "hotdata_query_result",
+    "hotdata_recent_results",
+    "hotdata_sql_editor",
+    "hotdata_table_browser",
+    "hotdata_workspace_selector",
+    "query_result",
+    "recent_results",
+    "register_hotdata_sql_engine",
+    "register_mo_ui_hotdata_aliases",
+    "run_history",
+    "sql_editor",
+    "table_browser",
+    "unregister_hotdata_sql_engine",
+    "workspace_selector_from_env",
+]
+
+hotdata_sql_editor = sql_editor
+hotdata_table_browser = table_browser
+hotdata_query_result = query_result
+hotdata_connection_picker = connection_picker
+hotdata_workspace_selector = workspace_selector_from_env
+hotdata_recent_results = recent_results
+
+
+def register_mo_ui_hotdata_aliases() -> None:
+    """Attach Hotdata helpers to ``marimo.ui`` for discoverability (``mo.ui.hotdata_*``)."""
+    import marimo as mo
+
+    mo.ui.hotdata_sql_editor = hotdata_sql_editor  # type: ignore[attr-defined]
+    mo.ui.hotdata_table_browser = hotdata_table_browser  # type: ignore[attr-defined]
+    mo.ui.hotdata_query_result = hotdata_query_result  # type: ignore[attr-defined]
+    mo.ui.hotdata_connection_status = connection_status  # type: ignore[attr-defined]
+    mo.ui.hotdata_connection_picker = hotdata_connection_picker  # type: ignore[attr-defined]
+    mo.ui.hotdata_workspace_selector = hotdata_workspace_selector  # type: ignore[attr-defined]
+    mo.ui.hotdata_recent_results = hotdata_recent_results  # type: ignore[attr-defined]
+
+
+register_mo_ui_hotdata_aliases()

hotdata_marimo/_options.py

@@ -0,0 +1,107 @@
+"""Shared dropdown option helpers for Marimo UI widgets."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import marimo as mo
+
+from hotdata_runtime import HotdataClient
+
+
+def unique_label_options(
+    pairs: list[tuple[str, str]],
+    *,
+    disambiguate: Callable[[str, str, int], str] | None = None,
+) -> dict[str, str]:
+    """Build a label→value map, suffixing repeated labels when needed."""
+    counts: dict[str, int] = {}
+    options: dict[str, str] = {}
+    for label, value in pairs:
+        count = counts.get(label, 0)
+        counts[label] = count + 1
+        if count == 0:
+            key = label
+        elif disambiguate is not None:
+            key = disambiguate(label, value, count)
+        else:
+            key = f"{label} ({count + 1})"
+        options[key] = value
+    return options
+
+
+def empty_dropdown(
+    *,
+    label: str,
+    message: str,
+    full_width: bool = True,
+):
+    return mo.ui.dropdown(
+        options={message: ""},
+        label=label,
+        full_width=full_width,
+    )
+
+
+def connection_options(conns: list[Any]) -> dict[str, str]:
+    pairs = [(str(c.name), str(c.id)) for c in conns]
+    return unique_label_options(
+        pairs,
+        disambiguate=lambda label, value, count: f"{label} ({value})",
+    )
+
+
+def connection_picker_from_connections(
+    conns: list[Any],
+    *,
+    label: str = "Connection",
+    full_width: bool = True,
+):
+    if not conns:
+        return empty_dropdown(
+            label=label,
+            message="(no connections)",
+            full_width=full_width,
+        )
+    return mo.ui.dropdown(
+        options=connection_options(conns),
+        label=label,
+        full_width=full_width,
+    )
+
+
+def connection_picker(
+    client: HotdataClient,
+    *,
+    label: str = "Connection",
+    full_width: bool = True,
+):
+    conns = client.connections().list_connections().connections
+    return connection_picker_from_connections(
+        conns,
+        label=label,
+        full_width=full_width,
+    )
+
+
+def resolve_connection_picker(
+    client: HotdataClient,
+    *,
+    label: str = "Connection",
+    full_width: bool = True,
+) -> tuple[Any | None, str | None]:
+    """Return ``(dropdown_or_none, implicit_connection_id)`` for table browsers."""
+    conns = client.connections().list_connections().connections
+    if not conns:
+        return None, ""
+    if len(conns) == 1:
+        return None, conns[0].id
+    return (
+        connection_picker_from_connections(
+            conns,
+            label=label,
+            full_width=full_width,
+        ),
+        None,
+    )

hotdata_marimo/display.py

@@ -0,0 +1,209 @@
+"""Marimo views for query results, history, and workspace status."""
+
+from __future__ import annotations
+
+import marimo as mo
+
+from hotdata_runtime import HotdataClient, QueryResult, workspace_health_lines
+
+
+def query_result(
+    result: QueryResult,
+    *,
+    label: str = "Hotdata result",
+    page_size: int = 25,
+    max_height: int = 480,
+):
+    shown_rows = len(result.rows)
+    if result.row_count > shown_rows and shown_rows > 0:
+        trunc = mo.callout(
+            mo.md(
+                f"Showing **{shown_rows}** of **{result.row_count}** rows. "
+                "Consider adding a `LIMIT` clause for faster iteration."
+            ),
+            kind="warn",
+        )
+    else:
+        trunc = None
+    meta = result.metadata_dict()
+    meta_bits = []
+    if meta["result_id"]:
+        meta_bits.append(f"**result_id** `{meta['result_id']}`")
+    if meta["query_run_id"]:
+        meta_bits.append(f"**query_run_id** `{meta['query_run_id']}`")
+    if meta["execution_time_ms"] is not None:
+        meta_bits.append(f"**execution_time_ms** {meta['execution_time_ms']}")
+    if meta["warning"]:
+        meta_bits.append(f"**warning** {meta['warning']}")
+    if meta["error_message"]:
+        meta_bits.append(f"**error** {meta['error_message']}")
+    header = mo.md(" · ".join(meta_bits) if meta_bits else "_No metadata._")
+    df = result.to_pandas()
+    tbl = mo.ui.table(
+        df,
+        label=label,
+        pagination=True,
+        page_size=page_size,
+        selection=None,
+        max_height=max_height,
+    )
+    summary = mo.md(f"**{result.row_count}** rows · **{len(result.columns)}** columns")
+    bits = [summary]
+    if trunc is not None:
+        bits.append(trunc)
+    bits.extend([header, tbl])
+    return mo.vstack(bits, gap=1)
+
+
+class RecentResults:
+    def __init__(self, client: HotdataClient, *, limit: int = 50) -> None:
+        self._client = client
+        self._results = client.list_recent_results(limit=limit, offset=0)
+        self._rows: list[dict[str, object]] = [
+            {
+                "created_at": r.created_at,
+                "status": r.status,
+                "result_id": r.result_id,
+            }
+            for r in self._results
+        ]
+        self.table = (
+            mo.ui.table(
+                self._rows,
+                label="Recent results",
+                pagination=True,
+                page_size=min(10, limit),
+                selection="single",
+                max_height=320,
+            )
+            if self._rows
+            else None
+        )
+
+    @property
+    def selected_result_id(self) -> str | None:
+        if self.table is None:
+            return None
+        selected = self.table.value
+        if not selected:
+            return None
+        row = selected[0]
+        if not isinstance(row, dict):
+            return None
+        rid = row.get("result_id")
+        return rid if rid else None
+
+    @property
+    def result(self) -> QueryResult:
+        rid = self.selected_result_id
+        mo.stop(rid is None, mo.md("Select a result row to load."))
+        return self._client.get_result(rid or "")
+
+    @property
+    def result_panel(self):
+        rid = self.selected_result_id
+        if rid is None:
+            return mo.md("_Select a result row to load._")
+        return query_result(self._client.get_result(rid), label="Recent result")
+
+    @property
+    def tab_ui(self):
+        if self.table is not None:
+            _ = self.table.value
+        return mo.vstack([self.ui, self.result_panel], gap=2)
+
+    @property
+    def ui(self):
+        if self.table is None:
+            return mo.md("_No recent results._")
+        _ = self.table.value
+        return mo.vstack(
+            [
+                mo.md("### Recent results"),
+                self.table,
+            ],
+            gap=1,
+        )
+
+
+def recent_results(client: HotdataClient, *, limit: int = 50) -> RecentResults:
+    return RecentResults(client, limit=limit)
+
+
+def run_history(
+    client: HotdataClient,
+    *,
+    limit: int = 20,
+    label: str = "Run history",
+):
+    runs = client.list_run_history(limit=limit)
+    if not runs:
+        return mo.md("_No query runs returned._")
+
+    rows: list[dict[str, object]] = []
+    for r in runs:
+        rows.append(
+            {
+                "created_at": r.created_at,
+                "status": r.status,
+                "execution_time_ms": r.execution_time_ms,
+                "result_id": r.result_id,
+                "query_run_id": r.query_run_id,
+            }
+        )
+
+    return mo.vstack(
+        [
+            mo.md(f"### {label}"),
+            mo.ui.table(
+                rows,
+                pagination=True,
+                page_size=min(10, limit),
+                selection=None,
+                max_height=320,
+            ),
+        ],
+        gap=1,
+    )
+
+
+def connection_status(client: HotdataClient):
+    """Small status line: API reachability, workspace id, connection count, sandbox."""
+    ok, parts = workspace_health_lines(client)
+    if ok:
+        return mo.callout(mo.md(" · ".join(parts)), kind="success")
+    return mo.callout(
+        mo.md(f"**API** error — {parts[0]}"),
+        kind="danger",
+    )
+
+
+def connections_panel(client: HotdataClient):
+    """Workspace health callout plus a table of configured connections."""
+    status = connection_status(client)
+    conns = client.connections().list_connections().connections
+    if not conns:
+        return mo.vstack([status, mo.md("_No connections in this workspace._")], gap=1)
+    rows: list[dict[str, object]] = []
+    for c in conns:
+        rows.append(
+            {
+                "name": c.name,
+                "id": c.id,
+                "source_type": getattr(c, "source_type", None),
+            }
+        )
+    return mo.vstack(
+        [
+            status,
+            mo.ui.table(
+                rows,
+                label="Connections",
+                pagination=True,
+                page_size=min(10, len(rows)),
+                selection=None,
+                max_height=320,
+            ),
+        ],
+        gap=1,
+    )

hotdata_marimo/sql_editor.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import marimo as mo
+
+from hotdata_runtime import HotdataClient, QueryResult
+
+
+class SqlEditor:
+    """SQL workspace: textarea plus Run, with `result` after the button is pressed.
+
+    Marimo does not allow reading ``.value`` on UI elements in the same cell that
+    constructs them. Instantiate ``SqlEditor`` in one cell and use ``.ui`` / read
+    ``.result`` in other cells (see the package README two-cell pattern).
+    """
+
+    def __init__(
+        self,
+        client: HotdataClient,
+        *,
+        default_sql: str = "",
+        label: str = "SQL",
+        run_label: str = "Run on Hotdata",
+    ) -> None:
+        self._client = client
+        self.sql = mo.ui.text_area(default_sql, label=label)
+        self.run = mo.ui.button(
+            value=0,
+            on_click=lambda n: n + 1,
+            label=run_label,
+            kind="success",
+        )
+        self.rerun = mo.ui.button(
+            value=0,
+            on_click=lambda n: n + 1,
+            label="Rerun last",
+        )
+        self.clear = mo.ui.button(
+            value=0,
+            on_click=lambda n: n + 1,
+            label="Clear result",
+            kind="neutral",
+        )
+        self._result_cache: QueryResult | None = None
+        self._cached_sql: str | None = None
+        self._last_run_n: int | None = None
+        self._last_rerun_n: int | None = None
+        self._last_clear_n: int | None = None
+        self.show_history = mo.ui.checkbox(value=False, label="Show run history")
+
+    @property
+    def ui(self):
+        _ = self.run.value
+        _ = self.rerun.value
+        _ = self.clear.value
+        _ = self.show_history.value
+        return mo.vstack(
+            [
+                self.sql,
+                mo.hstack(
+                    [
+                        self.run,
+                        self.rerun,
+                        self.clear,
+                        self.show_history,
+                    ],
+                    gap=1,
+                ),
+                (
+                    mo.accordion(
+                        {
+                            "Run history": mo.lazy(
+                                lambda: __import__(
+                                    "hotdata_marimo.display",
+                                    fromlist=["run_history"],
+                                ).run_history(self._client)
+                            )
+                        }
+                    )
+                    if self.show_history.value
+                    else mo.md("")
+                ),
+            ],
+            gap=1,
+        )
+
+    def _apply_clear(self, clear_n: int) -> bool:
+        if clear_n > 0 and self._last_clear_n != clear_n:
+            self._result_cache = None
+            self._cached_sql = None
+            self._last_clear_n = clear_n
+            return True
+        return False
+
+    def _execute_or_cached(self) -> QueryResult | None:
+        sql_text = self.sql.value
+        run_n = self.run.value
+        rerun_n = self.rerun.value
+
+        if rerun_n > 0 and rerun_n != self._last_rerun_n:
+            if self._cached_sql is None:
+                return None
+            with mo.status.spinner(
+                title="Running on Hotdata",
+                subtitle="Re-running last query and waiting for results…",
+            ):
+                result = self._client.execute_sql(self._cached_sql or "")
+            self._result_cache = result
+            self._last_rerun_n = rerun_n
+            return result
+
+        if run_n > 0 and run_n != self._last_run_n:
+            with mo.status.spinner(
+                title="Running on Hotdata",
+                subtitle="Executing query and waiting for results…",
+            ):
+                result = self._client.execute_sql(sql_text)
+            self._result_cache = result
+            self._cached_sql = sql_text
+            self._last_run_n = run_n
+            return result
+
+        if self._result_cache is not None and sql_text == self._cached_sql:
+            return self._result_cache
+
+        return None
+
+    @property
+    def result_panel(self):
+        from hotdata_marimo.display import query_result
+
+        run_n = self.run.value
+        rerun_n = self.rerun.value
+        clear_n = self.clear.value
+
+        if self._apply_clear(clear_n):
+            return mo.md("Result cleared. Click **Run on Hotdata** to execute again.")
+
+        if run_n == 0 and rerun_n == 0 and self._result_cache is None:
+            return mo.md("_Click **Run on Hotdata** to execute._")
+
+        if rerun_n > 0 and rerun_n != self._last_rerun_n and self._cached_sql is None:
+            return mo.md("No previous SQL to rerun yet — click **Run on Hotdata** first.")
+
+        result = self._execute_or_cached()
+        if result is not None:
+            return query_result(result)
+
+        return mo.md("SQL changed — click **Run on Hotdata** again to execute.")
+
+    @property
+    def tab_ui(self):
+        _ = self.run.value
+        _ = self.rerun.value
+        _ = self.clear.value
+        _ = self.show_history.value
+        return mo.vstack([self.ui, self.result_panel], gap=2)
+
+    @property
+    def result(self) -> QueryResult:
+        run_n = self.run.value
+        rerun_n = self.rerun.value
+        clear_n = self.clear.value
+
+        if self._apply_clear(clear_n):
+            mo.stop(True, mo.md("Result cleared. Click **Run on Hotdata** to execute again."))
+
+        mo.stop(
+            run_n == 0 and rerun_n == 0,
+            mo.md(
+                "**Run on Hotdata** is on the SQL editor UI (a cell that **returns** "
+                "`editor.ui` or `mo.vstack([browser.ui, editor.ui])`). Click it there, "
+                "then this cell will run."
+            ),
+        )
+
+        if rerun_n > 0 and rerun_n != self._last_rerun_n:
+            mo.stop(
+                self._cached_sql is None,
+                mo.md("No previous SQL to rerun yet — click **Run on Hotdata** first."),
+            )
+
+        result = self._execute_or_cached()
+        if result is not None:
+            return result
+
+        mo.stop(
+            True,
+            mo.md("SQL changed — click **Run on Hotdata** again to execute."),
+        )
+
+
+def sql_editor(
+    client: HotdataClient,
+    *,
+    default_sql: str = "",
+    label: str = "SQL",
+    run_label: str = "Run on Hotdata",
+) -> SqlEditor:
+    return SqlEditor(
+        client, default_sql=default_sql, label=label, run_label=run_label
+    )