hotdata-jupyter 0.2.1__py3-none-any.whl

hotdata_jupyter/__init__.py

@@ -0,0 +1,62 @@
+"""Jupyter integration package for Hotdata runtime."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hotdata-jupyter")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from hotdata_runtime import (
+    DEFAULT_SCHEMA,
+    HotdataClient,
+    LoadManagedTableResult,
+    ManagedDatabase,
+    QueryResult,
+    WorkspaceSelection,
+    from_env,
+    resolve_workspace_selection,
+    workspace_health_lines,
+)
+
+from hotdata_jupyter.databases import (
+    ManagedDatabaseWriter,
+    create_managed_database,
+    display_managed_databases_panel,
+    load_managed_table_from_bytes,
+    managed_database_writer,
+    managed_databases_markdown,
+)
+from hotdata_jupyter.display import display_query_result, result_markdown
+from hotdata_jupyter.env import load_default_env_files, load_env_file
+from hotdata_jupyter.magics import HotdataMagics, load_ipython_extension
+from hotdata_jupyter.metadata import notebook_metadata
+from hotdata_jupyter.workspace import WorkspaceSelector, workspace_selector_from_env
+
+__all__ = [
+    "DEFAULT_SCHEMA",
+    "HotdataClient",
+    "HotdataMagics",
+    "LoadManagedTableResult",
+    "ManagedDatabase",
+    "ManagedDatabaseWriter",
+    "QueryResult",
+    "WorkspaceSelection",
+    "WorkspaceSelector",
+    "__version__",
+    "create_managed_database",
+    "display_managed_databases_panel",
+    "display_query_result",
+    "from_env",
+    "load_default_env_files",
+    "load_env_file",
+    "load_ipython_extension",
+    "load_managed_table_from_bytes",
+    "managed_database_writer",
+    "managed_databases_markdown",
+    "notebook_metadata",
+    "resolve_workspace_selection",
+    "result_markdown",
+    "workspace_health_lines",
+    "workspace_selector_from_env",
+]

hotdata_jupyter/databases.py

@@ -0,0 +1,237 @@
+"""Jupyter UI for managed Hotdata databases (create + parquet table loads)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+
+import ipywidgets as widgets
+from hotdata_runtime import (
+    DEFAULT_SCHEMA,
+    HotdataClient,
+    HotdataError,
+    HotdataTransientError,
+    LoadManagedTableResult,
+    ManagedDatabase,
+    classify_sdk_error,
+)
+from IPython.display import Markdown, display
+
+
+def _parse_table_names(text: str) -> list[str]:
+    return [line.strip() for line in text.splitlines() if line.strip()]
+
+
+def _format_runtime_error(error: HotdataError) -> str:
+    """Render a typed runtime/SDK error as a readable widget status message.
+
+    Transient (retryable) failures get a hint to try again so notebook users
+    are not left guessing whether the operation can simply be re-run.
+    """
+    if isinstance(error, HotdataTransientError):
+        return f"{error} (temporary - try again)"
+    return str(error)
+
+
+def _upload_parquet_bytes(client: HotdataClient, contents: bytes) -> str:
+    with tempfile.NamedTemporaryFile(suffix=".parquet", delete=False) as tmp:
+        tmp.write(contents)
+        path = tmp.name
+    try:
+        return client.upload_parquet(path)
+    finally:
+        os.unlink(path)
+
+
+def managed_databases_markdown(client: HotdataClient) -> str:
+    dbs = client.list_managed_databases()
+    if not dbs:
+        return (
+            "### Managed databases\n\n"
+            "_No managed databases yet._ Create one below, or with the CLI: "
+            "`hotdata databases create --name <name> --table <table>`."
+        )
+    lines = [
+        "### Managed databases",
+        "",
+        "| description | id | sql_prefix |",
+        "| --- | --- | --- |",
+    ]
+    for db in dbs:
+        prefix = f"{db.id}.{{schema}}.{{table}}"
+        lines.append(f"| {db.description or db.id} | `{db.id}` | `{prefix}` |")
+    lines.append("")
+    lines.append("_Query as `database.schema.table` in SQL._")
+    return "\n".join(lines)
+
+
+def display_managed_databases_panel(client: HotdataClient) -> None:
+    display(Markdown(managed_databases_markdown(client)))
+
+
+def create_managed_database(
+    client: HotdataClient,
+    *,
+    name: str,
+    schema: str = DEFAULT_SCHEMA,
+    tables: list[str] | None = None,
+) -> ManagedDatabase:
+    return client.create_managed_database(description=name, schema=schema, tables=tables)
+
+
+def load_managed_table_from_bytes(
+    client: HotdataClient,
+    database: str,
+    table: str,
+    contents: bytes,
+    *,
+    schema: str = DEFAULT_SCHEMA,
+) -> LoadManagedTableResult:
+    upload_id = _upload_parquet_bytes(client, contents)
+    return client.load_managed_table(
+        database,
+        table,
+        schema=schema,
+        upload_id=upload_id,
+    )
+
+
+class ManagedDatabaseWriter:
+    """Create managed databases and load parquet files from a Jupyter notebook."""
+
+    def __init__(
+        self,
+        client: HotdataClient,
+        *,
+        default_schema: str = DEFAULT_SCHEMA,
+    ) -> None:
+        self._client = client
+        self._default_schema = default_schema
+        self._status = widgets.Output()
+
+        self.name = widgets.Text(description="Database name", layout=widgets.Layout(width="100%"))
+        self.schema = widgets.Text(
+            value=default_schema,
+            description="Schema",
+            layout=widgets.Layout(width="100%"),
+        )
+        self.tables = widgets.Textarea(
+            description="Tables",
+            placeholder="One table name per line",
+            layout=widgets.Layout(width="100%", height="80px"),
+        )
+        self.create = widgets.Button(description="Create database", button_style="success")
+
+        self._rebuild_database_pick()
+        self.table = widgets.Text(description="Table name", layout=widgets.Layout(width="100%"))
+        self.file = widgets.FileUpload(accept=".parquet", description="Parquet file")
+        self.load = widgets.Button(description="Load table", button_style="success")
+
+        self.create.on_click(self._on_create)
+        self.load.on_click(self._on_load)
+
+    def _rebuild_database_pick(self) -> None:
+        current = getattr(getattr(self, "database", None), "value", None)
+        dbs = self._client.list_managed_databases()
+        if not dbs:
+            self.database = widgets.Dropdown(
+                options=[("(create one first)", "")],
+                value="",
+                description="Database",
+                layout=widgets.Layout(width="100%"),
+            )
+            return
+        options = [(db.description or db.id, db.id) for db in dbs]
+        value = current if current in {val for _, val in options} else options[0][1]
+        self.database = widgets.Dropdown(
+            options=options,
+            value=value,
+            description="Database",
+            layout=widgets.Layout(width="100%"),
+        )
+
+    def _on_create(self, _button: widgets.Button) -> None:
+        db_name = self.name.value.strip()
+        if not db_name:
+            self._write_status("Enter a database name.", error=True)
+            return
+        schema = self.schema.value.strip() or self._default_schema
+        tables = _parse_table_names(self.tables.value)
+        try:
+            db = self._client.create_managed_database(
+                description=db_name,
+                schema=schema,
+                tables=tables or None,
+            )
+            self._rebuild_database_pick()
+            self._write_status(
+                f"Created {db.description or db.id} ({db.id}). "
+                "Load parquet into a declared table below."
+            )
+        except HotdataError as e:
+            self._write_status(_format_runtime_error(e), error=True)
+        except (ValueError, KeyError) as e:
+            self._write_status(_format_runtime_error(classify_sdk_error(e)), error=True)
+
+    def _on_load(self, _button: widgets.Button) -> None:
+        database = self.database.value
+        table = self.table.value.strip()
+        if not database:
+            self._write_status("Choose or create a database first.", error=True)
+            return
+        if not table:
+            self._write_status("Enter a table name.", error=True)
+            return
+        if not self.file.value:
+            self._write_status("Choose a parquet file to upload.", error=True)
+            return
+        schema = self.schema.value.strip() or self._default_schema
+        try:
+            contents = self.file.value[0]["content"]
+            upload_id = _upload_parquet_bytes(self._client, contents)
+            loaded = self._client.load_managed_table(
+                database,
+                table,
+                schema=schema,
+                upload_id=upload_id,
+            )
+            self._write_status(f"Loaded {loaded.full_name} · {loaded.row_count} rows.")
+        except HotdataError as e:
+            self._write_status(_format_runtime_error(e), error=True)
+        except (ValueError, KeyError, OSError) as e:
+            self._write_status(_format_runtime_error(classify_sdk_error(e)), error=True)
+
+    def _write_status(self, message: str, *, error: bool = False) -> None:
+        with self._status:
+            self._status.clear_output(wait=True)
+            display(Markdown(f"**Error:** {message}" if error else message))
+
+    @property
+    def ui(self):
+        return widgets.VBox(
+            [
+                widgets.HTML("<h4>Create database</h4>"),
+                self.name,
+                self.schema,
+                self.tables,
+                self.create,
+                widgets.HTML("<h4>Load parquet table</h4>"),
+                self.database,
+                self.table,
+                self.file,
+                self.load,
+                self._status,
+            ]
+        )
+
+    def display(self) -> None:
+        display_managed_databases_panel(self._client)
+        display(self.ui)
+
+
+def managed_database_writer(
+    client: HotdataClient,
+    *,
+    default_schema: str = DEFAULT_SCHEMA,
+) -> ManagedDatabaseWriter:
+    return ManagedDatabaseWriter(client, default_schema=default_schema)

hotdata_jupyter/display.py

@@ -0,0 +1,35 @@
+"""Display adapters for Hotdata query results in notebooks."""
+
+from __future__ import annotations
+
+from hotdata_runtime import QueryResult
+from IPython.display import Markdown, display
+
+
+def result_markdown(result: QueryResult) -> str:
+    meta = result.metadata_dict()
+    parts: list[str] = [
+        f"**rows** `{meta['row_count']}`",
+        f"**columns** `{meta['column_count']}`",
+    ]
+    if meta["result_id"]:
+        parts.append(f"**result_id** `{meta['result_id']}`")
+    if meta["query_run_id"]:
+        parts.append(f"**query_run_id** `{meta['query_run_id']}`")
+    if meta["execution_time_ms"] is not None:
+        parts.append(f"**execution_time_ms** `{meta['execution_time_ms']}`")
+    if meta["warning"]:
+        parts.append(f"**warning** `{meta['warning']}`")
+    if meta["error_message"]:
+        parts.append(f"**error** `{meta['error_message']}`")
+    return " · ".join(parts)
+
+
+def display_query_result(
+    result: QueryResult,
+    *,
+    title: str = "Hotdata result",
+):
+    display(Markdown(f"### {title}"))
+    display(Markdown(result_markdown(result)))
+    return result.to_pandas()

hotdata_jupyter/env.py

@@ -0,0 +1,40 @@
+"""Load Hotdata credentials into the current process (e.g. Jupyter kernel)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_env_file(path: str | Path, *, override: bool = False) -> bool:
+    """Parse a shell-style ``KEY=VALUE`` file into ``os.environ``.
+
+    Returns True if the file existed and was read.
+    """
+    p = Path(path).expanduser()
+    if not p.is_file():
+        return False
+    for raw in p.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip("'\"")
+        if not key:
+            continue
+        if override or key not in os.environ:
+            os.environ[key] = value
+    return True
+
+
+def load_default_env_files() -> list[str]:
+    """Load ``~/.env`` then ``.env`` in the current working directory."""
+    loaded: list[str] = []
+    home = Path.home() / ".env"
+    if load_env_file(home):
+        loaded.append(str(home))
+    cwd = Path.cwd() / ".env"
+    if cwd != home and load_env_file(cwd):
+        loaded.append(str(cwd))
+    return loaded

hotdata_jupyter/magics.py

@@ -0,0 +1,38 @@
+"""IPython magics for executing Hotdata SQL."""
+
+from __future__ import annotations
+
+from hotdata_runtime import HotdataClient
+from IPython.core.magic import Magics, line_cell_magic, magics_class
+
+from hotdata_jupyter.display import display_query_result
+
+
+@magics_class
+class HotdataMagics(Magics):
+    def __init__(self, shell, client: HotdataClient | None = None):
+        super().__init__(shell)
+        self._client = client
+
+    def _runtime_client(self) -> HotdataClient:
+        if self._client is None:
+            self._client = HotdataClient.from_env()
+        return self._client
+
+    @line_cell_magic
+    def hotdata(self, line: str, cell: str | None = None):
+        if cell is not None:
+            # Cell magic: %%hotdata [database]
+            # Optional database name on the first line scopes the query.
+            sql = cell
+            database = line.strip() or None
+        else:
+            # Line magic: %hotdata SELECT ...
+            sql = line
+            database = None
+        result = self._runtime_client().execute_sql(sql, database=database)
+        return display_query_result(result)
+
+
+def load_ipython_extension(ipython) -> None:
+    ipython.register_magics(HotdataMagics)

hotdata_jupyter/metadata.py

@@ -0,0 +1,13 @@
+"""Notebook metadata helpers for Hotdata sessions."""
+
+from __future__ import annotations
+
+from hotdata_runtime import HotdataClient
+
+
+def notebook_metadata(client: HotdataClient) -> dict[str, str | None]:
+    return {
+        "workspace_id": client.workspace_id,
+        "host": client.host,
+        "session_id": client.session_id,
+    }

hotdata_jupyter/workspace.py

@@ -0,0 +1,99 @@
+"""Jupyter workspace selection (aligned with hotdata-marimo)."""
+
+from __future__ import annotations
+
+import ipywidgets as widgets
+from hotdata_runtime import (
+    HotdataClient,
+    default_api_key,
+    default_host,
+    default_session_id,
+    resolve_workspace_selection,
+)
+from IPython.display import Markdown
+
+
+class WorkspaceSelector:
+    """Workspace picker that rebuilds ``HotdataClient`` when the selection changes."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        host: str | None = None,
+        session_id: str | None = None,
+        label: str = "Workspace",
+    ) -> None:
+        self._api_key = api_key
+        self._host = host or default_host()
+        self._session_id = session_id
+        self._client_cache: HotdataClient | None = None
+        self._client_cache_wid: str | None = None
+        selection = resolve_workspace_selection(api_key, self._host, session_id)
+        self._explicit = selection.source == "explicit_env"
+        if self._explicit:
+            self._pick = None
+            self._workspace_id = selection.workspace_id
+            return
+
+        workspaces = selection.workspaces
+        if len(workspaces) == 1:
+            self._pick = None
+            self._workspace_id = workspaces[0].public_id
+            return
+
+        labels: list[tuple[str, str]] = []
+        seen: set[str] = set()
+        for w in workspaces:
+            base = w.name
+            label_text = base if base not in seen else f"{base} ({w.public_id})"
+            seen.add(base)
+            labels.append((label_text, w.public_id))
+
+        labels.sort(key=lambda t: 0 if t[1] == selection.workspace_id else 1)
+        self._pick = widgets.Dropdown(
+            options=labels,
+            value=selection.workspace_id,
+            description=label,
+            layout=widgets.Layout(width="100%"),
+        )
+        self._workspace_id = selection.workspace_id
+
+    @property
+    def workspace_id(self) -> str:
+        if self._pick is None:
+            return self._workspace_id
+        value = self._pick.value
+        return value if value else self._workspace_id
+
+    @property
+    def client(self) -> HotdataClient:
+        wid = self.workspace_id
+        if self._client_cache is None or self._client_cache_wid != wid:
+            self._client_cache = HotdataClient(
+                self._api_key,
+                wid,
+                host=self._host,
+                session_id=self._session_id,
+            )
+            self._client_cache_wid = wid
+        return self._client_cache
+
+    @property
+    def ui(self):
+        if self._pick is None:
+            return Markdown(f"**Workspace** `{self.workspace_id}`")
+        _ = self._pick.value
+        return self._pick
+
+
+def workspace_selector_from_env(*, label: str = "Workspace") -> WorkspaceSelector:
+    api_key = default_api_key()
+    if not api_key:
+        raise RuntimeError("HOTDATA_API_KEY must be set.")
+    return WorkspaceSelector(
+        api_key=api_key,
+        host=default_host(),
+        session_id=default_session_id(),
+        label=label,
+    )

hotdata_jupyter-0.2.1.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: hotdata-jupyter
+Version: 0.2.1
+Summary: Jupyter integration for Hotdata runtime
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: hotdata-runtime>=0.3.0
+Requires-Dist: hotdata>=0.4.1
+Requires-Dist: ipython>=8.18
+Requires-Dist: ipywidgets>=8.1
+Description-Content-Type: text/markdown
+
+# hotdata-jupyter
+
+[Jupyter](https://jupyter.org/) helpers for [Hotdata](https://hotdata.dev) — rich query display, workspace selection, managed databases, and a `%%hotdata` cell magic for running SQL directly in cells.
+
+## Install
+
+```bash
+pip install hotdata-jupyter
+```
+
+## Authentication
+
+Set `HOTDATA_API_KEY` in your environment. Optionally set `HOTDATA_WORKSPACE` to pin a specific workspace (the first available workspace is used if unset).
+
+## Quickstart
+
+```python
+import hotdata_jupyter as hj
+
+client = hj.from_env()
+result = client.execute_sql("SELECT 1 AS ok")
+hj.display_query_result(result)
+```
+
+## Workspace selection
+
+When `HOTDATA_WORKSPACE` is set, the client connects to that workspace directly. If you have multiple workspaces, use the interactive picker — it renders a dropdown and updates `ws.client` when the selection changes:
+
+```python
+ws = hj.workspace_selector_from_env()
+display(ws.ui)
+client = ws.client
+```
+
+## Running SQL
+
+```python
+result = client.execute_sql("SELECT * FROM orders LIMIT 10")
+hj.display_query_result(result)
+```
+
+`display_query_result` renders the row count, column names, and a pandas DataFrame inline in the notebook.
+
+## Cell magic
+
+Load the extension once per session, then use `%%hotdata` cells to write SQL without wrapping it in Python strings. The last active client is picked up automatically:
+
+```python
+%load_ext hotdata_jupyter
+```
+
+```
+%%hotdata
+SELECT
+  product,
+  SUM(amount) AS total
+FROM orders
+GROUP BY product
+ORDER BY total DESC
+```
+
+## Managed databases
+
+List the managed databases in your workspace:
+
+```python
+hj.display_managed_databases_panel(client)
+```
+
+Create a database and load parquet files programmatically:
+
+```python
+db = hj.create_managed_database(client, name="sales", tables=["orders"])
+
+with open("orders.parquet", "rb") as f:
+    loaded = hj.load_managed_table_from_bytes(client, "sales", "orders", f.read())
+
+print(f"Loaded {loaded.row_count} rows into {loaded.full_name}")
+```
+
+Or use the interactive ipywidgets form:
+
+```python
+writer = hj.managed_database_writer(client)
+writer.display()
+```
+
+## Open the demo notebook
+
+```bash
+jupyter lab examples/demo.ipynb
+```
+
+The demo covers workspace selection, connection listing, schema browsing, query history, and cell magics.
+
+## Development
+
+```bash
+uv sync --locked
+uv run pytest
+```

hotdata_jupyter-0.2.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+hotdata_jupyter/__init__.py,sha256=a0Xgbq3D3Go-Qs7VjIbRlK5qWE2eMR5gYLVLoUo9QgY,1752
+hotdata_jupyter/databases.py,sha256=QVS0LLh7kdsJDpBje3cEEh3ti0w8IcixoYVE6DCO57w,8064
+hotdata_jupyter/display.py,sha256=6X5k6dIWHwTuLkXTgFbC50g-PUBbaxPLSZyjFnB2zVs,1115
+hotdata_jupyter/env.py,sha256=mb7QxNwQnd_QbTonZb2qSCNVncXKK2rI8rurnDEJAOU,1214
+hotdata_jupyter/magics.py,sha256=cZCo5TsxrmHgNtUFlTjirKH7A-IupQpjggXuue2A7no,1209
+hotdata_jupyter/metadata.py,sha256=BJdYle83OkRb8-q1tYlw27OEYHh9JapuBJ_4sP-1cK0,340
+hotdata_jupyter/workspace.py,sha256=hLVcITsL8ySX6etcVzUpyQnC9kgcU3HiTXTlNqFldrU,3078
+hotdata_jupyter-0.2.1.dist-info/METADATA,sha256=5rduKZgN3d1EF5g0maBIdKxqAFve39g_b5pEZem0ekc,2643
+hotdata_jupyter-0.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hotdata_jupyter-0.2.1.dist-info/RECORD,,

hotdata_jupyter-0.2.1.dist-info/WHEEL

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