feat(query): 429 retry + truncation auto-follow (#688)

.github/workflows/integration-tests.yml

@@ -57,6 +57,25 @@ jobs:
           print(f"All {len(scenarios)} scenarios have corresponding test files.")
           PY
 
+  # Unit tests need no server or secrets (they stub the transport / generated
+  # methods), so they run on every PR including forks. This is where the
+  # hand-written behavior (Arrow fetch, auth, 429 retry + truncation auto-follow)
+  # is verified — the integration job only covers tests/integration, and the
+  # truncation/429 contract can't be exercised against prod until it deploys.
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+      - name: Install package and test deps
+        run: |
+          pip install --quiet -r requirements.txt -r test-requirements.txt
+          pip install --quiet -e .
+      - name: Run unit tests
+        run: pytest test tests --ignore=tests/integration -v
+
   # Integration tests run against production. Skipped automatically by the
   # conftest if HOTDATA_SDK_TEST_API_KEY / HOTDATA_SDK_TEST_WORKSPACE_ID aren't
   # set (e.g. PRs from forks where secrets aren't injected).

.github/workflows/regenerate.yml

@@ -206,6 +206,9 @@ jobs:
       - name: Patch ApiClient close lifecycle
         run: python3 scripts/patch_api_client_close.py
 
+      - name: Patch default client exports (enhanced query/results)
+        run: python3 scripts/patch_query_exports.py
+
       - name: Verify JWT-exchange code survived regeneration
         run: |
           python3 - <<'PY'

.openapi-generator-ignore

@@ -2,7 +2,15 @@
 git_push.sh
 README.md
 setup.py
+
+# Hand-written enhancement modules layered over the generated client. They live
+# at the package root (outside hotdata/api and hotdata/models) so the generator
+# never emits or overwrites them, but they are listed here as the source of
+# truth for "hand-maintained, don't touch": _auth.py (JWT exchange), arrow.py
+# (Arrow IPC result fetch), query.py (429 retry + truncation auto-follow, #688).
 hotdata/_auth.py
+hotdata/arrow.py
+hotdata/query.py
 
 # Hand-written test for the patched ApiClient.close()/context-manager behavior
 # (re-applied by scripts/patch_api_client_close.py). It lives in the generated

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `hotdata.query.QueryApi`: enhanced query client that transparently retries
+  HTTP 429 (`OVERLOADED`) admission shedding honoring `Retry-After`, and
+  auto-follows truncated results to materialize the full row set, guarded by
+  configurable `max_auto_rows` (default 1M) and `max_auto_bytes` (default
+  64 MiB) ceilings (#688).
+- `ResultError` base class for the result-lifecycle exceptions
+  (`ResultFailedError`, `ResultTimeoutError`, `ResultTooLargeError`,
+  `ResultIncompleteError`, `ResultUnavailableError`) so callers can catch them
+  with a single `except`.
+
+### Changed
+
+- `from hotdata import QueryApi` / `ResultsApi` now resolve to the enhanced
+  clients (429 retry + truncation auto-follow; Arrow IPC fetch) instead of the
+  bare generated classes, so the default happy path gets the safe behavior the
+  query contract needs. The raw generated classes remain importable from
+  `hotdata.api.query_api` / `hotdata.api.results_api`.
+
 
 ## [0.3.4] - 2026-06-15
 

hotdata/__init__.py

@@ -348,3 +348,11 @@
 from hotdata.models.workspace_detail import WorkspaceDetail as WorkspaceDetail
 from hotdata.models.workspace_list_item import WorkspaceListItem as WorkspaceListItem
 
+
+# --- hand-applied: prefer the enhanced clients over the generated ones
+# (re-applied by scripts/patch_query_exports.py after regeneration).
+# hotdata.query.QueryApi adds 429 retry + truncation auto-follow;
+# hotdata.arrow.ResultsApi adds Arrow IPC result fetch. The raw generated
+# classes remain importable from hotdata.api.query_api / hotdata.api.results_api.
+from hotdata.query import QueryApi as QueryApi  # noqa: E402,F811
+from hotdata.arrow import ResultsApi as ResultsApi  # noqa: E402,F811