hotdata-framework 0.5.0__tar.gz → 0.6.1__tar.gz

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/CHANGELOG.md

@@ -8,6 +8,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.6.1] - 2026-07-08
+
+### Fixed
+
+- `ManagedDatabaseClient.fetch_table` now carries the `X-Database-Id` scope header on the result poll, the query-run poll, and the Arrow fetch — not only on the query submit. Results of database-scoped queries are themselves database-scoped, so every read against an existing synced table (merge/append loads, dlt state restore) failed with `400: Bad Request` once the table had data (dlthubworker#70).
+- API error messages now include the response body (flattened, truncated to 500 chars). `400: Bad Request` alone hid the server's actual explanation.
+
+### Changed
+
+- The `hotdata` SDK dependency is now `>=0.6.0`, and the scope above rides its native `x_database_id` parameters (`get_result`, `get_query_run`, `get_result_arrow`). Note 0.6.0 made `x_database_id` **required** on `get_result_arrow`, so older framework releases cannot run on it.
+
+## [0.6.0] - 2026-06-30
+
+### Added
+
+- `HotdataClient.add_managed_table(database, table, *, schema)` declares a new table on an existing managed database (wrapping the SDK `add_database_table` endpoint). This allows additive schema evolution without recreating the database.
+
 ## [0.5.0] - 2026-06-28
 
 ### Changed

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata-framework
-Version: 0.5.0
+Version: 0.6.1
 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
@@ -21,7 +21,7 @@ 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.5.0
+Requires-Dist: hotdata>=0.6.0
 Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=14.0
 Description-Content-Type: text/markdown

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/hotdata_framework/client.py

@@ -14,6 +14,7 @@ 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.add_managed_table_request import AddManagedTableRequest
 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
@@ -300,6 +301,33 @@ class HotdataClient:
             full_name=f"{db.id}.{loaded.schema_name}.{loaded.table_name}",
         )
 
+    def add_managed_table(
+        self,
+        database: str,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+    ) -> ManagedTable:
+        """Declare a new table on an existing managed database.
+
+        The table is added empty (declared-but-unloaded); populate it with
+        :meth:`load_managed_table`. Use this to evolve a managed database's
+        schema after creation without recreating it.
+        """
+        db = self.resolve_managed_database(database)
+        request = AddManagedTableRequest(name=table)
+        try:
+            self._databases_api().add_database_table(db.id, schema, request)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return ManagedTable(
+            full_name=f"{db.id}.{schema}.{table}",
+            schema=schema,
+            table=table,
+            synced=False,
+            last_sync=None,
+        )
+
     def delete_managed_table(
         self,
         database: str,

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/hotdata_framework/databases.py

@@ -58,4 +58,9 @@ def managed_database_from_detail(detail: Any) -> ManagedDatabase:
 
 
 def api_error_message(exc: ApiException) -> str:
-    return exc.reason or str(exc)
+    reason = exc.reason or str(exc)
+    # Keep the response body: it carries the API's actual explanation.
+    body = getattr(exc, "body", None)
+    if body:
+        return f"{reason}: {' '.join(str(body).split())[:500]}"
+    return reason

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/hotdata_framework/errors.py

@@ -23,6 +23,11 @@ def classify_sdk_error(error: Exception) -> HotdataError:
     if isinstance(error, ApiException):
         status_code = int(error.status or 0)
         message = f"{status_code}: {error.reason or 'unknown error'}"
+        # The response body is where the API explains itself (e.g. which
+        # header is missing) — without it "400: Bad Request" is undebuggable.
+        body = getattr(error, "body", None)
+        if body:
+            message = f"{message} — {' '.join(str(body).split())[:500]}"
         if status_code in (408, 409, 425, 429):
             return HotdataTransientError(message)
         if 500 <= status_code <= 599:

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/hotdata_framework/managed_client.py

@@ -110,10 +110,22 @@ class ManagedDatabaseClient:
             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._fetch_result_arrow(result_id, database_id=db.id)
 
         return self._request_with_retry(operation)
 
+    def _fetch_result_arrow(self, result_id: str, *, database_id: str) -> pa.Table:
+        """Fetch a ready result as Arrow, carrying the database scope.
+
+        Results of database-scoped queries are themselves database-scoped —
+        the results endpoints reject requests without the scope. The hotdata
+        0.6.0 SDK exposes (and requires) ``x_database_id`` on the Arrow
+        helper directly.
+        """
+        return ArrowResultsApi(self._runtime.api).get_result_arrow(
+            result_id, x_database_id=database_id
+        )
+
     def _poll(
         self,
         fetch: Callable[[], S],
@@ -146,26 +158,30 @@ class ManagedDatabaseClient:
             # under ``result_id``; that result may be ``processing`` when the
             # inline preview returns, so wait for ``ready`` before the caller
             # fetches it as Arrow.
-            return self._wait_result_ready(raw.result_id)
+            return self._wait_result_ready(raw.result_id, database_id=database_id)
         if isinstance(raw, AsyncQueryResponse):
-            return self._wait_result_ready(self._await_query_run(raw.query_run_id))
+            run_result = self._await_query_run(raw.query_run_id, database_id=database_id)
+            return self._wait_result_ready(run_result, database_id=database_id)
         return None
 
-    def _await_query_run(self, query_run_id: str) -> str | None:
+    def _await_query_run(self, query_run_id: str, *, database_id: str) -> str | None:
         runs = QueryRunsApi(self._runtime.api)
         run = self._poll(
-            lambda: runs.get_query_run(query_run_id),
+            # Runs (like results) of database-scoped queries are database-scoped.
+            lambda: runs.get_query_run(query_run_id, x_database_id=database_id),
             is_ready=lambda r: r.status == "succeeded",
             describe="Query",
         )
         return run.result_id
 
-    def _wait_result_ready(self, result_id: str | None) -> str | None:
+    def _wait_result_ready(self, result_id: str | None, *, database_id: str) -> str | None:
         if result_id is None:
             return None
         results = ResultsApi(self._runtime.api)
         self._poll(
-            lambda: results.get_result(result_id),
+            # The stored result of a database-scoped query 400s without the
+            # database scope.
+            lambda: results.get_result(result_id, x_database_id=database_id),
             is_ready=lambda r: r.status == "ready",
             describe=f"Result {result_id}",
         )

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hotdata-framework"
-version = "0.5.0"
+version = "0.6.1"
 description = "Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,7 +26,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "hotdata>=0.5.0",
+  "hotdata>=0.6.0",
   "pandas>=2.0",
   "pyarrow>=14.0",
 ]

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/tests/test_client.py

@@ -178,6 +178,35 @@ def test_columns_for_qualified_prefers_explicit_connection_id():
     assert fake_api.kwargs["connection_id"] == "conn_explicit"
 
 
+def test_add_managed_table_declares_table_on_existing_database():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    fake_db = SimpleNamespace(id="db_1", default_connection_id="conn")
+
+    class FakeDatabasesApi:
+        def __init__(self):
+            self.calls: list[tuple[str, str, str]] = []
+
+        def add_database_table(self, database_id, var_schema, request):
+            self.calls.append((database_id, var_schema, request.name))
+            return SimpleNamespace(
+                connection_id="conn", var_schema=var_schema, table=request.name
+            )
+
+    fake_api = FakeDatabasesApi()
+    with (
+        patch.object(client, "resolve_managed_database", return_value=fake_db),
+        patch.object(client, "_databases_api", return_value=fake_api),
+    ):
+        result = client.add_managed_table("mydb", "orders", schema="public")
+
+    assert fake_api.calls == [("db_1", "public", "orders")]
+    assert result.full_name == "db_1.public.orders"
+    assert result.schema == "public"
+    assert result.table == "orders"
+    assert result.synced is False
+    assert result.last_sync is None
+
+
 def test_list_recent_results_returns_normalized_summaries():
     client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
     listing = SimpleNamespace(

hotdata_framework-0.6.1/tests/test_errors.py

@@ -0,0 +1,49 @@
+"""Error message construction: the API's response body must survive.
+
+"400: Bad Request" alone is undebuggable; the body carries the server's
+actual explanation (e.g. which header was missing). Regression for the
+opaque load failures in dlthubworker#70.
+"""
+
+from __future__ import annotations
+
+from hotdata.rest import ApiException
+
+from hotdata_framework.databases import api_error_message
+from hotdata_framework.errors import (
+    HotdataTerminalError,
+    HotdataTransientError,
+    classify_sdk_error,
+)
+
+BODY = '{"error":{"code":"BAD_REQUEST","message":"X-Database-Id header is required"}}'
+
+
+def test_classify_sdk_error_includes_response_body() -> None:
+    err = classify_sdk_error(ApiException(status=400, reason="Bad Request", body=BODY))
+    assert isinstance(err, HotdataTerminalError)
+    assert "400: Bad Request" in str(err)
+    assert "X-Database-Id header is required" in str(err)
+
+
+def test_classify_sdk_error_without_body_keeps_short_form() -> None:
+    err = classify_sdk_error(ApiException(status=409, reason="Conflict"))
+    assert isinstance(err, HotdataTransientError)
+    assert str(err) == "409: Conflict"
+
+
+def test_classify_sdk_error_truncates_and_flattens_body() -> None:
+    noisy = "x\n" * 1000
+    err = classify_sdk_error(ApiException(status=500, reason="ISE", body=noisy))
+    assert "\n" not in str(err)
+    assert len(str(err)) < 600
+
+
+def test_api_error_message_includes_body() -> None:
+    msg = api_error_message(ApiException(status=400, reason="Bad Request", body=BODY))
+    assert msg.startswith("Bad Request: ")
+    assert "X-Database-Id header is required" in msg
+
+
+def test_api_error_message_without_body() -> None:
+    assert api_error_message(ApiException(status=404, reason="Not Found")) == "Not Found"

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/tests/test_managed_client.py

@@ -50,7 +50,7 @@ def test_fetch_table_waits_for_ready_before_arrow(monkeypatch: pytest.MonkeyPatc
         def __init__(self, api: object) -> None:
             pass
 
-        def get_result(self, result_id: str) -> Any:
+        def get_result(self, result_id: str, **kwargs: Any) -> Any:
             status = next(statuses)
             calls.append(f"get_result:{status}")
             return SimpleNamespace(status=status, result_id=result_id, error_message=None)
@@ -59,7 +59,7 @@ def test_fetch_table_waits_for_ready_before_arrow(monkeypatch: pytest.MonkeyPatc
         def __init__(self, api: object) -> None:
             pass
 
-        def get_result_arrow(self, result_id: str) -> pa.Table:
+        def get_result_arrow(self, result_id: str, **kwargs: Any) -> pa.Table:
             calls.append("arrow")
             return pa.table({"id": [1, 2]})
 
@@ -75,7 +75,20 @@ def test_fetch_table_waits_for_ready_before_arrow(monkeypatch: pytest.MonkeyPatc
         max_retries=1,
         retry_backoff_seconds=0.0,
     )
-    client._runtime = SimpleNamespace(  # type: ignore[assignment]
+    client._runtime = _fake_runtime()
+
+    table = client.fetch_table(database="mydb", schema="public", table="orders")
+
+    assert table is not None
+    assert table.num_rows == 2
+    # The result was polled to readiness, and Arrow was fetched only afterwards.
+    assert "get_result:processing" in calls
+    assert "get_result:ready" in calls
+    assert calls.index("arrow") > calls.index("get_result:ready")
+
+
+def _fake_runtime() -> SimpleNamespace:
+    return SimpleNamespace(
         api=object(),
         resolve_managed_database=lambda name: SimpleNamespace(id="db1", default_connection_id="c"),
         list_managed_tables=lambda database, schema=None: [
@@ -83,11 +96,64 @@ def test_fetch_table_waits_for_ready_before_arrow(monkeypatch: pytest.MonkeyPatc
         ],
     )
 
+
+def test_fetch_table_carries_database_scope_on_result_reads(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Results (and runs) of a database-scoped query are database-scoped:
+    the results endpoints 400 with "X-Database-Id header is required" when
+    the scope is missing. ``fetch_table`` must carry the database id on the
+    result poll and the Arrow fetch, not only on the query submit — the
+    hotdata 0.6.0 SDK exposes ``x_database_id`` on all three.
+
+    Regression: reruns/append loads against an existing synced table failed
+    with an opaque ``400: Bad Request`` (dlthubworker#70) because both reads
+    omitted the scope.
+    """
+    result_scopes: list[str | None] = []
+    arrow_scopes: list[str | None] = []
+
+    class FakeQueryApi:
+        def __init__(self, api: object) -> None:
+            pass
+
+        def query(self, request: object, *, x_database_id: str) -> QueryResponse:
+            assert x_database_id == "db1"
+            return _query_response("rslt1")
+
+    class FakeResultsApi:
+        def __init__(self, api: object) -> None:
+            pass
+
+        def get_result(self, result_id: str, *, x_database_id: str | None = None) -> Any:
+            result_scopes.append(x_database_id)
+            return SimpleNamespace(status="ready", result_id=result_id, error_message=None)
+
+    class FakeArrowResultsApi:
+        def __init__(self, api: object) -> None:
+            pass
+
+        # x_database_id is REQUIRED in the 0.6.0 SDK — mirroring that here
+        # makes this test fail if a caller ever drops the scope again.
+        def get_result_arrow(self, result_id: str, *, x_database_id: str) -> pa.Table:
+            arrow_scopes.append(x_database_id)
+            return pa.table({"id": [1]})
+
+    monkeypatch.setattr(mc, "QueryApi", FakeQueryApi)
+    monkeypatch.setattr(mc, "ResultsApi", FakeResultsApi)
+    monkeypatch.setattr(mc, "ArrowResultsApi", FakeArrowResultsApi)
+
+    client = mc.ManagedDatabaseClient(
+        api_key="k",
+        workspace_id="w",
+        api_base_url="https://example.test",
+        max_retries=1,
+        retry_backoff_seconds=0.0,
+    )
+    client._runtime = _fake_runtime()
+
     table = client.fetch_table(database="mydb", schema="public", table="orders")
 
     assert table is not None
-    assert table.num_rows == 2
-    # The result was polled to readiness, and Arrow was fetched only afterwards.
-    assert "get_result:processing" in calls
-    assert "get_result:ready" in calls
-    assert calls.index("arrow") > calls.index("get_result:ready")
+    assert result_scopes == ["db1"]
+    assert arrow_scopes == ["db1"]

{hotdata_framework-0.5.0 → hotdata_framework-0.6.1}/uv.lock

@@ -86,7 +86,7 @@ wheels = [
 
 [[package]]
 name = "hotdata"
-version = "0.5.0"
+version = "0.6.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pydantic" },
@@ -94,14 +94,14 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f2/d8/79f4906f4a39aacd7a94c7991af63064cecb95015d4fbe4d50757b21c940/hotdata-0.5.0.tar.gz", hash = "sha256:3d0240e6a3e7333e4290d8b3e75afebba43e518b868e1c3e3818fd719a6ab994", size = 170462, upload-time = "2026-06-28T16:28:49.591Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d2/17/6d9e7cbe7e766cd52968653096ce4199d0cb1aa55b73fcfc2979fb9805ff/hotdata-0.6.0.tar.gz", hash = "sha256:c655fd9691a1d65dd4ed51b86f1c27bf8e73268b4c44696987a57a624da35143", size = 214162, upload-time = "2026-07-07T16:44:32.65Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/aa/0e/026a2e03647e3d3c26027b690ea24ef036fbeb314b85517db3d606aab4da/hotdata-0.5.0-py3-none-any.whl", hash = "sha256:e7c4f5f8af6a7b370810fb599e5a166fc4bb569f6f41c506698c4bebfb500fcc", size = 286907, upload-time = "2026-06-28T16:28:48.298Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/0a/4c9f23e1fa85a8d0336681f608c13100e4ab2cf4204846d90374b1bb141b/hotdata-0.6.0-py3-none-any.whl", hash = "sha256:3324758eb0aa37bbcc505ddac524566a8c10fbe0787e226932e8b04d565200c1", size = 312820, upload-time = "2026-07-07T16:44:31.121Z" },
 ]
 
 [[package]]
 name = "hotdata-framework"
-version = "0.5.0"
+version = "0.6.1"
 source = { editable = "." }
 dependencies = [
     { name = "hotdata" },
@@ -120,7 +120,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "hotdata", specifier = ">=0.5.0" },
+    { name = "hotdata", specifier = ">=0.6.0" },
     { name = "pandas", specifier = ">=2.0" },
     { name = "pyarrow", specifier = ">=14.0" },
 ]