hotdata-framework 0.4.0__py3-none-any.whl

hotdata_framework/__init__.py

@@ -0,0 +1,71 @@
+"""Hotdata runtime primitives for notebook, app, and adapter integrations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from hotdata_framework.client import (
+    HotdataClient,
+    ResultSummary,
+    RunHistoryItem,
+    from_env,
+)
+from hotdata_framework.databases import (
+    DEFAULT_SCHEMA,
+    LoadManagedTableResult,
+    ManagedDatabase,
+    ManagedTable,
+    is_parquet_path,
+)
+from hotdata_framework.env import (
+    WorkspaceSelection,
+    default_api_key,
+    default_host,
+    default_session_id,
+    explicit_workspace_id,
+    list_workspaces,
+    normalize_host,
+    pick_workspace,
+    resolve_workspace_selection,
+)
+from hotdata_framework.errors import (
+    HotdataError,
+    HotdataTerminalError,
+    HotdataTransientError,
+    classify_sdk_error,
+)
+from hotdata_framework.health import workspace_health_lines
+from hotdata_framework.managed_client import ManagedDatabaseClient
+from hotdata_framework.result import QueryResult
+
+try:
+    __version__ = version("hotdata-framework")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "DEFAULT_SCHEMA",
+    "HotdataClient",
+    "HotdataError",
+    "HotdataTerminalError",
+    "HotdataTransientError",
+    "LoadManagedTableResult",
+    "ManagedDatabase",
+    "ManagedDatabaseClient",
+    "ManagedTable",
+    "QueryResult",
+    "ResultSummary",
+    "RunHistoryItem",
+    "WorkspaceSelection",
+    "__version__",
+    "classify_sdk_error",
+    "default_api_key",
+    "default_host",
+    "default_session_id",
+    "explicit_workspace_id",
+    "from_env",
+    "is_parquet_path",
+    "list_workspaces",
+    "normalize_host",
+    "pick_workspace",
+    "resolve_workspace_selection",
+    "workspace_health_lines",
+]

hotdata_framework/client.py

@@ -0,0 +1,524 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from hotdata import ApiClient, Configuration
+from hotdata.api.connections_api import ConnectionsApi
+from hotdata.api.databases_api import DatabasesApi
+from hotdata.api.information_schema_api import InformationSchemaApi
+from hotdata.api.query_api import QueryApi
+from hotdata.api.query_runs_api import QueryRunsApi
+from hotdata.api.results_api import ResultsApi
+from hotdata.api.uploads_api import UploadsApi
+from hotdata.exceptions import ApiException
+from hotdata.models.async_query_response import AsyncQueryResponse
+from hotdata.models.create_database_request import CreateDatabaseRequest
+from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDecl
+from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
+from hotdata.models.load_managed_table_request import LoadManagedTableRequest
+from hotdata.models.query_request import QueryRequest
+from hotdata.models.query_response import QueryResponse
+from hotdata.models.table_info import TableInfo
+from urllib3.exceptions import HTTPError as Urllib3HTTPError
+from urllib3.exceptions import ProtocolError
+
+from hotdata_framework.databases import (
+    DEFAULT_SCHEMA,
+    LoadManagedTableResult,
+    ManagedDatabase,
+    ManagedTable,
+    api_error_message,
+    is_parquet_path,
+    managed_database_from_detail,
+)
+from hotdata_framework.env import (
+    default_api_key,
+    default_host,
+    default_session_id,
+    normalize_host,
+    pick_workspace,
+)
+from hotdata_framework.http import default_http_retries
+from hotdata_framework.result import QueryResult
+
+_TERMINAL = frozenset({"succeeded", "failed", "cancelled"})
+_RESULT_FAILURE = frozenset({"failed", "cancelled"})
+
+
+@dataclass(frozen=True)
+class ResultSummary:
+    result_id: str
+    status: str
+    created_at: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class RunHistoryItem:
+    query_run_id: str
+    status: str
+    created_at: str | None
+    execution_time_ms: int | None
+    result_id: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class HotdataClient:
+    """Thin wrapper around the Hotdata Python SDK with query polling helpers."""
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace_id: str,
+        *,
+        host: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        self._host = normalize_host(host) if host else default_host()
+        self._api_key = api_key
+        self._workspace_id = workspace_id
+        self._session_id = session_id
+        self._config = Configuration(
+            host=self._host,
+            api_key=api_key,
+            workspace_id=workspace_id,
+            session_id=session_id,
+            retries=default_http_retries(),
+        )
+        self._api = ApiClient(self._config)
+
+    @classmethod
+    def from_env(cls) -> HotdataClient:
+        api_key = default_api_key()
+        if not api_key:
+            raise RuntimeError("HOTDATA_API_KEY must be set.")
+        host = default_host()
+        session = default_session_id()
+        workspace_id = pick_workspace(api_key, host, session)
+        return cls(api_key, workspace_id, host=host, session_id=session)
+
+    @property
+    def workspace_id(self) -> str:
+        return self._workspace_id
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    @property
+    def api(self) -> ApiClient:
+        return self._api
+
+    def close(self) -> None:
+        self._api.close()
+
+    def __enter__(self) -> HotdataClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def connections(self) -> ConnectionsApi:
+        return ConnectionsApi(self._api)
+
+    def _databases_api(self) -> DatabasesApi:
+        return DatabasesApi(self._api)
+
+    def _information_schema(self) -> InformationSchemaApi:
+        return InformationSchemaApi(self._api)
+
+    def _query_api(self) -> QueryApi:
+        return QueryApi(self._api)
+
+    def _query_runs_api(self) -> QueryRunsApi:
+        return QueryRunsApi(self._api)
+
+    def _results_api(self) -> ResultsApi:
+        return ResultsApi(self._api)
+
+    def query_runs(self) -> QueryRunsApi:
+        return self._query_runs_api()
+
+    def results(self) -> ResultsApi:
+        return self._results_api()
+
+    def uploads(self) -> UploadsApi:
+        return UploadsApi(self._api)
+
+    def list_managed_databases(self) -> list[ManagedDatabase]:
+        listing = self._databases_api().list_databases()
+        result: list[ManagedDatabase] = []
+        for summary in listing.databases:
+            try:
+                detail = self._databases_api().get_database(summary.id)
+                result.append(managed_database_from_detail(detail))
+            except ApiException:
+                pass
+        return result
+
+    def resolve_managed_database(self, name_or_id: str) -> ManagedDatabase:
+        # Try direct ID lookup first
+        try:
+            detail = self._databases_api().get_database(name_or_id)
+            return managed_database_from_detail(detail)
+        except ApiException as e:
+            if e.status != 404:
+                raise RuntimeError(api_error_message(e)) from e
+
+        # Fall back to description-based lookup
+        listing = self._databases_api().list_databases()
+        match_id: str | None = None
+        for db in listing.databases:
+            if db.name == name_or_id:
+                match_id = db.id
+                break
+        if match_id is None:
+            raise KeyError(f"No database named or with id {name_or_id!r}")
+        try:
+            detail = self._databases_api().get_database(match_id)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return managed_database_from_detail(detail)
+
+    def create_managed_database(
+        self,
+        description: str | None = None,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+        tables: list[str] | None = None,
+        expires_at: str | None = None,
+    ) -> ManagedDatabase:
+        schemas = None
+        if tables:
+            schemas = [
+                DatabaseDefaultSchemaDecl(
+                    name=schema,
+                    tables=[DatabaseDefaultTableDecl(name=t) for t in tables],
+                )
+            ]
+        request = CreateDatabaseRequest(
+            name=description,
+            schemas=schemas,
+            expires_at=expires_at,
+        )
+        try:
+            created = self._databases_api().create_database(request)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return managed_database_from_detail(created)
+
+    def delete_managed_database(self, name_or_id: str) -> None:
+        db = self.resolve_managed_database(name_or_id)
+        try:
+            self._databases_api().delete_database(db.id)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+
+    def list_managed_tables(
+        self,
+        database: str,
+        *,
+        schema: str | None = None,
+    ) -> list[ManagedTable]:
+        db = self.resolve_managed_database(database)
+        rows: list[ManagedTable] = []
+        for t in self.iter_tables(connection_id=db.default_connection_id):
+            if schema is not None and t.var_schema != schema:
+                continue
+            rows.append(
+                ManagedTable(
+                    full_name=f"{db.id}.{t.var_schema}.{t.table}",
+                    schema=t.var_schema,
+                    table=t.table,
+                    synced=t.synced,
+                    last_sync=t.last_sync,
+                )
+            )
+        rows.sort(key=lambda row: (row.schema, row.table))
+        return rows
+
+    def upload_parquet(self, path: str) -> str:
+        if not is_parquet_path(path):
+            raise ValueError(f"Managed table loads require a parquet file (got {path!r})")
+        with open(path, "rb") as f:
+            data = f.read()
+        try:
+            uploaded = self.uploads().upload_file(
+                data,
+                _content_type="application/octet-stream",
+            )
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return uploaded.id
+
+    def load_managed_table(
+        self,
+        database: str,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+        upload_id: str | None = None,
+        file: str | None = None,
+    ) -> LoadManagedTableResult:
+        if (upload_id is None) == (file is None):
+            raise ValueError("Exactly one of upload_id or file is required")
+        db = self.resolve_managed_database(database)
+        if upload_id is not None:
+            resolved_upload_id = upload_id
+        else:
+            assert file is not None
+            resolved_upload_id = self.upload_parquet(file)
+        request = LoadManagedTableRequest(
+            mode="replace",
+            upload_id=resolved_upload_id,
+        )
+        try:
+            loaded = self.connections().load_managed_table(
+                db.default_connection_id,
+                schema,
+                table,
+                request,
+            )
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return LoadManagedTableResult(
+            connection_id=loaded.connection_id,
+            schema_name=loaded.schema_name,
+            table_name=loaded.table_name,
+            row_count=loaded.row_count,
+            full_name=f"{db.id}.{loaded.schema_name}.{loaded.table_name}",
+        )
+
+    def delete_managed_table(
+        self,
+        database: str,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+    ) -> None:
+        db = self.resolve_managed_database(database)
+        try:
+            self.connections().delete_managed_table(db.default_connection_id, schema, table)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+
+    def list_recent_results(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ResultSummary]:
+        listing = self.results().list_results(limit=limit, offset=offset)
+        return [
+            ResultSummary(
+                result_id=r.id,
+                status=r.status,
+                created_at=r.created_at,
+            )
+            for r in listing.results
+        ]
+
+    def list_run_history(
+        self,
+        *,
+        limit: int = 20,
+    ) -> list[RunHistoryItem]:
+        listing = self.query_runs().list_query_runs(limit=limit)
+        return [
+            RunHistoryItem(
+                query_run_id=r.id,
+                status=r.status,
+                created_at=r.created_at,
+                execution_time_ms=r.execution_time_ms,
+                result_id=r.result_id,
+            )
+            for r in listing.query_runs
+        ]
+
+    def iter_tables(
+        self,
+        *,
+        connection_id: str | None = None,
+        include_columns: bool = False,
+        page_size: int = 200,
+    ) -> Iterator[TableInfo]:
+        cursor: str | None = None
+        while True:
+            resp = self._information_schema().information_schema(
+                connection_id=connection_id,
+                include_columns=include_columns,
+                limit=page_size,
+                cursor=cursor,
+            )
+            yield from resp.tables
+            if not resp.has_more or not resp.next_cursor:
+                break
+            cursor = resp.next_cursor
+
+    def qualified_table_name(self, t: TableInfo) -> str:
+        return f"{t.connection}.{t.var_schema}.{t.table}"
+
+    def list_qualified_table_names(
+        self, *, limit: int = 5000, connection_id: str | None = None
+    ) -> list[str]:
+        out: list[str] = []
+        for t in self.iter_tables(connection_id=connection_id):
+            out.append(self.qualified_table_name(t))
+            if len(out) >= limit:
+                break
+        return sorted(out)
+
+    def connection_id_by_name(self) -> dict[str, str]:
+        listing = self.connections().list_connections()
+        id_map: dict[str, str] = {}
+        duplicate_names: set[str] = set()
+        for c in listing.connections:
+            if c.name in id_map and id_map[c.name] != c.id:
+                duplicate_names.add(c.name)
+            id_map[c.name] = c.id
+        if duplicate_names:
+            names = ", ".join(sorted(duplicate_names))
+            raise RuntimeError(
+                f"Duplicate connection names found: {names}. Use an explicit connection_id."
+            )
+        return id_map
+
+    def columns_for_qualified(
+        self,
+        qualified: str,
+        *,
+        connection_id: str | None = None,
+    ) -> list[TableInfo]:
+        parts = qualified.split(".")
+        if len(parts) < 3:
+            raise ValueError(f"Expected connection.schema.table, got {qualified!r}")
+        conn_name, schema_name, table_name = (
+            parts[0],
+            parts[1],
+            ".".join(parts[2:]),
+        )
+        conn_id = connection_id
+        if conn_id is None:
+            id_map = self.connection_id_by_name()
+            conn_id = id_map.get(conn_name)
+            if not conn_id:
+                raise KeyError(f"Unknown connection {conn_name!r}")
+        resp = self._information_schema().information_schema(
+            connection_id=conn_id,
+            var_schema=schema_name,
+            table=table_name,
+            include_columns=True,
+            limit=10,
+        )
+        if not resp.tables:
+            return []
+        first = resp.tables[0]
+        return first.columns or []
+
+    def _poll_query_run(
+        self,
+        query_run_id: str,
+        *,
+        timeout_s: float = 300.0,
+        interval_s: float = 0.5,
+    ):
+        runs = self._query_runs_api()
+        deadline = time.monotonic() + timeout_s
+        last = None
+        while time.monotonic() < deadline:
+            last = runs.get_query_run(query_run_id)
+            if last.status in _TERMINAL:
+                return last
+            time.sleep(interval_s)
+        raise TimeoutError(
+            f"Query run {query_run_id} did not finish within {timeout_s}s "
+            f"(last status: {getattr(last, 'status', None)})"
+        )
+
+    def _wait_result_ready(
+        self,
+        result_id: str,
+        *,
+        timeout_s: float = 300.0,
+        interval_s: float = 0.5,
+    ):
+        results = self._results_api()
+        deadline = time.monotonic() + timeout_s
+        last = None
+        while time.monotonic() < deadline:
+            last = results.get_result(result_id)
+            if last.status == "ready":
+                return last
+            if last.status in _RESULT_FAILURE:
+                raise RuntimeError(last.error_message or f"Result {last.status}")
+            time.sleep(interval_s)
+        raise TimeoutError(
+            f"Result {result_id} not ready within {timeout_s}s "
+            f"(last status: {getattr(last, 'status', None)})"
+        )
+
+    def execute_sql(self, sql: str, *, database: str | None = None) -> QueryResult:
+        """Execute SQL and return a :class:`QueryResult`.
+
+        Pass ``database`` to scope the query to a managed database.  The name
+        is resolved to a database ID once before the retry loop, and the
+        ``X-Database-Id`` header is sent with every attempt.  Inside a managed
+        database the built-in catalog is always ``"default"``, so table
+        references should use ``"default"."<schema>"."<table>"``.
+        """
+        database_id = self.resolve_managed_database(database).id if database else None
+        last_err: BaseException | None = None
+        for attempt in range(3):
+            try:
+                return self._execute_sql_once(sql, database_id=database_id)
+            except (ProtocolError, ConnectionResetError, Urllib3HTTPError) as e:
+                last_err = e
+                if attempt == 2:
+                    raise
+                time.sleep(0.2 * (2**attempt))
+        raise last_err  # pragma: no cover
+
+    def _execute_sql_once(self, sql: str, *, database_id: str | None = None) -> QueryResult:
+        q = self._query_api()
+        try:
+            if database_id:
+                raw = q.query(QueryRequest(sql=sql), x_database_id=database_id)
+            else:
+                raw = q.query(QueryRequest(sql=sql))
+        except ApiException as e:
+            raise RuntimeError(e.reason or str(e)) from e
+
+        if isinstance(raw, AsyncQueryResponse):
+            run = self._poll_query_run(raw.query_run_id)
+            if run.status != "succeeded":
+                raise RuntimeError(run.error_message or f"Query failed ({run.status})")
+            if run.result_id:
+                persisted = self._wait_result_ready(run.result_id)
+                return QueryResult.from_get_result(persisted)
+            raise RuntimeError("Query succeeded but no result_id was returned.")
+
+        if isinstance(raw, QueryResponse):
+            return QueryResult.from_query_response(raw)
+
+        raise RuntimeError(f"Unexpected query response type: {type(raw)!r}")
+
+    def get_result(self, result_id: str) -> QueryResult:
+        r = self._results_api().get_result(result_id)
+        if r.status != "ready":
+            r = self._wait_result_ready(result_id)
+        return QueryResult.from_get_result(r)
+
+
+def from_env() -> HotdataClient:
+    return HotdataClient.from_env()

hotdata_framework/databases.py

@@ -0,0 +1,61 @@
+"""Managed database helpers (Hotdata-owned catalogs with parquet table loads)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from hotdata.exceptions import ApiException
+
+DEFAULT_SCHEMA = "public"
+
+
+@dataclass(frozen=True)
+class ManagedDatabase:
+    id: str
+    description: str | None
+    default_connection_id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ManagedTable:
+    full_name: str
+    schema: str
+    table: str
+    synced: bool
+    last_sync: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class LoadManagedTableResult:
+    connection_id: str
+    schema_name: str
+    table_name: str
+    row_count: int
+    full_name: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def is_parquet_path(path: str) -> bool:
+    return Path(path).suffix.lower() == ".parquet"
+
+
+def managed_database_from_detail(detail: Any) -> ManagedDatabase:
+    return ManagedDatabase(
+        id=str(detail.id),
+        description=detail.name,
+        default_connection_id=str(detail.default_connection_id),
+    )
+
+
+def api_error_message(exc: ApiException) -> str:
+    return exc.reason or str(exc)

hotdata_framework/env.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from hotdata import ApiClient, Configuration
+from hotdata.api.workspaces_api import WorkspacesApi
+
+
+def normalize_host(url: str) -> str:
+    u = url.rstrip("/")
+    if u.endswith("/v1"):
+        u = u[:-3]
+    parsed = urlparse(u)
+    if not parsed.scheme or not parsed.netloc:
+        return u
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def default_api_key() -> str:
+    return os.environ.get("HOTDATA_API_KEY", "")
+
+
+def explicit_workspace_id() -> str | None:
+    return os.environ.get("HOTDATA_WORKSPACE")
+
+
+def default_host() -> str:
+    raw = os.environ.get("HOTDATA_API_URL", "https://api.hotdata.dev")
+    return normalize_host(raw)
+
+
+def default_session_id() -> str | None:
+    return os.environ.get("HOTDATA_SANDBOX")
+
+
+def list_workspaces(api_key: str, host: str, session_id: str | None):
+    cfg = Configuration(
+        host=host,
+        api_key=api_key,
+        workspace_id=None,
+        session_id=session_id,
+    )
+    with ApiClient(cfg) as api:
+        listing = WorkspacesApi(api).list_workspaces()
+    return listing.workspaces
+
+
+@dataclass(frozen=True)
+class WorkspaceSelection:
+    workspace_id: str
+    source: str
+    workspaces: list
+
+
+def resolve_workspace_selection(
+    api_key: str, host: str, session_id: str | None
+) -> WorkspaceSelection:
+    explicit = explicit_workspace_id()
+    if explicit:
+        return WorkspaceSelection(
+            workspace_id=explicit,
+            source="explicit_env",
+            workspaces=[],
+        )
+    workspaces = list_workspaces(api_key, host, session_id)
+    if not workspaces:
+        raise RuntimeError("No Hotdata workspaces found for this API key.")
+    active = [w for w in workspaces if w.active]
+    chosen = active[0] if active else workspaces[0]
+    return WorkspaceSelection(
+        workspace_id=chosen.public_id,
+        source="active" if active else "first",
+        workspaces=workspaces,
+    )
+
+
+def pick_workspace(api_key: str, host: str, session_id: str | None) -> str:
+    selection = resolve_workspace_selection(api_key, host, session_id)
+    return selection.workspace_id

hotdata_framework/errors.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from hotdata.rest import ApiException
+
+
+class HotdataError(RuntimeError):
+    pass
+
+
+class HotdataTransientError(HotdataError):
+    pass
+
+
+class HotdataTerminalError(HotdataError):
+    pass
+
+
+def classify_sdk_error(error: Exception) -> HotdataError:
+    if isinstance(error, TimeoutError):
+        return HotdataTransientError(str(error))
+    if isinstance(error, ConnectionError):
+        return HotdataTransientError(str(error))
+    if isinstance(error, ApiException):
+        status_code = int(error.status or 0)
+        message = f"{status_code}: {error.reason or 'unknown error'}"
+        if status_code in (408, 409, 425, 429):
+            return HotdataTransientError(message)
+        if 500 <= status_code <= 599:
+            return HotdataTransientError(message)
+        return HotdataTerminalError(message)
+    return HotdataTerminalError(str(error))

hotdata_framework/health.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from hotdata.exceptions import ApiException
+
+from hotdata_framework.client import HotdataClient
+
+
+def workspace_health_lines(client: HotdataClient) -> tuple[bool, list[str]]:
+    """Return ``(ok, parts)`` where ``parts`` are short markdown fragments.
+
+    On failure, ``ok`` is False and ``parts`` is a single-element list with the error text.
+    """
+    try:
+        listing = client.connections().list_connections()
+        n = len(listing.connections)
+        lines = [
+            "**API** reachable",
+            f"**workspace** `{client.workspace_id}`",
+            f"**connections** {n}",
+        ]
+        if client.session_id:
+            lines.append(f"**sandbox** `{client.session_id}`")
+        return True, lines
+    except ApiException as e:
+        return False, [e.reason or str(e)]
+    except Exception as e:
+        return False, [str(e)]

hotdata_framework/http.py

@@ -0,0 +1,17 @@
+"""HTTP client defaults for Hotdata SDK :class:`~hotdata.Configuration`."""
+
+from __future__ import annotations
+
+from urllib3.util.retry import Retry
+
+
+def default_http_retries() -> Retry:
+    """Retry transient connection failures (e.g. stale pooled sockets)."""
+    return Retry(
+        total=3,
+        connect=3,
+        read=3,
+        backoff_factor=0.2,
+        status_forcelist=(502, 503, 504),
+        allowed_methods=frozenset(["GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"]),
+    )

hotdata_framework/managed_client.py

@@ -0,0 +1,184 @@
+"""Retry-wrapped managed-database client shared by Hotdata adapter packages.
+
+Both hotdata-airflow and hotdata-dlt-destination import this module so that
+the higher-level client logic (retries, Arrow queries, table management) lives
+in one place rather than being duplicated per adapter.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import pyarrow as pa
+from hotdata.api.query_api import QueryApi
+from hotdata.api.query_runs_api import QueryRunsApi
+from hotdata.api.results_api import ResultsApi
+from hotdata.arrow import ResultsApi as ArrowResultsApi
+from hotdata.models.async_query_response import AsyncQueryResponse
+from hotdata.models.query_request import QueryRequest
+from hotdata.models.query_response import QueryResponse
+
+from hotdata_framework.client import HotdataClient as RuntimeClient
+from hotdata_framework.databases import LoadManagedTableResult, ManagedDatabase
+from hotdata_framework.errors import (
+    HotdataTransientError,
+    classify_sdk_error,
+)
+
+T = TypeVar("T")
+
+
+class ManagedDatabaseClient:
+    """Managed-database client with bounded retries over hotdata-framework.
+
+    This is the shared client used by Hotdata adapter packages (Airflow,
+    dlt, etc.).  It wraps the lower-level RuntimeClient with retry logic,
+    Arrow-based result fetching, and convenience helpers for the managed
+    database lifecycle.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        workspace_id: str,
+        api_base_url: str,
+        max_retries: int,
+        retry_backoff_seconds: float,
+    ) -> None:
+        self._max_retries = max_retries
+        self._retry_backoff_seconds = retry_backoff_seconds
+        self._runtime = RuntimeClient(
+            api_key,
+            workspace_id,
+            host=api_base_url.rstrip("/"),
+        )
+
+    def close(self) -> None:
+        self._runtime.close()
+
+    def ensure_managed_database(
+        self,
+        name: str,
+        *,
+        schema: str,
+        tables: list[str],
+        create_if_missing: bool,
+    ) -> ManagedDatabase:
+        def operation() -> ManagedDatabase:
+            try:
+                return self._runtime.resolve_managed_database(name)
+            except KeyError:
+                if not create_if_missing:
+                    raise
+                return self._runtime.create_managed_database(
+                    description=name,
+                    schema=schema,
+                    tables=sorted(set(tables)),
+                )
+
+        return self._request_with_retry(operation)
+
+    def table_is_synced(self, database: str, table: str, *, schema: str) -> bool:
+        for managed_table in self._runtime.list_managed_tables(database, schema=schema):
+            if managed_table.table == table:
+                return managed_table.synced
+        return False
+
+    def fetch_table(self, *, database: str, schema: str, table: str) -> pa.Table | None:
+        def operation() -> pa.Table | None:
+            if not self.table_is_synced(database, table, schema=schema):
+                return None
+            db = self._runtime.resolve_managed_database(database)
+            sql = f'SELECT * FROM "default"."{schema}"."{table}"'
+            result_id = self._query_database_scoped(sql, database_id=db.id)
+            if result_id is None:
+                return None
+            return ArrowResultsApi(self._runtime.api).get_result_arrow(result_id)
+
+        return self._request_with_retry(operation)
+
+    _QUERY_TIMEOUT_SECONDS = 300.0
+
+    def _query_database_scoped(self, sql: str, *, database_id: str) -> str | None:
+        raw = QueryApi(self._runtime.api).query(
+            QueryRequest(sql=sql),
+            x_database_id=database_id,
+        )
+        if isinstance(raw, QueryResponse):
+            return raw.result_id
+
+        if isinstance(raw, AsyncQueryResponse):
+            runs = QueryRunsApi(self._runtime.api)
+            deadline = time.monotonic() + self._QUERY_TIMEOUT_SECONDS
+            result_id: str | None = None
+            while time.monotonic() < deadline:
+                run = runs.get_query_run(raw.query_run_id)
+                if run.status == "succeeded":
+                    result_id = run.result_id
+                    break
+                if run.status in ("failed", "cancelled"):
+                    raise RuntimeError(run.error_message or f"Query {run.status}")
+                time.sleep(0.5)
+            else:
+                raise TimeoutError(
+                    f"Managed database query timed out after {self._QUERY_TIMEOUT_SECONDS}s"
+                )
+            return self._wait_result_ready(result_id)
+
+        return None
+
+    def _wait_result_ready(self, result_id: str | None) -> str | None:
+        if result_id is None:
+            return None
+        results = ResultsApi(self._runtime.api)
+        deadline = time.monotonic() + self._QUERY_TIMEOUT_SECONDS
+        while time.monotonic() < deadline:
+            r = results.get_result(result_id)
+            if r.status == "ready":
+                return result_id
+            if r.status in ("failed", "cancelled"):
+                raise RuntimeError(r.error_message or f"Result {r.status}")
+            time.sleep(0.3)
+        raise TimeoutError(f"Result {result_id} not ready after {self._QUERY_TIMEOUT_SECONDS}s")
+
+    def fetch_table_rows(self, *, database: str, schema: str, table: str) -> list[dict[str, Any]]:
+        result = self.fetch_table(database=database, schema=schema, table=table)
+        return result.to_pylist() if result is not None else []
+
+    def upload_parquet(self, path: str) -> str:
+        return self._request_with_retry(lambda: self._runtime.upload_parquet(path))
+
+    def load_managed_table(
+        self,
+        database: str,
+        table: str,
+        *,
+        schema: str,
+        upload_id: str,
+    ) -> LoadManagedTableResult:
+        return self._request_with_retry(
+            lambda: self._runtime.load_managed_table(
+                database,
+                table,
+                schema=schema,
+                upload_id=upload_id,
+            )
+        )
+
+    _MAX_BACKOFF_SECONDS = 30.0
+
+    def _request_with_retry(self, operation: Callable[[], T]) -> T:
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                return operation()
+            except Exception as error:
+                mapped_error = classify_sdk_error(error.__cause__ or error)
+                if isinstance(mapped_error, HotdataTransientError) and attempt < self._max_retries:
+                    backoff = min(self._retry_backoff_seconds * attempt, self._MAX_BACKOFF_SECONDS)
+                    time.sleep(backoff)
+                    continue
+                raise mapped_error from error
+        raise RuntimeError("No retry attempts configured")

hotdata_framework/result.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from hotdata.models.get_result_response import GetResultResponse
+from hotdata.models.query_response import QueryResponse
+
+
+@dataclass
+class QueryResult:
+    """Tabular result from a Hotdata query or stored result id."""
+
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    result_id: str | None
+    query_run_id: str | None
+    execution_time_ms: int | None
+    warning: str | None = None
+    error_message: str | None = None
+
+    def to_records(
+        self,
+        *,
+        max_rows: int | None = None,
+    ) -> list[dict[str, Any]]:
+        rows = self.rows if max_rows is None else self.rows[:max_rows]
+        return [dict(zip(self.columns, row, strict=True)) for row in rows]
+
+    def metadata_dict(self) -> dict[str, Any]:
+        return {
+            "row_count": self.row_count,
+            "column_count": len(self.columns),
+            "result_id": self.result_id,
+            "query_run_id": self.query_run_id,
+            "execution_time_ms": self.execution_time_ms,
+            "warning": self.warning,
+            "error_message": self.error_message,
+        }
+
+    def to_pandas(self):  # type: ignore[no-untyped-def]
+        import pandas as pd
+
+        if not self.columns:
+            return pd.DataFrame()
+        return pd.DataFrame(self.rows, columns=self.columns)
+
+    @classmethod
+    def from_query_response(cls, r: QueryResponse) -> QueryResult:
+        return cls(
+            columns=list(r.columns),
+            rows=[list(row) for row in r.rows],
+            row_count=r.row_count,
+            result_id=r.result_id,
+            query_run_id=r.query_run_id,
+            execution_time_ms=r.execution_time_ms,
+            warning=r.warning,
+            error_message=None,
+        )
+
+    @classmethod
+    def from_get_result(cls, r: GetResultResponse) -> QueryResult:
+        cols = list(r.columns or [])
+        row_data = [list(row) for row in (r.rows or [])]
+        return cls(
+            columns=cols,
+            rows=row_data,
+            row_count=r.row_count or 0,
+            result_id=r.result_id,
+            query_run_id=None,
+            execution_time_ms=None,
+            warning=None,
+            error_message=r.error_message,
+        )

hotdata_framework-0.4.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: hotdata-framework
+Version: 0.4.0
+Summary: Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases
+Project-URL: Homepage, https://www.hotdata.dev
+Project-URL: Documentation, https://www.hotdata.dev/docs
+Project-URL: Repository, https://github.com/hotdata-dev/sdk-python-framework
+License: MIT
+Keywords: analytics,arrow,data,framework,hotdata,pandas,python,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: hotdata>=0.4.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Description-Content-Type: text/markdown
+
+# hotdata-framework
+
+**A Python framework for building Hotdata integrations.**
+
+Shared runtime primitives for Hotdata integrations: workspace/session semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.
+
+Runtime boundary and guarantees are defined in `CONTRACT.md`.
+
+## Features
+
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, `HOTDATA_WORKSPACE`, and `HOTDATA_SANDBOX`.
+- **Workspace resolution** — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
+- **Sandbox/session propagation** — pass sandbox session context through the SDK via `X-Session-Id`.
+- **HTTP resilience** — configure SDK retries for transient connection failures and retry SQL execution on stale pooled sockets.
+- **SQL execution helper** — run SQL through `POST /v1/query`, poll async query runs when needed, and return a `QueryResult`.
+- **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
+- **History helpers** — list recent results and query run history with normalized dataclasses.
+- **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
+- **Health helpers** — build compact API/workspace health summaries for UI integrations.
+
+Install:
+
+```bash
+uv pip install hotdata-framework
+# or: pip install hotdata-framework
+```
+
+Example:
+
+```bash
+python examples/basic_usage.py
+```
+
+Development (uses **uv**; creates `.venv/` in this repo):
+
+```bash
+uv sync --locked
+uv run pytest
+```
+
+`uv.lock` is checked in so CI can run `uv sync --locked`. The default **dev** group (pytest) is enabled via `[tool.uv] default-groups`.

hotdata_framework-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+hotdata_framework/__init__.py,sha256=XTAkQjuxshKLAKMTs-KoDeQBaUMYW4MXEskXRy-WRnM,1719
+hotdata_framework/client.py,sha256=eXer2fHp4AWqC_NWlkUOSRCbnC8Nw3PR0r7SIv1zmJg,17653
+hotdata_framework/databases.py,sha256=wajadlyxl5pB1mgLos-cxr3Yx4pnZiTDyY49acxWpkQ,1313
+hotdata_framework/env.py,sha256=1gm56sQhJ2rdEtfvAzfXc0P44IodLLmSP15Uax_WnoM,2190
+hotdata_framework/errors.py,sha256=8baHY-bcR505yh_CIrBz5cZ0GU5SWei6t4cDImLRwzs,897
+hotdata_framework/health.py,sha256=fFmqN-aPm0gHXj_j9KVB_T6T1fe2clI6aC45R9HxhgM,894
+hotdata_framework/http.py,sha256=k2Ie-9HUennILAXAtQ66N7vGNpA8m1VPJ3F_FlTpN2o,507
+hotdata_framework/managed_client.py,sha256=FRV93QHDlZ6GhtELzFhHq5DGbor7clx9Pa87h5f46vA,6825
+hotdata_framework/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hotdata_framework/result.py,sha256=q39xn--aRRuDMxXr4Y6pZcr9u6E8s_5PYMBREA3gloA,2303
+hotdata_framework-0.4.0.dist-info/METADATA,sha256=qB4uNmdGzG5iGsoNBWqsFfnM2bbEY1wD8S5xHk6Tmao,3213
+hotdata_framework-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hotdata_framework-0.4.0.dist-info/RECORD,,

hotdata_framework-0.4.0.dist-info/WHEEL

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