hotdata 0.11.0__tar.gz → 0.12.0__tar.gz

{hotdata-0.11.0 → hotdata-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata
-Version: 0.11.0
+Version: 0.12.0
 Summary: Hotdata API
 Author-email: Hotdata <developers@hotdata.dev>
 License: MIT
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/hotdata-dev/sdk-python
 Keywords: hotdata,api-client,data-platform
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: urllib3<3.0.0,>=2.7.0
+Requires-Dist: urllib3<3.0.0,>=2.8.0
 Requires-Dist: python-dateutil>=2.8.2
 Requires-Dist: pydantic>=2.4.0
 Requires-Dist: typing-extensions>=4.7.1
@@ -55,7 +55,17 @@ configuration = hotdata.Configuration(
 )
 ```
 
-`host` defaults to `https://api.hotdata.dev`. Override it if you target another environment.
+Each of these can come from the environment instead, the same variables the
+CLI uses: `HOTDATA_API_KEY`, `HOTDATA_WORKSPACE` and `HOTDATA_API_URL` fill in
+`api_key`, `workspace_id` and `host` when the argument is not passed. An
+explicit argument always wins.
+
+`host` defaults to `https://api.hotdata.dev`. Override it (or set
+`HOTDATA_API_URL`) if you target another environment.
+
+Almost every call is workspace-scoped. If no workspace id is configured, the
+SDK raises `hotdata.MissingWorkspaceError` before sending the request rather
+than letting the server answer with an unexplained 404.
 
 ## Usage
 
@@ -78,6 +88,25 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Each `Api` class groups endpoints by resource. Construct the client, then call the typed methods you need.
 
+## Loading tables
+
+Loads are serialised per table on the server. `hotdata.DatabasesApi` and
+`hotdata.ConnectionsApi` retry a load that hits a table another load still
+holds (HTTP 409, error code `RESOURCE_LOCKED`), honouring the server's
+`Retry-After`, for up to 60s by default:
+
+```python
+from hotdata import DatabasesApi, LoadRetryPolicy, TableLockedError
+
+databases = DatabasesApi(api_client, load_retry=LoadRetryPolicy(deadline_s=120))
+try:
+    databases.load_database_table(db_id, "public", "events", request)
+except TableLockedError as e:
+    print(f"gave up after {e.attempts} attempts: {e.reason}")
+```
+
+Other 409s (`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`) are raised immediately.
+
 ## Arrow results
 
 Query results can be fetched as an [Apache Arrow](https://arrow.apache.org/) IPC stream instead of JSON, which is faster and far more memory-efficient for large result sets. Install the optional extra:

{hotdata-0.11.0 → hotdata-0.12.0}/README.md

@@ -37,7 +37,17 @@ configuration = hotdata.Configuration(
 )
 ```
 
-`host` defaults to `https://api.hotdata.dev`. Override it if you target another environment.
+Each of these can come from the environment instead, the same variables the
+CLI uses: `HOTDATA_API_KEY`, `HOTDATA_WORKSPACE` and `HOTDATA_API_URL` fill in
+`api_key`, `workspace_id` and `host` when the argument is not passed. An
+explicit argument always wins.
+
+`host` defaults to `https://api.hotdata.dev`. Override it (or set
+`HOTDATA_API_URL`) if you target another environment.
+
+Almost every call is workspace-scoped. If no workspace id is configured, the
+SDK raises `hotdata.MissingWorkspaceError` before sending the request rather
+than letting the server answer with an unexplained 404.
 
 ## Usage
 
@@ -60,6 +70,25 @@ with hotdata.ApiClient(configuration) as api_client:
 
 Each `Api` class groups endpoints by resource. Construct the client, then call the typed methods you need.
 
+## Loading tables
+
+Loads are serialised per table on the server. `hotdata.DatabasesApi` and
+`hotdata.ConnectionsApi` retry a load that hits a table another load still
+holds (HTTP 409, error code `RESOURCE_LOCKED`), honouring the server's
+`Retry-After`, for up to 60s by default:
+
+```python
+from hotdata import DatabasesApi, LoadRetryPolicy, TableLockedError
+
+databases = DatabasesApi(api_client, load_retry=LoadRetryPolicy(deadline_s=120))
+try:
+    databases.load_database_table(db_id, "public", "events", request)
+except TableLockedError as e:
+    print(f"gave up after {e.attempts} attempts: {e.reason}")
+```
+
+Other 409s (`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`) are raised immediately.
+
 ## Arrow results
 
 Query results can be fetched as an [Apache Arrow](https://arrow.apache.org/) IPC stream instead of JSON, which is faster and far more memory-efficient for large result sets. Install the optional extra:

{hotdata-0.11.0 → hotdata-0.12.0}/hotdata/__init__.py

@@ -90,6 +90,7 @@ __all__ = [
     "DatabaseDefaultSchemaDecl",
     "DatabaseDefaultTableDecl",
     "DatabaseDetailResponse",
+    "DatabaseLineageResponse",
     "DatabaseSummary",
     "DeleteDatabaseBatchResponse",
     "DiscoveryStatus",
@@ -100,6 +101,7 @@ __all__ = [
     "FinalizeUploadRequest",
     "FinalizeUploadResponse",
     "ForkDatabaseRequest",
+    "ForkedFromInfo",
     "GetConnectionResponse",
     "GetDatabaseContextResponse",
     "GetResultResponse",
@@ -111,6 +113,8 @@ __all__ = [
     "JobStatus",
     "JobStatusResponse",
     "JobType",
+    "LineageAncestorInfo",
+    "LineageForkInfo",
     "ListConnectionsResponse",
     "ListDatabaseContextsResponse",
     "ListDatabasesResponse",
@@ -126,6 +130,7 @@ __all__ = [
     "LoadManagedTableRequest",
     "LoadManagedTableResponse",
     "ManagedSchemaResponse",
+    "ManagedTableConstantPerKeyResponse",
     "ManagedTableResponse",
     "MintUploadPartsRequest",
     "MintUploadPartsResponse",
@@ -148,6 +153,7 @@ __all__ = [
     "TextProfileDetail",
     "UpdateEmbeddingProviderRequest",
     "UpdateEmbeddingProviderResponse",
+    "UpdateManagedTableRequest",
     "UpdateSavedQueryRequest",
     "UploadSessionResponse",
     "UpsertDatabaseContextRequest",
@@ -228,6 +234,7 @@ from hotdata.models.database_count_response import DatabaseCountResponse as Data
 from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDecl as DatabaseDefaultSchemaDecl
 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_lineage_response import DatabaseLineageResponse as DatabaseLineageResponse
 from hotdata.models.database_summary import DatabaseSummary as DatabaseSummary
 from hotdata.models.delete_database_batch_response import DeleteDatabaseBatchResponse as DeleteDatabaseBatchResponse
 from hotdata.models.discovery_status import DiscoveryStatus as DiscoveryStatus
@@ -238,6 +245,7 @@ from hotdata.models.finalize_upload_part import FinalizeUploadPart as FinalizeUp
 from hotdata.models.finalize_upload_request import FinalizeUploadRequest as FinalizeUploadRequest
 from hotdata.models.finalize_upload_response import FinalizeUploadResponse as FinalizeUploadResponse
 from hotdata.models.fork_database_request import ForkDatabaseRequest as ForkDatabaseRequest
+from hotdata.models.forked_from_info import ForkedFromInfo as ForkedFromInfo
 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_result_response import GetResultResponse as GetResultResponse
@@ -249,6 +257,8 @@ 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
 from hotdata.models.job_type import JobType as JobType
+from hotdata.models.lineage_ancestor_info import LineageAncestorInfo as LineageAncestorInfo
+from hotdata.models.lineage_fork_info import LineageForkInfo as LineageForkInfo
 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
@@ -264,6 +274,7 @@ from hotdata.models.list_workspaces_response import ListWorkspacesResponse as Li
 from hotdata.models.load_managed_table_request import LoadManagedTableRequest as LoadManagedTableRequest
 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_constant_per_key_response import ManagedTableConstantPerKeyResponse as ManagedTableConstantPerKeyResponse
 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
@@ -286,6 +297,7 @@ from hotdata.models.temporal_profile_detail import TemporalProfileDetail as Temp
 from hotdata.models.text_profile_detail import TextProfileDetail as TextProfileDetail
 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_managed_table_request import UpdateManagedTableRequest as UpdateManagedTableRequest
 from hotdata.models.update_saved_query_request import UpdateSavedQueryRequest as UpdateSavedQueryRequest
 from hotdata.models.upload_session_response import UploadSessionResponse as UploadSessionResponse
 from hotdata.models.upsert_database_context_request import UpsertDatabaseContextRequest as UpsertDatabaseContextRequest
@@ -300,10 +312,21 @@ from hotdata.models.workspace_usage_response import WorkspaceUsageResponse as Wo
 # hotdata.query.QueryApi adds 429 retry + truncation auto-follow;
 # 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.*.
+# uploads; hotdata.loads.DatabasesApi / ConnectionsApi retry table loads
+# while another load holds the table (409 RESOURCE_LOCKED). 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
+from hotdata.loads import DatabasesApi as DatabasesApi  # noqa: E402,F811
+from hotdata.loads import ConnectionsApi as ConnectionsApi  # noqa: E402,F811
+from hotdata.loads import (  # noqa: E402,F401
+    LoadRetryPolicy as LoadRetryPolicy,
+    TableLockedError as TableLockedError,
+)
+# Raised client-side (scripts/patch_workspace_guard.py) when a workspace-
+# scoped call has no workspace id configured.
+from hotdata._workspace import MissingWorkspaceError as MissingWorkspaceError  # noqa: E402,F401
 # 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.`).
@@ -338,4 +361,7 @@ __all__ += [  # noqa: F405
     "UploadProgress",
     "UploadSource",
     "tqdm_progress",
+    "LoadRetryPolicy",
+    "TableLockedError",
+    "MissingWorkspaceError",
 ]

hotdata-0.12.0/hotdata/_workspace.py

@@ -0,0 +1,84 @@
+"""Fail fast when a workspace-scoped request has no workspace to go to.
+
+Most operations are scoped to a workspace through the ``X-Workspace-Id``
+header (the ``WorkspaceId`` security scheme). The generated client simply
+skips a scheme that has no configured value, so a ``Configuration`` built
+without ``workspace_id`` sends the request anyway and the server answers with
+a bare 404 that says nothing about what was missing.
+
+:func:`ensure_workspace` runs before the request is sent (wired into
+``ApiClient.update_params_for_auth`` by ``scripts/patch_workspace_guard.py``)
+and raises :class:`MissingWorkspaceError` naming the constructor argument and
+the environment variable. Operations whose security does not list
+``WorkspaceId`` (workspace management itself) are unaffected, as are calls
+that supply the header explicitly or override auth per request.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Optional
+
+from hotdata.exceptions import ApiValueError
+
+WORKSPACE_SCHEME = "WorkspaceId"
+WORKSPACE_HEADER = "X-Workspace-Id"
+
+
+class MissingWorkspaceError(ApiValueError):
+    """Raised before sending a workspace-scoped request when no workspace id
+    is configured.
+
+    Pass ``workspace_id=`` to :class:`hotdata.Configuration`, set the
+    ``HOTDATA_WORKSPACE`` environment variable, or send the ``X-Workspace-Id``
+    header explicitly for the call.
+    """
+
+    def __init__(self, resource_path: str, method: str) -> None:
+        self.resource_path = resource_path
+        self.method = method
+        super().__init__(
+            f"{method} {resource_path} is scoped to a workspace but no workspace id "
+            "is configured. Pass workspace_id=... to hotdata.Configuration(...), "
+            "set the HOTDATA_WORKSPACE environment variable, or send the "
+            f"{WORKSPACE_HEADER} header explicitly (_headers=...)."
+        )
+
+
+def ensure_workspace(
+    configuration: Any,
+    auth_settings: Optional[Iterable[str]],
+    headers: Optional[Mapping[str, Any]],
+    resource_path: str,
+    method: str,
+    request_auth: Optional[Mapping[str, Any]] = None,
+) -> None:
+    """Raise :class:`MissingWorkspaceError` if the operation needs a workspace
+    id and none would be sent.
+
+    :param configuration: The client's :class:`hotdata.Configuration`.
+    :param auth_settings: The operation's security scheme names.
+    :param headers: Header params already assembled for the request.
+    :param request_auth: A per-request auth override; when given the
+        configuration is bypassed entirely, so the check is skipped.
+    """
+    if request_auth:
+        return
+    if not auth_settings or WORKSPACE_SCHEME not in auth_settings:
+        return
+    if headers and any(
+        str(name).lower() == WORKSPACE_HEADER.lower() for name in headers
+    ):
+        return
+    settings = configuration.auth_settings()
+    scheme = settings.get(WORKSPACE_SCHEME) if settings else None
+    if scheme and scheme.get("value"):
+        return
+    raise MissingWorkspaceError(resource_path, method)
+
+
+__all__ = [
+    "WORKSPACE_HEADER",
+    "WORKSPACE_SCHEME",
+    "MissingWorkspaceError",
+    "ensure_workspace",
+]