hotdata-marimo 0.1.0__py3-none-any.whl

hotdata_marimo-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: hotdata-marimo
+Version: 0.1.0
+Summary: Marimo integration for Hotdata runtime
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: hotdata-runtime>=0.1.0
+Requires-Dist: marimo>=0.10.0
+Description-Content-Type: text/markdown
+
+# hotdata-marimo
+
+Marimo UI helpers for [Hotdata](https://hotdata.dev): run SQL from a notebook, browse catalog metadata, and render results as tables.
+
+## Features
+
+- **Workspace-aware setup** — build a `HotdataClient` from environment variables, or use `workspace_selector_from_env()` to choose a workspace interactively when no workspace is pinned.
+- **Connection health** — show a compact status callout with API, workspace, and optional sandbox context.
+- **Catalog browsing** — browse Hotdata connections, schemas, tables, and columns from Marimo UI controls.
+- **SQL editor widget** — run SQL against Hotdata, cache the latest successful result, and render results in downstream reactive cells.
+- **Native `mo.sql` engine** — register `HotdataMarimoEngine` so Marimo SQL cells can execute through a live `HotdataClient` with `engine=client`.
+- **Result display helpers** — render query results, recent results, and run history as notebook-friendly UI.
+- **Marimo UI aliases** — importing `hotdata_marimo` attaches helpers such as `mo.ui.hotdata_sql_editor` and `mo.ui.hotdata_table_browser` for discoverability.
+
+## Install
+
+```bash
+uv pip install hotdata-marimo
+# or: pip install hotdata-marimo
+```
+
+Requires Python 3.10+, **Marimo**, and [**hotdata-runtime**](https://github.com/hotdata-dev/hotdata-runtime) (Hotdata SDK + runtime/session semantics — pulled in automatically when you `pip install hotdata-marimo`).
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HOTDATA_API_KEY` | Yes | API key for the Hotdata API |
+| `HOTDATA_API_URL` | No | API base URL (default: `https://api.hotdata.dev`) |
+| `HOTDATA_WORKSPACE` | No | Workspace id; if unset, the first active workspace is used |
+| `HOTDATA_SANDBOX` | No | Sandbox session id, passed through to the SDK |
+
+## Minimal notebook
+
+```python
+import marimo as mo
+import hotdata_marimo as hm
+
+client = hm.from_env()
+editor = hm.sql_editor(client, default_sql="SELECT 1 AS ok")
+return editor.ui
+```
+
+```python
+return hm.query_result(editor.result)
+```
+
+Importing `hotdata_marimo` registers discoverability aliases on Marimo’s UI namespace, so you can also use `mo.ui.hotdata_sql_editor`, `mo.ui.hotdata_table_browser`, `mo.ui.hotdata_query_result`, and `mo.ui.hotdata_connection_status`.
+
+Use `hm.connection_status(client)` (or `mo.ui.hotdata_connection_status(client)`) for a small API/workspace health callout.
+
+## Marimo SQL Cells
+
+Register the Hotdata SQL engine once during setup, then pass a `HotdataClient` to Marimo SQL cells:
+
+```python
+import hotdata_marimo as hm
+
+hm.register_hotdata_sql_engine()
+client = hm.from_env()
+```
+
+```python
+_df = mo.sql(
+    """
+    SELECT 1 AS example_value
+    """,
+    engine=client,
+)
+```
+
+The engine also exposes Hotdata catalog metadata to Marimo's data-source UI. Hotdata connections are labeled **Hotdata** in the SQL connection picker.
+
+## Two-cell pattern
+
+Keep the editor in one cell and consume `editor.result` in another. The editor caches the last successful run so downstream cells do not re-query the API on every refresh; click **Run on Hotdata** again after you change SQL. While a query is running, a Marimo status spinner is shown.
+
+Marimo only shows **what you `return` from a cell**. Calling `mo.vstack(...)` or `hm.query_result(...)` without returning it produces no visible output.
+
+See `examples/demo.py` for a full runnable notebook flow.
+
+## Examples
+
+- `examples/demo.py` — tabbed explorer with workspace selection, connection health, recent results (selectable table), run history, and a native `mo.sql` cell.
+
+Run locally (single-user machine):
+
+```bash
+uv run marimo edit examples/demo.py --no-token
+```
+
+On a **shared or networked host**, omit `--no-token` and use the access token printed in the terminal URL. Without it, anyone who can reach the Marimo port can run queries against your Hotdata workspace.
+
+## Layout
+
+This repo is intentionally thin: **API client, env helpers, and result models** live in **hotdata-runtime**; **hotdata-marimo** only adds Marimo widgets (`sql_editor`, `table_browser`, `display` for tables/status/history, `workspace_selector`). Import `HotdataClient` / `QueryResult` / `from_env` from **`hotdata_marimo`** or directly from **`hotdata_runtime`**.
+
+## Development
+
+This package depends on [**hotdata-runtime**](https://github.com/hotdata-dev/hotdata-runtime) (PyPI name `hotdata-runtime`). Development uses **uv**; keep a sibling checkout at `../hotdata-runtime` so the lockfile resolves the runtime from disk (see `[tool.uv.sources]` in `pyproject.toml`).
+
+```bash
+uv sync --locked
+uv run pytest
+marimo edit examples/demo.py --no-token
+```
+
+To pin **hotdata-runtime** from Git instead of the sibling path, remove the `[tool.uv.sources]` block, set the dependency line as needed, and run `uv lock` again.
+
+For a **publishable** `uv.lock` (CI that only clones this repo), remove `[tool.uv.sources]`, point `hotdata-runtime` at PyPI or `git+https://…`, then `uv lock`.
+
+The **`[project] name`** in [hotdata-runtime](https://github.com/hotdata-dev/hotdata-runtime) `pyproject.toml` is **`hotdata-runtime`** and the import package is **`hotdata_runtime`**.
+
+Use **`--no-token`** for local development so the editor does not redirect to `/auth/login` (session auth is easy to hit with a global Marimo config). For a public or shared machine, omit it and use the printed URL with an access token instead.

hotdata_marimo-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hotdata_marimo/__init__.py,sha256=cnq5DzMM2xYTkzwzC07tPkA_S8Zzjg2HoohRHP6EP1E,2617
+hotdata_marimo/_options.py,sha256=hHyj0tiJ4SuKoyqfr2DjlEVSNbBBFmuxdAs9uVvYiSw,2617
+hotdata_marimo/display.py,sha256=9rnXTmuYphqlEpy_XBFFfYQuYNYgzFMyDCjJS56CFyQ,6086
+hotdata_marimo/sql_editor.py,sha256=wHZQh1Ia3bLwLFGl8QoOfoI8A8wspNgdvo6JMJclQcU,6455
+hotdata_marimo/sql_engine.py,sha256=JEr7GtvQAuC85c3JchsF-03scYc-Ep7L2RisZISPBCE,12166
+hotdata_marimo/table_browser.py,sha256=s8l2QFat9dQGocORKqQIy0hxEgYZqvhi8zPwP8m5LIg,7334
+hotdata_marimo/workspace_selector.py,sha256=83dR4ABttQ64fAPmfDIsTmNEB375TS8SWhtgEolTu_c,2665
+hotdata_marimo-0.1.0.dist-info/METADATA,sha256=nLUOgcZqA5SkedgAXhkmkwfV87YwMWeSTIzreKYljG4,5685
+hotdata_marimo-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hotdata_marimo-0.1.0.dist-info/RECORD,,

hotdata_marimo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any