hotdata 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata
-Version: 0.4.0
+Version: 0.5.0
 Summary: Hotdata API
 Author-email: Hotdata <developers@hotdata.dev>
 License: MIT
@@ -107,6 +107,61 @@ with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
 
 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.
 
+## File uploads
+
+`hotdata.uploads.UploadsApi` (also the default `hotdata.UploadsApi`) adds
+`upload_file`, which uploads a local file **directly to object storage** and
+finalizes it in one call. It opens an upload session, `PUT`s the bytes straight
+to storage — a single `PUT` for a small file, concurrent part `PUT`s for a large
+one — then finalizes. The bytes never round-trip through the API.
+
+```python
+from hotdata import ApiClient, Configuration, UploadsApi
+
+with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
+    uploads = UploadsApi(client)
+
+    finalized = uploads.upload_file(
+        "data.parquet",
+        content_type="application/parquet",
+        progress=lambda done, total: print(f"{done}/{total} bytes"),
+    )
+
+    # Pass finalized.upload_id to the managed-table load endpoint.
+    print(finalized.upload_id)
+```
+
+`upload_file` accepts a path, raw `bytes`, or a seekable binary file object
+(`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.
+
+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,
+streaming a file object without buffering it in memory:
+
+```python
+with open("data.parquet", "rb") as f:
+    resp = uploads.upload_stream(f, content_type="application/parquet")
+print(resp.id)
+```
+
+Note `upload_file` shadows the generated raw-body `upload_file(body=...)`; that
+raw operation is still reachable at
+`hotdata.api.uploads_api.UploadsApi.upload_file`.
+
 ## API reference
 
 Generated Markdown for every operation and model is in [`docs/`](https://github.com/hotdata-dev/sdk-python/tree/main/docs):

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

@@ -89,6 +89,61 @@ with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
 
 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.
 
+## File uploads
+
+`hotdata.uploads.UploadsApi` (also the default `hotdata.UploadsApi`) adds
+`upload_file`, which uploads a local file **directly to object storage** and
+finalizes it in one call. It opens an upload session, `PUT`s the bytes straight
+to storage — a single `PUT` for a small file, concurrent part `PUT`s for a large
+one — then finalizes. The bytes never round-trip through the API.
+
+```python
+from hotdata import ApiClient, Configuration, UploadsApi
+
+with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
+    uploads = UploadsApi(client)
+
+    finalized = uploads.upload_file(
+        "data.parquet",
+        content_type="application/parquet",
+        progress=lambda done, total: print(f"{done}/{total} bytes"),
+    )
+
+    # Pass finalized.upload_id to the managed-table load endpoint.
+    print(finalized.upload_id)
+```
+
+`upload_file` accepts a path, raw `bytes`, or a seekable binary file object
+(`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.
+
+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,
+streaming a file object without buffering it in memory:
+
+```python
+with open("data.parquet", "rb") as f:
+    resp = uploads.upload_stream(f, content_type="application/parquet")
+print(resp.id)
+```
+
+Note `upload_file` shadows the generated raw-body `upload_file(body=...)`; that
+raw operation is still reachable at
+`hotdata.api.uploads_api.UploadsApi.upload_file`.
+
 ## API reference
 
 Generated Markdown for every operation and model is in [`docs/`](https://github.com/hotdata-dev/sdk-python/tree/main/docs):

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

@@ -5,7 +5,7 @@
 """
     Hotdata API
 
-    Powerful data platform API for datasets, queries, and analytics.
+    Powerful data platform API for managed databases, queries, and analytics.
 
     The version of the OpenAPI document: 1.0.0
     Contact: developers@hotdata.dev
@@ -28,7 +28,6 @@ __all__ = [
     "ConnectionsApi",
     "DatabaseContextApi",
     "DatabasesApi",
-    "DatasetsApi",
     "EmbeddingProvidersApi",
     "IndexesApi",
     "InformationSchemaApi",
@@ -40,6 +39,7 @@ __all__ = [
     "SavedQueriesApi",
     "SecretsApi",
     "UploadsApi",
+    "UsageApi",
     "WorkspacesApi",
     "ApiResponse",
     "ApiClient",
@@ -57,6 +57,8 @@ __all__ = [
     "ApiErrorResponse",
     "AsyncQueryResponse",
     "AttachDatabaseCatalogRequest",
+    "BatchCreateUploadRequest",
+    "BatchCreateUploadResponse",
     "BooleanProfileDetail",
     "CategoricalProfileDetail",
     "CategoryValueInfo",
@@ -68,7 +70,6 @@ __all__ = [
     "ColumnProfileDetailOneOf3",
     "ColumnProfileDetailOneOf4",
     "ColumnProfileInfo",
-    "ColumnTypeSpec",
     "ConnectionHealthResponse",
     "ConnectionInfo",
     "ConnectionRefreshResult",
@@ -79,14 +80,13 @@ __all__ = [
     "CreateConnectionResponse",
     "CreateDatabaseRequest",
     "CreateDatabaseResponse",
-    "CreateDatasetRequest",
-    "CreateDatasetResponse",
     "CreateEmbeddingProviderRequest",
     "CreateEmbeddingProviderResponse",
     "CreateIndexRequest",
     "CreateSavedQueryRequest",
     "CreateSecretRequest",
     "CreateSecretResponse",
+    "CreateUploadRequest",
     "CreateWorkspaceRequest",
     "CreateWorkspaceResponse",
     "DatabaseAttachmentInfo",
@@ -95,29 +95,21 @@ __all__ = [
     "DatabaseDefaultTableDecl",
     "DatabaseDetailResponse",
     "DatabaseSummary",
-    "DatasetSource",
-    "DatasetSourceOneOf",
-    "DatasetSourceOneOf1",
-    "DatasetSourceOneOf2",
-    "DatasetSourceOneOf3",
-    "DatasetSourceOneOf4",
-    "DatasetSummary",
-    "DatasetVersionSummary",
     "DiscoveryStatus",
     "EmbeddingProviderResponse",
     "Error",
     "ExecuteSavedQueryRequest",
+    "FinalizeUploadPart",
+    "FinalizeUploadRequest",
+    "FinalizeUploadResponse",
     "GetConnectionResponse",
     "GetDatabaseContextResponse",
-    "GetDatasetResponse",
     "GetResultResponse",
     "GetSecretResponse",
     "IndexEntryResponse",
     "IndexInfoResponse",
     "IndexStatus",
     "InformationSchemaResponse",
-    "InlineData",
-    "InlineDatasetSource",
     "JobResult",
     "JobStatus",
     "JobStatusResponse",
@@ -126,8 +118,6 @@ __all__ = [
     "ListConnectionsResponse",
     "ListDatabaseContextsResponse",
     "ListDatabasesResponse",
-    "ListDatasetVersionsResponse",
-    "ListDatasetsResponse",
     "ListEmbeddingProvidersResponse",
     "ListIndexesPageResponse",
     "ListIndexesResponse",
@@ -147,19 +137,16 @@ __all__ = [
     "QueryRequest",
     "QueryResponse",
     "QueryRunInfo",
-    "RefreshDatasetResponse",
     "RefreshRequest",
     "RefreshResponse",
     "RefreshWarning",
     "ResultInfo",
     "ResultsFormatQuery",
-    "SavedQueryDatasetSource",
     "SavedQueryDetail",
     "SavedQuerySummary",
     "SavedQueryVersionInfo",
     "SchemaRefreshResult",
     "SecretMetadataResponse",
-    "SqlQueryDatasetSource",
     "SubmitJobResponse",
     "TableInfo",
     "TableProfileResponse",
@@ -167,21 +154,19 @@ __all__ = [
     "TableRefreshResult",
     "TemporalProfileDetail",
     "TextProfileDetail",
-    "UpdateDatasetRequest",
-    "UpdateDatasetResponse",
     "UpdateEmbeddingProviderRequest",
     "UpdateEmbeddingProviderResponse",
     "UpdateSavedQueryRequest",
     "UpdateSecretRequest",
     "UpdateSecretResponse",
-    "UploadDatasetSource",
     "UploadInfo",
     "UploadResponse",
+    "UploadSessionResponse",
     "UpsertDatabaseContextRequest",
     "UpsertDatabaseContextResponse",
-    "UrlDatasetSource",
     "WorkspaceDetail",
     "WorkspaceListItem",
+    "WorkspaceUsageResponse",
 ]
 
 # import apis into sdk package
@@ -189,7 +174,6 @@ from hotdata.api.connection_types_api import ConnectionTypesApi as ConnectionTyp
 from hotdata.api.connections_api import ConnectionsApi as ConnectionsApi
 from hotdata.api.database_context_api import DatabaseContextApi as DatabaseContextApi
 from hotdata.api.databases_api import DatabasesApi as DatabasesApi
-from hotdata.api.datasets_api import DatasetsApi as DatasetsApi
 from hotdata.api.embedding_providers_api import EmbeddingProvidersApi as EmbeddingProvidersApi
 from hotdata.api.indexes_api import IndexesApi as IndexesApi
 from hotdata.api.information_schema_api import InformationSchemaApi as InformationSchemaApi
@@ -201,6 +185,7 @@ from hotdata.api.results_api import ResultsApi as ResultsApi
 from hotdata.api.saved_queries_api import SavedQueriesApi as SavedQueriesApi
 from hotdata.api.secrets_api import SecretsApi as SecretsApi
 from hotdata.api.uploads_api import UploadsApi as UploadsApi
+from hotdata.api.usage_api import UsageApi as UsageApi
 from hotdata.api.workspaces_api import WorkspacesApi as WorkspacesApi
 
 # import ApiClient
@@ -222,6 +207,8 @@ from hotdata.models.api_error_detail import ApiErrorDetail as ApiErrorDetail
 from hotdata.models.api_error_response import ApiErrorResponse as ApiErrorResponse
 from hotdata.models.async_query_response import AsyncQueryResponse as AsyncQueryResponse
 from hotdata.models.attach_database_catalog_request import AttachDatabaseCatalogRequest as AttachDatabaseCatalogRequest
+from hotdata.models.batch_create_upload_request import BatchCreateUploadRequest as BatchCreateUploadRequest
+from hotdata.models.batch_create_upload_response import BatchCreateUploadResponse as BatchCreateUploadResponse
 from hotdata.models.boolean_profile_detail import BooleanProfileDetail as BooleanProfileDetail
 from hotdata.models.categorical_profile_detail import CategoricalProfileDetail as CategoricalProfileDetail
 from hotdata.models.category_value_info import CategoryValueInfo as CategoryValueInfo
@@ -233,7 +220,6 @@ from hotdata.models.column_profile_detail_one_of2 import ColumnProfileDetailOneO
 from hotdata.models.column_profile_detail_one_of3 import ColumnProfileDetailOneOf3 as ColumnProfileDetailOneOf3
 from hotdata.models.column_profile_detail_one_of4 import ColumnProfileDetailOneOf4 as ColumnProfileDetailOneOf4
 from hotdata.models.column_profile_info import ColumnProfileInfo as ColumnProfileInfo
-from hotdata.models.column_type_spec import ColumnTypeSpec as ColumnTypeSpec
 from hotdata.models.connection_health_response import ConnectionHealthResponse as ConnectionHealthResponse
 from hotdata.models.connection_info import ConnectionInfo as ConnectionInfo
 from hotdata.models.connection_refresh_result import ConnectionRefreshResult as ConnectionRefreshResult
@@ -244,14 +230,13 @@ from hotdata.models.create_connection_request import CreateConnectionRequest as
 from hotdata.models.create_connection_response import CreateConnectionResponse as CreateConnectionResponse
 from hotdata.models.create_database_request import CreateDatabaseRequest as CreateDatabaseRequest
 from hotdata.models.create_database_response import CreateDatabaseResponse as CreateDatabaseResponse
-from hotdata.models.create_dataset_request import CreateDatasetRequest as CreateDatasetRequest
-from hotdata.models.create_dataset_response import CreateDatasetResponse as CreateDatasetResponse
 from hotdata.models.create_embedding_provider_request import CreateEmbeddingProviderRequest as CreateEmbeddingProviderRequest
 from hotdata.models.create_embedding_provider_response import CreateEmbeddingProviderResponse as CreateEmbeddingProviderResponse
 from hotdata.models.create_index_request import CreateIndexRequest as CreateIndexRequest
 from hotdata.models.create_saved_query_request import CreateSavedQueryRequest as CreateSavedQueryRequest
 from hotdata.models.create_secret_request import CreateSecretRequest as CreateSecretRequest
 from hotdata.models.create_secret_response import CreateSecretResponse as CreateSecretResponse
+from hotdata.models.create_upload_request import CreateUploadRequest as CreateUploadRequest
 from hotdata.models.create_workspace_request import CreateWorkspaceRequest as CreateWorkspaceRequest
 from hotdata.models.create_workspace_response import CreateWorkspaceResponse as CreateWorkspaceResponse
 from hotdata.models.database_attachment_info import DatabaseAttachmentInfo as DatabaseAttachmentInfo
@@ -260,29 +245,21 @@ from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDec
 from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl as DatabaseDefaultTableDecl
 from hotdata.models.database_detail_response import DatabaseDetailResponse as DatabaseDetailResponse
 from hotdata.models.database_summary import DatabaseSummary as DatabaseSummary
-from hotdata.models.dataset_source import DatasetSource as DatasetSource
-from hotdata.models.dataset_source_one_of import DatasetSourceOneOf as DatasetSourceOneOf
-from hotdata.models.dataset_source_one_of1 import DatasetSourceOneOf1 as DatasetSourceOneOf1
-from hotdata.models.dataset_source_one_of2 import DatasetSourceOneOf2 as DatasetSourceOneOf2
-from hotdata.models.dataset_source_one_of3 import DatasetSourceOneOf3 as DatasetSourceOneOf3
-from hotdata.models.dataset_source_one_of4 import DatasetSourceOneOf4 as DatasetSourceOneOf4
-from hotdata.models.dataset_summary import DatasetSummary as DatasetSummary
-from hotdata.models.dataset_version_summary import DatasetVersionSummary as DatasetVersionSummary
 from hotdata.models.discovery_status import DiscoveryStatus as DiscoveryStatus
 from hotdata.models.embedding_provider_response import EmbeddingProviderResponse as EmbeddingProviderResponse
 from hotdata.models.error import Error as Error
 from hotdata.models.execute_saved_query_request import ExecuteSavedQueryRequest as ExecuteSavedQueryRequest
+from hotdata.models.finalize_upload_part import FinalizeUploadPart as FinalizeUploadPart
+from hotdata.models.finalize_upload_request import FinalizeUploadRequest as FinalizeUploadRequest
+from hotdata.models.finalize_upload_response import FinalizeUploadResponse as FinalizeUploadResponse
 from hotdata.models.get_connection_response import GetConnectionResponse as GetConnectionResponse
 from hotdata.models.get_database_context_response import GetDatabaseContextResponse as GetDatabaseContextResponse
-from hotdata.models.get_dataset_response import GetDatasetResponse as GetDatasetResponse
 from hotdata.models.get_result_response import GetResultResponse as GetResultResponse
 from hotdata.models.get_secret_response import GetSecretResponse as GetSecretResponse
 from hotdata.models.index_entry_response import IndexEntryResponse as IndexEntryResponse
 from hotdata.models.index_info_response import IndexInfoResponse as IndexInfoResponse
 from hotdata.models.index_status import IndexStatus as IndexStatus
 from hotdata.models.information_schema_response import InformationSchemaResponse as InformationSchemaResponse
-from hotdata.models.inline_data import InlineData as InlineData
-from hotdata.models.inline_dataset_source import InlineDatasetSource as InlineDatasetSource
 from hotdata.models.job_result import JobResult as JobResult
 from hotdata.models.job_status import JobStatus as JobStatus
 from hotdata.models.job_status_response import JobStatusResponse as JobStatusResponse
@@ -291,8 +268,6 @@ from hotdata.models.list_connection_types_response import ListConnectionTypesRes
 from hotdata.models.list_connections_response import ListConnectionsResponse as ListConnectionsResponse
 from hotdata.models.list_database_contexts_response import ListDatabaseContextsResponse as ListDatabaseContextsResponse
 from hotdata.models.list_databases_response import ListDatabasesResponse as ListDatabasesResponse
-from hotdata.models.list_dataset_versions_response import ListDatasetVersionsResponse as ListDatasetVersionsResponse
-from hotdata.models.list_datasets_response import ListDatasetsResponse as ListDatasetsResponse
 from hotdata.models.list_embedding_providers_response import ListEmbeddingProvidersResponse as ListEmbeddingProvidersResponse
 from hotdata.models.list_indexes_page_response import ListIndexesPageResponse as ListIndexesPageResponse
 from hotdata.models.list_indexes_response import ListIndexesResponse as ListIndexesResponse
@@ -312,19 +287,16 @@ from hotdata.models.numeric_profile_detail import NumericProfileDetail as Numeri
 from hotdata.models.query_request import QueryRequest as QueryRequest
 from hotdata.models.query_response import QueryResponse as QueryResponse
 from hotdata.models.query_run_info import QueryRunInfo as QueryRunInfo
-from hotdata.models.refresh_dataset_response import RefreshDatasetResponse as RefreshDatasetResponse
 from hotdata.models.refresh_request import RefreshRequest as RefreshRequest
 from hotdata.models.refresh_response import RefreshResponse as RefreshResponse
 from hotdata.models.refresh_warning import RefreshWarning as RefreshWarning
 from hotdata.models.result_info import ResultInfo as ResultInfo
 from hotdata.models.results_format_query import ResultsFormatQuery as ResultsFormatQuery
-from hotdata.models.saved_query_dataset_source import SavedQueryDatasetSource as SavedQueryDatasetSource
 from hotdata.models.saved_query_detail import SavedQueryDetail as SavedQueryDetail
 from hotdata.models.saved_query_summary import SavedQuerySummary as SavedQuerySummary
 from hotdata.models.saved_query_version_info import SavedQueryVersionInfo as SavedQueryVersionInfo
 from hotdata.models.schema_refresh_result import SchemaRefreshResult as SchemaRefreshResult
 from hotdata.models.secret_metadata_response import SecretMetadataResponse as SecretMetadataResponse
-from hotdata.models.sql_query_dataset_source import SqlQueryDatasetSource as SqlQueryDatasetSource
 from hotdata.models.submit_job_response import SubmitJobResponse as SubmitJobResponse
 from hotdata.models.table_info import TableInfo as TableInfo
 from hotdata.models.table_profile_response import TableProfileResponse as TableProfileResponse
@@ -332,27 +304,27 @@ from hotdata.models.table_refresh_error import TableRefreshError as TableRefresh
 from hotdata.models.table_refresh_result import TableRefreshResult as TableRefreshResult
 from hotdata.models.temporal_profile_detail import TemporalProfileDetail as TemporalProfileDetail
 from hotdata.models.text_profile_detail import TextProfileDetail as TextProfileDetail
-from hotdata.models.update_dataset_request import UpdateDatasetRequest as UpdateDatasetRequest
-from hotdata.models.update_dataset_response import UpdateDatasetResponse as UpdateDatasetResponse
 from hotdata.models.update_embedding_provider_request import UpdateEmbeddingProviderRequest as UpdateEmbeddingProviderRequest
 from hotdata.models.update_embedding_provider_response import UpdateEmbeddingProviderResponse as UpdateEmbeddingProviderResponse
 from hotdata.models.update_saved_query_request import UpdateSavedQueryRequest as UpdateSavedQueryRequest
 from hotdata.models.update_secret_request import UpdateSecretRequest as UpdateSecretRequest
 from hotdata.models.update_secret_response import UpdateSecretResponse as UpdateSecretResponse
-from hotdata.models.upload_dataset_source import UploadDatasetSource as UploadDatasetSource
 from hotdata.models.upload_info import UploadInfo as UploadInfo
 from hotdata.models.upload_response import UploadResponse as UploadResponse
+from hotdata.models.upload_session_response import UploadSessionResponse as UploadSessionResponse
 from hotdata.models.upsert_database_context_request import UpsertDatabaseContextRequest as UpsertDatabaseContextRequest
 from hotdata.models.upsert_database_context_response import UpsertDatabaseContextResponse as UpsertDatabaseContextResponse
-from hotdata.models.url_dataset_source import UrlDatasetSource as UrlDatasetSource
 from hotdata.models.workspace_detail import WorkspaceDetail as WorkspaceDetail
 from hotdata.models.workspace_list_item import WorkspaceListItem as WorkspaceListItem
+from hotdata.models.workspace_usage_response import WorkspaceUsageResponse as WorkspaceUsageResponse
 
 
 # --- 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.
+# hotdata.arrow.ResultsApi adds Arrow IPC result fetch;
+# hotdata.uploads.UploadsApi adds transparent presigned direct-to-storage
+# uploads. The raw generated classes remain importable from hotdata.api.*.
 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

{hotdata-0.4.0 → hotdata-0.5.0}/hotdata/_auth.py

@@ -28,6 +28,11 @@ Key behaviors:
 * **Refresh, then re-mint** -- prefer the refresh token when available; on
   refresh failure, re-mint from the held API token (always possible since the
   SDK holds it). Matches the CLI.
+* **Transient-failure retry** -- a momentary ``5xx`` or a transport error on the
+  token endpoint is retried with bounded exponential backoff + jitter
+  (``_MAX_ATTEMPTS`` total) before giving up, so a brief server-side blip does
+  not fail the caller (#113). A ``4xx`` is never retried -- a bad/expired
+  credential is not transient.
 * **TLS/proxy reuse** -- the exchange call reuses the SDK's configured TLS,
   client cert and proxy settings (see :func:`_pool_from_config`) so it behaves
   like every other SDK request, with a bounded timeout so a stalled token
@@ -36,6 +41,7 @@ Key behaviors:
 
 import json
 import os
+import random
 import ssl
 import threading
 import time
@@ -47,6 +53,15 @@ _LEEWAY = 30          # refresh when <30s of life remains
 _TIMEOUT = 30.0       # seconds -- never let a stalled token endpoint hang every request
 _CLIENT_ID = "hotdata-python-sdk"
 
+# Bounded retry of *transient* token-exchange failures (#113). A momentary 5xx
+# or a transport error (connection/read failure) on the token endpoint should
+# not fail the caller outright -- an immediate re-attempt typically succeeds.
+# We retry those, but never a 4xx (a bad/expired credential is not transient).
+_MAX_ATTEMPTS = 3       # one initial attempt + up to two retries
+_BACKOFF_BASE = 0.1     # seconds -- first retry waits ~this, doubling thereafter
+_BACKOFF_MAX = 2.0      # cap on a single backoff so a flapping host can't stall us
+_BACKOFF_JITTER = 0.5   # additive jitter fraction (delay in [base, 1.5*base]) to spread retries out
+
 # Env var that disables exchange entirely. Used as a hard escape hatch during
 # the rollout window and for local/dev setups. Only affirmative values opt out
 # (see _DISABLE_VALUES) so that ``=0`` / ``=false`` do NOT silently disable it.
@@ -109,8 +124,11 @@ def _pool_from_config(configuration):
         pool_args["server_hostname"] = configuration.tls_server_name
     if configuration.socket_options is not None:
         pool_args["socket_options"] = configuration.socket_options
-    # `retries`/`maxsize` are intentionally not mirrored: the exchange is a
-    # single bounded-timeout request that fails fast rather than retrying.
+    # `retries`/`maxsize` are intentionally not mirrored: urllib3's own Retry is
+    # left at urllib3's default (it does not retry POST status codes anyway), so
+    # we do not inherit the SDK's connection-reset retry here. Transient-failure
+    # retry for the exchange is handled explicitly in `_TokenManager._exchange`
+    # (5xx + transport errors, bounded backoff), where we can keep 4xx fatal.
 
     if configuration.proxy:
         if _is_socks_proxy_url(configuration.proxy):
@@ -125,6 +143,29 @@ def _pool_from_config(configuration):
     return urllib3.PoolManager(**pool_args)
 
 
+def _is_transient_status(status):
+    """True for HTTP statuses worth retrying (server-side, likely momentary).
+
+    Only 5xx is transient: the request reached the server but it failed to
+    handle it (e.g. a brief ``500``/``503``). A 4xx -- including ``400``/``401``
+    from a bad or expired credential -- is a definitive rejection that a retry
+    will not fix, so it is never retried.
+    """
+    return 500 <= status < 600
+
+
+def _backoff_delay(attempt):
+    """Seconds to sleep before retry number ``attempt`` (0 = first retry).
+
+    Exponential growth from ``_BACKOFF_BASE`` (doubling per attempt) capped at
+    ``_BACKOFF_MAX``, plus additive jitter in ``[0, _BACKOFF_JITTER * base]`` so
+    concurrent clients retrying the same blip don't resynchronize into a thundering
+    herd. Mirrors the Rust SDK's ``backoff_delay``.
+    """
+    base = min(_BACKOFF_BASE * (2 ** attempt), _BACKOFF_MAX)
+    return base * (1 + _BACKOFF_JITTER * random.random())
+
+
 class _TokenManager:
     """Exchanges an API token for short-lived JWTs and keeps them fresh.
 
@@ -134,10 +175,11 @@ class _TokenManager:
     exchanged.
     """
 
-    def __init__(self, credential, configuration, pool=None):
+    def __init__(self, credential, configuration, pool=None, sleep=None):
         self._credential = credential
         self._config = configuration      # read host + TLS lazily at mint time
         self._pool = pool                 # injected in tests; else built from config TLS
+        self._sleep = sleep or time.sleep  # injected in tests so retry backoff is instant
         self._lock = threading.Lock()
         self._jwt = None
         self._exp = 0.0
@@ -168,8 +210,18 @@ class _TokenManager:
         """
         if not self._needs_exchange:
             return self._credential            # already a JWT (or opt-out) -> unchanged
+        # Lock-free fast path: a still-valid cached JWT needs no mint and must
+        # not block behind an in-flight (possibly retrying) mint that holds the
+        # lock for up to several timeouts. Attribute reads are atomic under the
+        # GIL; the worst a benign jwt/exp race can do is fall through to re-check
+        # under the lock, and the _LEEWAY margin keeps a token read here valid on
+        # the wire even if it is about to be rotated.
+        jwt = self._jwt
+        if jwt and time.time() < self._exp - _LEEWAY:
+            return jwt
         with self._lock:
-            # Fast path: a still-valid cached JWT, no network call.
+            # Re-check under the lock: another thread may have minted a fresh JWT
+            # while we waited (double-checked locking).
             if self._jwt and time.time() < self._exp - _LEEWAY:
                 return self._jwt
             # Prefer the refresh token; on failure, drop it and re-mint below.
@@ -187,24 +239,12 @@ class _TokenManager:
         # -- a non-200, a transport error, or a malformed/missing-token body --
         # returns False so the caller re-mints from the held API token. An
         # api_token mint instead raises TokenExchangeError on any failure, since
-        # there is no further fallback.
+        # there is no further fallback. Transient failures (5xx + transport
+        # errors) are retried inside _exchange before either outcome.
         params["client_id"] = _CLIENT_ID
         is_refresh = params["grant_type"] == "refresh_token"
         try:
-            pool = self._pool or _pool_from_config(self._config)   # reuses ssl_ca_cert/cert/proxy
-            host = self._config.host.rstrip("/")                   # read host lazily -- may be set post-construct
-            resp = pool.request(
-                "POST",
-                f"{host}/v1/auth/jwt",
-                body=urlencode(params),
-                headers={"Content-Type": "application/x-www-form-urlencoded"},
-                timeout=_TIMEOUT,
-            )
-            if resp.status != 200:
-                raise TokenExchangeError(
-                    f"token exchange failed: {resp.status} {resp.data[:200]!r}"
-                )
-            data = json.loads(resp.data)
+            data = self._exchange(params)
             token = data["access_token"]
             expires_in = float(data.get("expires_in", 300))
         except (
@@ -224,6 +264,57 @@ class _TokenManager:
         self._refresh = data.get("refresh_token") or self._refresh
         return True
 
+    def _exchange(self, params):
+        # POST the token-exchange request, retrying transient failures, and
+        # return the parsed JSON body of the 200 response.
+        #
+        # Retries 5xx responses and transport errors (urllib3 HTTPError, e.g. a
+        # connection/read failure) with bounded exponential backoff + jitter, up
+        # to _MAX_ATTEMPTS total. A 4xx is returned immediately as a fatal
+        # TokenExchangeError -- bad/expired credentials are not transient. Once
+        # the budget is exhausted, the last failure is surfaced: a 5xx as a
+        # TokenExchangeError preserving the status/body, a transport error as the
+        # raised HTTPError (which _mint wraps). JSON/missing-token errors from
+        # parsing a 200 body propagate unretried.
+        pool = self._pool or _pool_from_config(self._config)   # reuses ssl_ca_cert/cert/proxy
+        host = self._config.host.rstrip("/")                   # read host lazily -- may be set post-construct
+        url = f"{host}/v1/auth/jwt"
+        body = urlencode(params)
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        for attempt in range(_MAX_ATTEMPTS):
+            last = attempt == _MAX_ATTEMPTS - 1
+            try:
+                resp = pool.request(
+                    "POST",
+                    url,
+                    body=body,
+                    headers=headers,
+                    timeout=_TIMEOUT,
+                    # Disable urllib3's own per-request retries so this loop is
+                    # the sole arbiter of the attempt budget. Otherwise urllib3's
+                    # default (Retry(3)) would retry connection errors *inside*
+                    # each attempt, multiplying the effective transport-attempt
+                    # count well past _MAX_ATTEMPTS.
+                    retries=False,
+                )
+            except urllib3.exceptions.HTTPError:
+                # Transport-level failure (connection/read error): transient, but
+                # don't retry past the budget -- re-raise for _mint to handle.
+                if last:
+                    raise
+                self._sleep(_backoff_delay(attempt))
+                continue
+            if resp.status == 200:
+                return json.loads(resp.data)
+            if _is_transient_status(resp.status) and not last:
+                self._sleep(_backoff_delay(attempt))
+                continue
+            # A 4xx, or a 5xx with the retry budget exhausted: fatal, surfacing
+            # the last status/body.
+            raise TokenExchangeError(
+                f"token exchange failed: {resp.status} {resp.data[:200]!r}"
+            )
+
 
 __all__ = [
     "TokenExchangeError",