hotdata 0.5.0__tar.gz → 0.6.0__tar.gz

{hotdata-0.5.0 → hotdata-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata
-Version: 0.5.0
+Version: 0.6.0
 Summary: Hotdata API
 Author-email: Hotdata <developers@hotdata.dev>
 License: MIT
@@ -95,17 +95,21 @@ from hotdata.arrow import ResultsApi
 with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
     results = ResultsApi(client)
 
+    # Results are scoped to a database via the required `X-Database-Id` header,
+    # so pass the id of the database the query ran in.
+    database_id = "your_database_id"
+
     # Buffered: returns a pyarrow.Table.
-    table = results.get_result_arrow(result_id)
+    table = results.get_result_arrow(result_id, database_id)
 
     # Streaming: yields a pyarrow.RecordBatchStreamReader without
     # materializing the full table in memory.
-    with results.stream_result_arrow(result_id) as reader:
+    with results.stream_result_arrow(result_id, database_id) as reader:
         for batch in reader:
             ...
 ```
 
-Both methods accept `offset` and `limit` for pagination. They raise `hotdata.arrow.ResultNotReadyError` if the result is still pending or processing — poll `results.get_result(result_id)` until `status == "ready"` first.
+Both methods accept `offset` and `limit` for pagination. They raise `hotdata.arrow.ResultNotReadyError` if the result is still pending or processing — poll `results.get_result(result_id, database_id)` until `status == "ready"` first.
 
 ## File uploads
 
@@ -135,18 +139,40 @@ with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
 (`size` is inferred for all three; a file object is read from its current
 position to the end). The SDK picks single vs. multipart from the size,
 auto-scales the part size, and bounds part concurrency to a peak-memory budget
-(override with `part_size` / `max_concurrency` / `part_retry`). Storage `PUT`s go
-through a dedicated, header-isolated connection pool, so the SDK's auth and
-workspace headers never reach object storage (which would otherwise reject the
-upload). Finalize is sent with retries disabled so the exactly-once call is never
-accidentally replayed.
-
-Failures surface as a typed hierarchy under `hotdata.uploads.UploadError`:
-`StorageError` (storage returned a non-2xx), `StorageTransportError` (the PUT
-failed before any response), `MissingETagError`, `MalformedSessionError`, and
-`SizeLimitError`. Opening the session or finalizing raises the usual
-`hotdata.exceptions.ApiException` — for example a `501` `PRESIGN_UNSUPPORTED`,
-meaning the backend cannot issue upload URLs.
+(override with `part_size` / `max_concurrency` / `part_retry`). A file larger than
+8 MiB uploads via a **streaming** session — the SDK mints each part's URL just
+before its `PUT`, so a presigned URL can't expire mid-transfer on a slow upload.
+Storage `PUT`s go through a dedicated, header-isolated connection pool (auth and
+workspace headers never reach object storage, which would otherwise reject the
+upload) with a 30s connect timeout so a dead endpoint fails fast. Finalize is sent
+with retries disabled so the exactly-once call is never accidentally replayed.
+
+Every failure is a subclass of `hotdata.uploads.UploadError` (also importable as
+`from hotdata import UploadError`), so a single `except UploadError` catches the
+whole flow: `SessionCreateError` (opening the session — check `.status` for a
+`501` `PRESIGN_UNSUPPORTED`), `StorageError` (storage returned a non-2xx; `.exhausted`
+is `True` if it outlived every retry round), `StorageTransportError` (the PUT
+failed before any response), `MissingETagError`, `MintPartError` (minting a part
+URL), `FinalizeError`, `MalformedSessionError`, `SizeLimitError`, and
+`UploadCancelledError`. The phase errors that wrap a control-plane call chain the
+underlying `hotdata.exceptions.ApiException` as `__cause__` (and expose it as
+`.api_exception` / `.status`). A local file read error surfaces as `OSError`.
+
+The `progress` callback receives a **cumulative** `(bytes_done, total)` — for a
+tqdm bar (whose `update(n)` wants a delta, and which isn't thread-safe under
+multipart) use the ready-made adapter:
+
+```python
+from hotdata import tqdm_progress
+from tqdm import tqdm
+
+with tqdm(total=size, unit="B", unit_scale=True) as bar:
+    uploads.upload_file("data.parquet", progress=tqdm_progress(bar))
+```
+
+Pass a `threading.Event` as `cancel_event` to abort an in-flight upload; tune the
+control-plane calls with `request_timeout` (storage-PUT timeouts are automatic and
+size-scaled).
 
 For that fallback (or to upload from a non-seekable stream), use `upload_stream`,
 which sends the bytes to the legacy `POST /v1/files` endpoint in one request,

{hotdata-0.5.0 → hotdata-0.6.0}/README.md

@@ -77,17 +77,21 @@ from hotdata.arrow import ResultsApi
 with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
     results = ResultsApi(client)
 
+    # Results are scoped to a database via the required `X-Database-Id` header,
+    # so pass the id of the database the query ran in.
+    database_id = "your_database_id"
+
     # Buffered: returns a pyarrow.Table.
-    table = results.get_result_arrow(result_id)
+    table = results.get_result_arrow(result_id, database_id)
 
     # Streaming: yields a pyarrow.RecordBatchStreamReader without
     # materializing the full table in memory.
-    with results.stream_result_arrow(result_id) as reader:
+    with results.stream_result_arrow(result_id, database_id) as reader:
         for batch in reader:
             ...
 ```
 
-Both methods accept `offset` and `limit` for pagination. They raise `hotdata.arrow.ResultNotReadyError` if the result is still pending or processing — poll `results.get_result(result_id)` until `status == "ready"` first.
+Both methods accept `offset` and `limit` for pagination. They raise `hotdata.arrow.ResultNotReadyError` if the result is still pending or processing — poll `results.get_result(result_id, database_id)` until `status == "ready"` first.
 
 ## File uploads
 
@@ -117,18 +121,40 @@ with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
 (`size` is inferred for all three; a file object is read from its current
 position to the end). The SDK picks single vs. multipart from the size,
 auto-scales the part size, and bounds part concurrency to a peak-memory budget
-(override with `part_size` / `max_concurrency` / `part_retry`). Storage `PUT`s go
-through a dedicated, header-isolated connection pool, so the SDK's auth and
-workspace headers never reach object storage (which would otherwise reject the
-upload). Finalize is sent with retries disabled so the exactly-once call is never
-accidentally replayed.
-
-Failures surface as a typed hierarchy under `hotdata.uploads.UploadError`:
-`StorageError` (storage returned a non-2xx), `StorageTransportError` (the PUT
-failed before any response), `MissingETagError`, `MalformedSessionError`, and
-`SizeLimitError`. Opening the session or finalizing raises the usual
-`hotdata.exceptions.ApiException` — for example a `501` `PRESIGN_UNSUPPORTED`,
-meaning the backend cannot issue upload URLs.
+(override with `part_size` / `max_concurrency` / `part_retry`). A file larger than
+8 MiB uploads via a **streaming** session — the SDK mints each part's URL just
+before its `PUT`, so a presigned URL can't expire mid-transfer on a slow upload.
+Storage `PUT`s go through a dedicated, header-isolated connection pool (auth and
+workspace headers never reach object storage, which would otherwise reject the
+upload) with a 30s connect timeout so a dead endpoint fails fast. Finalize is sent
+with retries disabled so the exactly-once call is never accidentally replayed.
+
+Every failure is a subclass of `hotdata.uploads.UploadError` (also importable as
+`from hotdata import UploadError`), so a single `except UploadError` catches the
+whole flow: `SessionCreateError` (opening the session — check `.status` for a
+`501` `PRESIGN_UNSUPPORTED`), `StorageError` (storage returned a non-2xx; `.exhausted`
+is `True` if it outlived every retry round), `StorageTransportError` (the PUT
+failed before any response), `MissingETagError`, `MintPartError` (minting a part
+URL), `FinalizeError`, `MalformedSessionError`, `SizeLimitError`, and
+`UploadCancelledError`. The phase errors that wrap a control-plane call chain the
+underlying `hotdata.exceptions.ApiException` as `__cause__` (and expose it as
+`.api_exception` / `.status`). A local file read error surfaces as `OSError`.
+
+The `progress` callback receives a **cumulative** `(bytes_done, total)` — for a
+tqdm bar (whose `update(n)` wants a delta, and which isn't thread-safe under
+multipart) use the ready-made adapter:
+
+```python
+from hotdata import tqdm_progress
+from tqdm import tqdm
+
+with tqdm(total=size, unit="B", unit_scale=True) as bar:
+    uploads.upload_file("data.parquet", progress=tqdm_progress(bar))
+```
+
+Pass a `threading.Event` as `cancel_event` to abort an in-flight upload; tune the
+control-plane calls with `request_timeout` (storage-PUT timeouts are automatic and
+size-scaled).
 
 For that fallback (or to upload from a non-seekable stream), use `upload_stream`,
 which sends the bytes to the legacy `POST /v1/files` endpoint in one request,

{hotdata-0.5.0 → hotdata-0.6.0}/hotdata/__init__.py

@@ -133,6 +133,9 @@ __all__ = [
     "LoadManagedTableResponse",
     "ManagedSchemaResponse",
     "ManagedTableResponse",
+    "MintUploadPartsRequest",
+    "MintUploadPartsResponse",
+    "MintedUploadPartResponse",
     "NumericProfileDetail",
     "QueryRequest",
     "QueryResponse",
@@ -283,6 +286,9 @@ from hotdata.models.load_managed_table_request import LoadManagedTableRequest as
 from hotdata.models.load_managed_table_response import LoadManagedTableResponse as LoadManagedTableResponse
 from hotdata.models.managed_schema_response import ManagedSchemaResponse as ManagedSchemaResponse
 from hotdata.models.managed_table_response import ManagedTableResponse as ManagedTableResponse
+from hotdata.models.mint_upload_parts_request import MintUploadPartsRequest as MintUploadPartsRequest
+from hotdata.models.mint_upload_parts_response import MintUploadPartsResponse as MintUploadPartsResponse
+from hotdata.models.minted_upload_part_response import MintedUploadPartResponse as MintedUploadPartResponse
 from hotdata.models.numeric_profile_detail import NumericProfileDetail as NumericProfileDetail
 from hotdata.models.query_request import QueryRequest as QueryRequest
 from hotdata.models.query_response import QueryResponse as QueryResponse
@@ -328,3 +334,38 @@ from hotdata.models.workspace_usage_response import WorkspaceUsageResponse as Wo
 from hotdata.query import QueryApi as QueryApi  # noqa: E402,F811
 from hotdata.arrow import ResultsApi as ResultsApi  # noqa: E402,F811
 from hotdata.uploads import UploadsApi as UploadsApi  # noqa: E402,F811
+# The upload error hierarchy + option/helper types, so `from hotdata import
+# UploadError` / `StorageError` / ... works (they otherwise live only under
+# hotdata.uploads and are invisible to autocomplete on `hotdata.`).
+from hotdata.uploads import (  # noqa: E402,F401
+    UploadError as UploadError,
+    SessionCreateError as SessionCreateError,
+    MalformedSessionError as MalformedSessionError,
+    SizeLimitError as SizeLimitError,
+    StorageError as StorageError,
+    StorageTransportError as StorageTransportError,
+    MissingETagError as MissingETagError,
+    MintPartError as MintPartError,
+    FinalizeError as FinalizeError,
+    UploadCancelledError as UploadCancelledError,
+    UploadOptions as UploadOptions,
+    UploadProgress as UploadProgress,
+    UploadSource as UploadSource,
+    tqdm_progress as tqdm_progress,
+)
+__all__ += [  # noqa: F405
+    "UploadError",
+    "SessionCreateError",
+    "MalformedSessionError",
+    "SizeLimitError",
+    "StorageError",
+    "StorageTransportError",
+    "MissingETagError",
+    "MintPartError",
+    "FinalizeError",
+    "UploadCancelledError",
+    "UploadOptions",
+    "UploadProgress",
+    "UploadSource",
+    "tqdm_progress",
+]