hotdata-framework 0.6.2__tar.gz → 0.7.0__tar.gz

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/CHANGELOG.md

@@ -8,6 +8,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.7.0] - 2026-07-14
+
+### Added
+
+- `load_managed_table(..., mode=...)` selects the load mode (`replace` (default), `append`, `delete`, `update`, `upsert`) instead of always replacing the table. `replace`/`append` apply the upload directly; `delete`/`update`/`upsert` match rows by the table's declared key. Backward compatible — omitting `mode` still replaces.
+- `create_managed_database(..., keys={table: [cols]})` and `add_managed_table(..., key=[cols])` declare a table's row-identity key, enabling the key-based load modes on it. Requires a `hotdata` client whose managed-table decl models carry `key` (see the dependency floor bump); tables declared without a key stay `replace`/`append`-only.
+
+### Fixed
+
+- `load_managed_table(..., mode="append")` is no longer retried on transient errors. Every other mode is idempotent, but retrying an `append` whose commit succeeded before the response was received would duplicate the uploaded rows; `append` now runs at most once. `mode` is also now typed as a literal of the accepted values.
+
+## [0.6.3] - 2026-07-08
+
+### Added
+
+- `HotdataClient` and `ManagedDatabaseClient` accept `request_timeout` (seconds, or a `(connect, read)` pair). The generated SDK otherwise issues every HTTP request with urllib3's no-timeout default, so a stalled or unreachable server blocks the calling thread indefinitely; the new parameter applies a socket-level deadline to every call through the client while still honoring an explicit per-call `_request_timeout`. Also exported as `apply_default_request_timeout(api_client, timeout)` for callers holding a raw generated client. Default remains no timeout (behavior unchanged unless opted in).
+
 ## [0.6.2] - 2026-07-08
 
 ### Changed

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/PKG-INFO

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

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/hotdata_framework/client.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
+import functools
 import time
 from collections.abc import Iterator
 from dataclasses import asdict, dataclass
-from typing import Any
+from typing import Any, Literal
 
 from hotdata import ApiClient, Configuration
 from hotdata.api.connections_api import ConnectionsApi
@@ -45,6 +46,10 @@ from hotdata_framework.env import (
 from hotdata_framework.http import default_http_retries
 from hotdata_framework.result import QueryResult
 
+# Load modes the managed-table endpoint accepts: replace overwrites, append adds
+# rows, delete/update/upsert match by the table's declared key.
+ManagedLoadMode = Literal["replace", "append", "delete", "update", "upsert"]
+
 _TERMINAL = frozenset({"succeeded", "failed", "cancelled"})
 _RESULT_FAILURE = frozenset({"failed", "cancelled"})
 
@@ -71,6 +76,45 @@ class RunHistoryItem:
         return asdict(self)
 
 
+
+def apply_default_request_timeout(
+    api_client: ApiClient, timeout: float | tuple[float, float]
+) -> None:
+    """Give every request through this client a socket-level deadline.
+
+    The generated client forwards ``_request_timeout=None`` — urllib3's
+    no-timeout — on every call unless the caller passes one explicitly, and
+    most helper methods expose no such knob. A stalled or black-holed server
+    therefore blocks the calling thread indefinitely. Wrapping the REST seam
+    applies ``timeout`` (seconds, or a ``(connect, read)`` pair) as the
+    default while still honoring an explicit per-call ``_request_timeout``.
+    """
+    rest_client = api_client.rest_client
+    original = rest_client.request
+
+    @functools.wraps(original)
+    def request_with_default_timeout(
+        method,
+        url,
+        headers=None,
+        body=None,
+        post_params=None,
+        _request_timeout=None,
+    ):
+        if _request_timeout is None:
+            _request_timeout = timeout
+        return original(
+            method,
+            url,
+            headers=headers,
+            body=body,
+            post_params=post_params,
+            _request_timeout=_request_timeout,
+        )
+
+    rest_client.request = request_with_default_timeout
+
+
 class HotdataClient:
     """Thin wrapper around the Hotdata Python SDK with query polling helpers."""
 
@@ -81,6 +125,7 @@ class HotdataClient:
         *,
         host: str | None = None,
         session_id: str | None = None,
+        request_timeout: float | tuple[float, float] | None = None,
     ) -> None:
         self._host = normalize_host(host) if host else default_host()
         self._api_key = api_key
@@ -94,6 +139,8 @@ class HotdataClient:
             retries=default_http_retries(),
         )
         self._api = ApiClient(self._config)
+        if request_timeout is not None:
+            apply_default_request_timeout(self._api, request_timeout)
 
     @classmethod
     def from_env(cls) -> HotdataClient:
@@ -198,14 +245,21 @@ class HotdataClient:
         *,
         schema: str = DEFAULT_SCHEMA,
         tables: list[str] | None = None,
+        keys: dict[str, list[str]] | None = None,
         expires_at: str | None = None,
     ) -> ManagedDatabase:
+        """Create a managed database. ``keys`` maps a table to its key columns
+        (enabling delete/update/upsert on it); omitted tables are keyless."""
+        keys = keys or {}
         schemas = None
         if tables:
             schemas = [
                 DatabaseDefaultSchemaDecl(
                     name=schema,
-                    tables=[DatabaseDefaultTableDecl(name=t) for t in tables],
+                    tables=[
+                        DatabaseDefaultTableDecl(name=t, key=list(keys.get(t, [])))
+                        for t in tables
+                    ],
                 )
             ]
         request = CreateDatabaseRequest(
@@ -271,6 +325,7 @@ class HotdataClient:
         schema: str = DEFAULT_SCHEMA,
         upload_id: str | None = None,
         file: str | None = None,
+        mode: ManagedLoadMode = "replace",
     ) -> LoadManagedTableResult:
         if (upload_id is None) == (file is None):
             raise ValueError("Exactly one of upload_id or file is required")
@@ -281,7 +336,7 @@ class HotdataClient:
             assert file is not None
             resolved_upload_id = self.upload_parquet(file)
         request = LoadManagedTableRequest(
-            mode="replace",
+            mode=mode,
             upload_id=resolved_upload_id,
         )
         try:
@@ -307,15 +362,17 @@ class HotdataClient:
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
+        key: list[str] | None = None,
     ) -> 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.
+        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)
-        request = AddManagedTableRequest(name=table)
+        request = AddManagedTableRequest(name=table, key=list(key or []))
         try:
             self._databases_api().add_database_table(db.id, schema, request)
         except ApiException as e:

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/hotdata_framework/managed_client.py

@@ -21,6 +21,7 @@ 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.client import ManagedLoadMode
 from hotdata_framework.databases import LoadManagedTableResult, ManagedDatabase
 from hotdata_framework.errors import (
     HotdataTransientError,
@@ -61,6 +62,7 @@ class ManagedDatabaseClient:
         api_base_url: str,
         max_retries: int,
         retry_backoff_seconds: float,
+        request_timeout: float | tuple[float, float] | None = None,
     ) -> None:
         self._max_retries = max_retries
         self._retry_backoff_seconds = retry_backoff_seconds
@@ -68,6 +70,7 @@ class ManagedDatabaseClient:
             api_key,
             workspace_id,
             host=api_base_url.rstrip("/"),
+            request_timeout=request_timeout,
         )
 
     def close(self) -> None:
@@ -201,23 +204,30 @@ class ManagedDatabaseClient:
         *,
         schema: str,
         upload_id: str,
+        mode: ManagedLoadMode = "replace",
     ) -> 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.
         return self._request_with_retry(
             lambda: self._runtime.load_managed_table(
                 database,
                 table,
                 schema=schema,
                 upload_id=upload_id,
-            )
+                mode=mode,
+            ),
+            retryable=(mode != "append"),
         )
 
-    def _request_with_retry(self, operation: Callable[[], T]) -> T:
-        for attempt in range(1, self._max_retries + 1):
+    def _request_with_retry(self, operation: Callable[[], T], *, retryable: bool = True) -> T:
+        max_attempts = self._max_retries if retryable else 1
+        for attempt in range(1, max_attempts + 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:
+                if isinstance(mapped_error, HotdataTransientError) and attempt < max_attempts:
                     backoff = min(self._retry_backoff_seconds * attempt, self._MAX_BACKOFF_SECONDS)
                     time.sleep(backoff)
                     continue

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hotdata-framework"
-version = "0.6.2"
+version = "0.7.0"
 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,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "hotdata>=0.6.0",
+  # 0.7.0 adds `key` to table decls (create_managed_database(keys=) / add_managed_table(key=))
+  "hotdata>=0.7.0",
   "pandas>=2.0",
   "pyarrow>=14.0",
 ]

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/tests/test_databases.py

@@ -5,6 +5,7 @@ from unittest.mock import mock_open, patch
 
 import pytest
 from hotdata.exceptions import ApiException
+from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
 
 from hotdata_framework.client import HotdataClient
 from hotdata_framework.databases import (
@@ -13,6 +14,20 @@ from hotdata_framework.databases import (
 )
 
 
+def _decl_key_supported() -> bool:
+    # `key` ships with the regenerated client; the key tests activate once it does.
+    try:
+        return DatabaseDefaultTableDecl(name="t", key=["k"]).key == ["k"]
+    except Exception:
+        return False
+
+
+requires_key_field = pytest.mark.skipif(
+    not _decl_key_supported(),
+    reason="hotdata client without `key` on managed-table decls",
+)
+
+
 def _client() -> HotdataClient:
     return HotdataClient("k", "ws", host="https://api.hotdata.dev")
 
@@ -230,6 +245,69 @@ def test_load_managed_table_requires_exactly_one_source():
         )
 
 
+def _load_and_capture_request(client, **kwargs):
+    db = managed_database_from_detail(_detail())
+    loaded = SimpleNamespace(
+        connection_id="conn_1", schema_name="public", table_name="orders", row_count=1
+    )
+    with (
+        patch.object(client, "resolve_managed_database", return_value=db),
+        patch.object(client, "connections") as connections,
+    ):
+        connections.return_value.load_managed_table.return_value = loaded
+        client.load_managed_table("db_1", "orders", upload_id="upl_1", **kwargs)
+    return connections.return_value.load_managed_table.call_args.args[3]
+
+
+def test_load_managed_table_defaults_to_replace():
+    assert _load_and_capture_request(_client()).mode == "replace"
+
+
+@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
+
+
+@requires_key_field
+def test_create_managed_database_declares_keys():
+    client = _client()
+    with patch.object(client, "_databases_api") as dbs:
+        dbs.return_value.create_database.return_value = _detail(id="db_new")
+        client.create_managed_database(
+            "mydb", tables=["orders", "events"], keys={"orders": ["id"]}
+        )
+    req = dbs.return_value.create_database.call_args.args[0]
+    declared = {t.name: list(t.key) for t in req.schemas[0].tables}
+    assert declared == {"orders": ["id"], "events": []}
+
+
+@requires_key_field
+def test_add_managed_table_declares_key():
+    client = _client()
+    db = managed_database_from_detail(_detail())
+    with (
+        patch.object(client, "resolve_managed_database", return_value=db),
+        patch.object(client, "_databases_api") as dbs,
+    ):
+        client.add_managed_table("db_1", "line_items", key=["order_id", "sku"])
+    req = dbs.return_value.add_database_table.call_args.args[2]
+    assert req.name == "line_items"
+    assert list(req.key) == ["order_id", "sku"]
+
+
+@requires_key_field
+def test_add_managed_table_keyless_by_default():
+    client = _client()
+    db = managed_database_from_detail(_detail())
+    with (
+        patch.object(client, "resolve_managed_database", return_value=db),
+        patch.object(client, "_databases_api") as dbs,
+    ):
+        client.add_managed_table("db_1", "orders")
+    req = dbs.return_value.add_database_table.call_args.args[2]
+    assert list(req.key) == []
+
+
 def test_delete_managed_table_uses_default_connection_id():
     client = _client()
     db = managed_database_from_detail(_detail())

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/tests/test_managed_client.py

@@ -156,3 +156,56 @@ def test_fetch_table_carries_database_scope_on_result_reads(
     assert table is not None
     assert result_scopes == ["db1"]
     assert arrow_scopes == ["db1"]
+
+
+def _load_recording_runtime(calls: list[str]) -> SimpleNamespace:
+    """A runtime whose ``load_managed_table`` records each mode and always fails
+    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
+    ) -> SimpleNamespace:
+        calls.append(mode)
+        raise TimeoutError("commit succeeded but response was lost")
+
+    runtime = _fake_runtime()
+    runtime.load_managed_table = load_managed_table
+    return runtime
+
+
+def _managed_client(max_retries: int) -> Any:
+    return mc.ManagedDatabaseClient(
+        api_key="k",
+        workspace_id="w",
+        api_base_url="https://example.test",
+        max_retries=max_retries,
+        retry_backoff_seconds=0.0,
+    )
+
+
+def test_append_load_runs_at_most_once(monkeypatch: pytest.MonkeyPatch) -> None:
+    """``append`` is not idempotent: retrying after a commit whose response was
+    lost would duplicate rows. A transient failure must surface immediately
+    without re-appending, even with retries budgeted."""
+    monkeypatch.setattr(mc.time, "sleep", lambda _seconds: None)
+    calls: list[str] = []
+    client = _managed_client(max_retries=8)
+    client._runtime = _load_recording_runtime(calls)
+
+    with pytest.raises(mc.HotdataTransientError):
+        client.load_managed_table("db", "orders", schema="public", upload_id="u1", mode="append")
+
+    assert calls == ["append"]  # tried once, never retried
+
+
+def test_idempotent_load_retries_on_transient(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Idempotent modes still exhaust the retry budget on transient errors."""
+    monkeypatch.setattr(mc.time, "sleep", lambda _seconds: None)
+    calls: list[str] = []
+    client = _managed_client(max_retries=3)
+    client._runtime = _load_recording_runtime(calls)
+
+    with pytest.raises(mc.HotdataTransientError):
+        client.load_managed_table("db", "orders", schema="public", upload_id="u1", mode="replace")
+
+    assert calls == ["replace", "replace", "replace"]  # retried up to max_retries

hotdata_framework-0.7.0/tests/test_request_timeout.py

@@ -0,0 +1,69 @@
+"""The default request timeout must reach every call through the client.
+
+The generated client sends ``_request_timeout=None`` (urllib3 no-timeout)
+unless a caller passes one per call — and the helper methods expose no such
+knob — so a stalled server blocks the calling thread indefinitely.
+``apply_default_request_timeout`` wraps the REST seam once at construction.
+"""
+
+from __future__ import annotations
+
+from hotdata_framework.client import HotdataClient, apply_default_request_timeout
+from hotdata_framework.managed_client import ManagedDatabaseClient
+
+
+class _FakeRest:
+    def __init__(self) -> None:
+        self.seen: list[object] = []
+
+    def request(self, method, url, headers=None, body=None, post_params=None, _request_timeout=None):
+        self.seen.append(_request_timeout)
+        return "resp"
+
+
+class _FakeApi:
+    def __init__(self) -> None:
+        self.rest_client = _FakeRest()
+
+
+def test_default_applied_when_no_per_call_timeout() -> None:
+    api = _FakeApi()
+    rest = api.rest_client
+    apply_default_request_timeout(api, (10.0, 60.0))
+
+    assert api.rest_client.request("GET", "http://x") == "resp"
+    assert rest.seen == [(10.0, 60.0)]
+
+
+def test_explicit_per_call_timeout_wins() -> None:
+    api = _FakeApi()
+    rest = api.rest_client
+    apply_default_request_timeout(api, 60.0)
+
+    api.rest_client.request("GET", "http://x", _request_timeout=5.0)
+    assert rest.seen == [5.0]
+
+
+def test_hotdata_client_wraps_its_rest_seam() -> None:
+    client = HotdataClient("k", "w", host="https://example.test", request_timeout=7.0)
+    # The wrapper is installed in place of the generated bound method.
+    assert client.api.rest_client.request.__name__ == "request"
+    assert client.api.rest_client.request.__wrapped__ is not None
+
+
+def test_hotdata_client_without_timeout_is_untouched() -> None:
+    client = HotdataClient("k", "w", host="https://example.test")
+    assert not hasattr(client.api.rest_client.request, "__wrapped__")
+
+
+def test_managed_client_threads_timeout_through() -> None:
+    client = ManagedDatabaseClient(
+        api_key="k",
+        workspace_id="w",
+        api_base_url="https://example.test",
+        max_retries=1,
+        retry_backoff_seconds=0.0,
+        request_timeout=(5.0, 30.0),
+    )
+    assert client._runtime.api.rest_client.request.__wrapped__ is not None
+    client.close()

{hotdata_framework-0.6.2 → hotdata_framework-0.7.0}/uv.lock

@@ -86,7 +86,7 @@ wheels = [
 
 [[package]]
 name = "hotdata"
-version = "0.6.0"
+version = "0.7.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/d2/17/6d9e7cbe7e766cd52968653096ce4199d0cb1aa55b73fcfc2979fb9805ff/hotdata-0.6.0.tar.gz", hash = "sha256:c655fd9691a1d65dd4ed51b86f1c27bf8e73268b4c44696987a57a624da35143", size = 214162, upload-time = "2026-07-07T16:44:32.65Z" }
+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" }
 wheels = [
-    { 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" },
+    { 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" },
 ]
 
 [[package]]
 name = "hotdata-framework"
-version = "0.6.2"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "hotdata" },
@@ -120,7 +120,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "hotdata", specifier = ">=0.6.0" },
+    { name = "hotdata", specifier = ">=0.7.0" },
     { name = "pandas", specifier = ">=2.0" },
     { name = "pyarrow", specifier = ">=14.0" },
 ]