hotdata-framework 0.7.3__tar.gz → 0.9.0__tar.gz

hotdata_framework-0.9.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @hotdata-dev/engineers

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/CHANGELOG.md

@@ -8,6 +8,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.9.0] - 2026-07-23
+
+### Added
+
+- `list_managed_tables`, `load_managed_table`, `add_managed_table`,
+  `delete_managed_table`, `delete_managed_database`, and `execute_sql` accept an
+  already-resolved `ManagedDatabase` (as returned by `create_managed_database`)
+  in place of a name/id. When passed one, they skip the `get_database` /
+  `list_databases` read probe. This lets an API key scoped to create + load but
+  not read `/databases` bootstrap a managed database and load into it within a
+  single run: the caller holds the `ManagedDatabase` from `create` and drives
+  the load/add/query ops with zero reads. The name/id string path is unchanged.
+
+## [0.8.0] - 2026-07-20
+
+### Changed
+
+- `load_managed_table` accepts a `key` argument — the merge key columns for
+  `delete`/`update`/`upsert` loads, matched per-load instead of requiring a key
+  declared at table creation. Omit it to use the table's declared key; ignored
+  for `replace`/`append`. Requires `hotdata>=0.8.0`.
+
 ## [0.7.3] - 2026-07-16
 
 ### Changed

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/CONTRACT.md

@@ -56,13 +56,14 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
   adapters should pass `connection_id` when known.
 - `uploads()` returns the uploads API wrapper for parquet staging.
 - `list_managed_databases()` returns all databases via the `/databases` API.
-- `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan).
-- `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front.
+- `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan). A `403` from `/databases` surfaces as `RuntimeError` (forbidden, not absent), preserving the underlying `ApiException` as `__cause__`.
+- `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front. Returns a `ManagedDatabase` (id + `default_connection_id`) sufficient to load without a further read.
 - `delete_managed_database(name_or_id)` deletes a database via the `/databases` API.
 - `list_managed_tables(database, schema=...)` lists tables in a managed database.
 - `upload_parquet(path)` uploads a local parquet file and returns an upload id.
 - `load_managed_table(database, table, schema=..., upload_id=..., file=...)` publishes parquet data into a declared managed table.
 - `delete_managed_table(database, table, schema=...)` deletes a managed table.
+- The `database` argument of `list_managed_tables`, `load_managed_table`, `add_managed_table`, `delete_managed_table`, `delete_managed_database`, and `execute_sql` accepts a name/id **or** an already-resolved `ManagedDatabase`. Passing a `ManagedDatabase` skips the name/id read probe, so a create-scoped key that cannot read `/databases` can load into a database it just created.
 
 ### `QueryResult`
 

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata-framework
-Version: 0.7.3
+Version: 0.9.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
@@ -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.7.0
+Requires-Dist: hotdata>=0.8.0
 Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=14.0
 Description-Content-Type: text/markdown

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/hotdata_framework/client.py

@@ -241,6 +241,19 @@ class HotdataClient:
             raise RuntimeError(api_error_message(e)) from e
         return managed_database_from_detail(detail)
 
+    def _as_managed_database(self, database: str | ManagedDatabase) -> ManagedDatabase:
+        """Return ``database`` as-is if it is already a resolved ``ManagedDatabase``,
+        otherwise resolve it by name or id.
+
+        Passing an already-resolved ``ManagedDatabase`` (e.g. the value returned by
+        :meth:`create_managed_database`) skips the id/name read probe, so callers
+        whose API key may create but not read ``/databases`` can drive loads without
+        a forbidden read.
+        """
+        if isinstance(database, ManagedDatabase):
+            return database
+        return self.resolve_managed_database(database)
+
     def create_managed_database(
         self,
         description: str | None = None,
@@ -275,8 +288,8 @@ class HotdataClient:
             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)
+    def delete_managed_database(self, name_or_id: str | ManagedDatabase) -> None:
+        db = self._as_managed_database(name_or_id)
         try:
             self._databases_api().delete_database(db.id)
         except ApiException as e:
@@ -284,11 +297,11 @@ class HotdataClient:
 
     def list_managed_tables(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         *,
         schema: str | None = None,
     ) -> list[ManagedTable]:
-        db = self.resolve_managed_database(database)
+        db = self._as_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:
@@ -333,17 +346,18 @@ class HotdataClient:
 
     def load_managed_table(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
         upload_id: str | None = None,
         file: str | None = None,
         mode: ManagedLoadMode = "replace",
+        key: list[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)
+        db = self._as_managed_database(database)
         if upload_id is not None:
             resolved_upload_id = upload_id
         else:
@@ -352,6 +366,7 @@ class HotdataClient:
         request = LoadManagedTableRequest(
             mode=mode,
             upload_id=resolved_upload_id,
+            key=key,
         )
         try:
             loaded = self.connections().load_managed_table(
@@ -372,7 +387,7 @@ class HotdataClient:
 
     def add_managed_table(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
@@ -385,7 +400,7 @@ class HotdataClient:
         schema after creation without recreating it. ``key`` sets the
         row-identity columns for delete/update/upsert; omit for keyless.
         """
-        db = self.resolve_managed_database(database)
+        db = self._as_managed_database(database)
         request = AddManagedTableRequest(name=table, key=list(key or []))
         try:
             self._databases_api().add_database_table(db.id, schema, request)
@@ -401,12 +416,12 @@ class HotdataClient:
 
     def delete_managed_table(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
     ) -> None:
-        db = self.resolve_managed_database(database)
+        db = self._as_managed_database(database)
         try:
             self.connections().delete_managed_table(db.default_connection_id, schema, table)
         except ApiException as e:
@@ -567,16 +582,19 @@ class HotdataClient:
             f"(last status: {getattr(last, 'status', None)})"
         )
 
-    def execute_sql(self, sql: str, *, database: str | None = None) -> QueryResult:
+    def execute_sql(
+        self, sql: str, *, database: str | ManagedDatabase | 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
+        Pass ``database`` to scope the query to a managed database.  A name or
+        id is resolved to a database ID once before the retry loop; an
+        already-resolved ``ManagedDatabase`` is used as-is (no read probe).  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
+        database_id = self._as_managed_database(database).id if database else None
         last_err: BaseException | None = None
         for attempt in range(3):
             try:

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/hotdata_framework/managed_client.py

@@ -205,10 +205,15 @@ class ManagedDatabaseClient:
         schema: str,
         upload_id: str,
         mode: ManagedLoadMode = "replace",
+        key: list[str] | None = None,
     ) -> LoadManagedTableResult:
         # append is the only non-idempotent mode: if the server commits the load
         # but the response is lost, a retry re-appends the same rows. Run it
         # at-most-once; every other mode is safe to retry.
+        #
+        # `key` is the merge key for delete/update/upsert loads: when set it is
+        # matched per-load instead of a key declared at table creation. Omit it
+        # to use the table's declared key. Ignored for replace/append.
         return self._request_with_retry(
             lambda: self._runtime.load_managed_table(
                 database,
@@ -216,6 +221,7 @@ class ManagedDatabaseClient:
                 schema=schema,
                 upload_id=upload_id,
                 mode=mode,
+                key=key,
             ),
             retryable=(mode != "append"),
         )

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hotdata-framework"
-version = "0.7.3"
+version = "0.9.0"
 description = "Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,7 +27,7 @@ classifiers = [
 ]
 dependencies = [
   # 0.7.0 adds `key` to table decls (create_managed_database(keys=) / add_managed_table(key=))
-  "hotdata>=0.7.0",
+  "hotdata>=0.8.0",
   "pandas>=2.0",
   "pyarrow>=14.0",
 ]

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/tests/test_client.py

@@ -4,11 +4,134 @@ from types import SimpleNamespace
 from unittest.mock import patch
 
 import pytest
+from hotdata.exceptions import ForbiddenException
 
 from hotdata_framework.client import HotdataClient
+from hotdata_framework.databases import ManagedDatabase
 from hotdata_framework.env import normalize_host, pick_workspace, resolve_workspace_selection
 
 
+class _ForbiddenDatabasesApi:
+    """A `/databases` API that a create-scoped key would see: every read is 403,
+    while the declare-table write succeeds. Counts reads so tests can assert none
+    happened."""
+
+    def __init__(self) -> None:
+        self.read_calls = 0
+        self.add_calls: list[tuple[str, str, str]] = []
+
+    def get_database(self, database_id: str):
+        self.read_calls += 1
+        raise ForbiddenException(status=403)
+
+    def list_databases(self):
+        self.read_calls += 1
+        raise ForbiddenException(status=403)
+
+    def add_database_table(self, database_id, var_schema, request):
+        self.add_calls.append((database_id, var_schema, request.name))
+        return SimpleNamespace(
+            connection_id="conn", var_schema=var_schema, table=request.name
+        )
+
+
+class _FakeConnectionsApi:
+    def __init__(self) -> None:
+        self.load_calls: list[tuple[str, str, str]] = []
+
+    def load_managed_table(self, connection_id, schema, table, request):
+        self.load_calls.append((connection_id, schema, table))
+        return SimpleNamespace(
+            connection_id=connection_id,
+            schema_name=schema,
+            table_name=table,
+            row_count=3,
+        )
+
+
+def test_load_managed_table_with_object_skips_read_probe():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    databases = _ForbiddenDatabasesApi()
+    connections = _FakeConnectionsApi()
+
+    with (
+        patch.object(client, "_databases_api", return_value=databases),
+        patch.object(client, "connections", return_value=connections),
+    ):
+        result = client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+
+    assert databases.read_calls == 0
+    assert connections.load_calls == [("conn_1", "public", "orders")]
+    assert result.full_name == "db_1.public.orders"
+    assert result.row_count == 3
+
+
+def test_add_managed_table_with_object_skips_read_probe():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    databases = _ForbiddenDatabasesApi()
+
+    with patch.object(client, "_databases_api", return_value=databases):
+        result = client.add_managed_table(db, "orders", schema="public")
+
+    assert databases.read_calls == 0
+    assert databases.add_calls == [("db_1", "public", "orders")]
+    assert result.full_name == "db_1.public.orders"
+
+
+def test_execute_sql_with_object_skips_read_probe():
+    from hotdata.models.query_response import QueryResponse as _QR
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_abc", description="mydb", default_connection_id="conn_1")
+    databases = _ForbiddenDatabasesApi()
+
+    class FakeQueryApi:
+        def __init__(self):
+            self.calls: list[dict] = []
+
+        def query(self, request, **kwargs):
+            self.calls.append(kwargs)
+            return _QR(
+                columns=["n"],
+                rows=[[1]],
+                row_count=1,
+                preview_row_count=1,
+                truncated=False,
+                nullable=[False],
+                result_id="res_1",
+                query_run_id="qrun_1",
+                execution_time_ms=1,
+            )
+
+    fake_q = FakeQueryApi()
+    with (
+        patch.object(client, "_query_api", return_value=fake_q),
+        patch.object(client, "_databases_api", return_value=databases),
+    ):
+        client.execute_sql("SELECT 1", database=db)
+
+    assert databases.read_calls == 0
+    assert fake_q.calls == [{"x_database_id": "db_abc"}]
+
+
+def test_load_managed_table_with_name_still_resolves():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    connections = _FakeConnectionsApi()
+    resolved = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+
+    with (
+        patch.object(client, "resolve_managed_database", return_value=resolved) as resolve,
+        patch.object(client, "connections", return_value=connections),
+    ):
+        result = client.load_managed_table("mydb", "orders", schema="public", upload_id="up_1")
+
+    resolve.assert_called_once_with("mydb")
+    assert connections.load_calls == [("conn_1", "public", "orders")]
+    assert result.full_name == "db_1.public.orders"
+
+
 def _clear_workspace_env(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.delenv("HOTDATA_WORKSPACE", raising=False)
 

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/tests/test_databases.py

@@ -308,6 +308,16 @@ def test_load_managed_table_defaults_to_replace():
     assert _load_and_capture_request(_client()).mode == "replace"
 
 
+def test_load_managed_table_passes_key():
+    request = _load_and_capture_request(_client(), mode="delete", key=["id"])
+    assert request.mode == "delete"
+    assert request.key == ["id"]
+
+
+def test_load_managed_table_key_defaults_to_none():
+    assert _load_and_capture_request(_client()).key is None
+
+
 @pytest.mark.parametrize("mode", ["append", "delete", "update", "upsert"])
 def test_load_managed_table_forwards_mode(mode: str):
     assert _load_and_capture_request(_client(), mode=mode).mode == mode

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/tests/test_managed_client.py

@@ -163,7 +163,13 @@ def _load_recording_runtime(calls: list[str]) -> SimpleNamespace:
     with a transient error, so retry behaviour is observable via ``calls``."""
 
     def load_managed_table(
-        database: str, table: str, *, schema: str, upload_id: str, mode: str
+        database: str,
+        table: str,
+        *,
+        schema: str,
+        upload_id: str,
+        mode: str,
+        key: list[str] | None = None,
     ) -> SimpleNamespace:
         calls.append(mode)
         raise TimeoutError("commit succeeded but response was lost")
@@ -209,3 +215,34 @@ def test_idempotent_load_retries_on_transient(monkeypatch: pytest.MonkeyPatch) -
         client.load_managed_table("db", "orders", schema="public", upload_id="u1", mode="replace")
 
     assert calls == ["replace", "replace", "replace"]  # retried up to max_retries
+
+
+def test_load_managed_table_forwards_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A per-load ``key`` is passed straight through to the runtime client."""
+    monkeypatch.setattr(mc.time, "sleep", lambda _seconds: None)
+    captured: dict[str, Any] = {}
+
+    def load_managed_table(
+        database: str,
+        table: str,
+        *,
+        schema: str,
+        upload_id: str,
+        mode: str,
+        key: list[str] | None = None,
+    ) -> SimpleNamespace:
+        captured["mode"] = mode
+        captured["key"] = key
+        return SimpleNamespace(
+            connection_id="c", schema_name=schema, table_name=table, row_count=0
+        )
+
+    client = _managed_client(max_retries=1)
+    runtime = _fake_runtime()
+    runtime.load_managed_table = load_managed_table
+    client._runtime = runtime
+
+    client.load_managed_table(
+        "db", "orders", schema="public", upload_id="u1", mode="delete", key=["id"]
+    )
+    assert captured == {"mode": "delete", "key": ["id"]}

{hotdata_framework-0.7.3 → hotdata_framework-0.9.0}/uv.lock

@@ -86,7 +86,7 @@ wheels = [
 
 [[package]]
 name = "hotdata"
-version = "0.7.0"
+version = "0.8.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/61/30/08681132e019f6c9ddb566dc38be6a302763c4b4848b2d97e3d7ace8d257/hotdata-0.7.0.tar.gz", hash = "sha256:ef4484a74c0f33ee543b0a0dbfb5a6c04e7b5812b277f42a6448000d41c2405d", size = 215130, upload-time = "2026-07-14T12:21:33.936Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/8a/38/30ed3d1d99413e7684672fa424baef85a347db465b90c774443320cf1cea/hotdata-0.8.0.tar.gz", hash = "sha256:cdac515ffa193ed028491e4b7abcd1b6404d4e3f96986c9c0a2b2f407db42eb6", size = 216848, upload-time = "2026-07-20T06:30:37.659Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/dc/ef/6c4236640629688074892759b1a7593c08f30e9d916b6951c2bbfec19d7f/hotdata-0.7.0-py3-none-any.whl", hash = "sha256:d9e3008e3084d22bcc27b7bf1d08d8c2c255fe3726c252c777bb614a3cae0576", size = 314103, upload-time = "2026-07-14T12:21:32.154Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/0f/f2ccaeb0f910c3f8cd84a911d934704277f0d6e5a20f8b49cf0eedb2a8aa/hotdata-0.8.0-py3-none-any.whl", hash = "sha256:5d64bfc185a0e7e2bf34ebdcea50787d3418fb250dacc53e00dc74d64e99f753", size = 316923, upload-time = "2026-07-20T06:30:35.778Z" },
 ]
 
 [[package]]
 name = "hotdata-framework"
-version = "0.7.3"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "hotdata" },
@@ -120,7 +120,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "hotdata", specifier = ">=0.7.0" },
+    { name = "hotdata", specifier = ">=0.8.0" },
     { name = "pandas", specifier = ">=2.0" },
     { name = "pyarrow", specifier = ">=14.0" },
 ]