hotdata-framework 0.11.0__tar.gz → 0.12.0__tar.gz

hotdata_framework-0.12.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: daily
+    allow:
+      - dependency-name: hotdata
+
+  # Action pins had no watcher, which is how gh-action-pypi-publish sat at
+  # v1.13.0 until its bundled twine broke a release at upload time. Unlike the
+  # uv entry there is no `allow` filter: the point is to see every stale pin,
+  # not a chosen one.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/.github/workflows/publish.yml

@@ -4,9 +4,20 @@ on:
   push:
     tags:
       - 'v[0-9]*'
+  # Retry an existing tag without moving it. A publish can fail for reasons that
+  # have nothing to do with the code — a stale action pin, a PyPI outage — and
+  # with only the tag trigger the choices were to delete and re-push the tag or
+  # to burn a version number on a CI fix. Neither is a good answer to
+  # "the upload failed, run it again".
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing tag to build and publish (e.g. v1.2.3)
+        required: true
+        type: string
 
 concurrency:
-  group: pypi-publish-${{ github.ref_name }}
+  group: pypi-publish-${{ inputs.tag || github.ref_name }}
   cancel-in-progress: false
 
 permissions:
@@ -16,8 +27,13 @@ jobs:
   build:
     name: Build distribution
     runs-on: ubuntu-latest
+    env:
+      # The tag being released, whether it arrived by push or by dispatch.
+      TAG: ${{ inputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -28,11 +44,11 @@ jobs:
 
       - name: Verify tag matches pyproject version
         run: |
-          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9] ]]; then
-            echo "Release tag '$GITHUB_REF_NAME' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
+          if [[ ! "$TAG" =~ ^v[0-9] ]]; then
+            echo "Release tag '$TAG' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
             exit 1
           fi
-          tag="${GITHUB_REF_NAME#v}"
+          tag="${TAG#v}"
           pkg_version=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
           if [ "$tag" != "$pkg_version" ]; then
             echo "Release tag ($tag) does not match pyproject.toml version ($pkg_version)" >&2
@@ -65,5 +81,10 @@ jobs:
           name: dist
           path: dist/
 
+      # v1.13.0's bundled twine rejects `Metadata-Version: 2.5`, which current
+      # hatchling emits: `InvalidDistribution: '2.5' is not a valid metadata
+      # version`. The build job's own `twine check --strict` passes, because it
+      # pip-installs a current twine — so the failure appears only at upload,
+      # after the tag is already public.
       - name: Publish via Trusted Publishing
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/.github/workflows/release.yml

@@ -4,6 +4,15 @@ on:
   push:
     tags:
       - 'v[0-9]*'
+  # Repair the Release for a tag that already exists, without moving it. See
+  # RELEASING.md, "If a release workflow fails" — added alongside this trigger,
+  # since a capability nobody can find is not much better than not having it.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing tag to create or update a Release for (e.g. v1.2.3)
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -12,8 +21,13 @@ jobs:
   release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
+    env:
+      # The tag being released, whether it arrived by push or by dispatch.
+      TAG: ${{ inputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -23,7 +37,7 @@ jobs:
         id: meta
         run: |
           pkg_name=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['name'])")
-          pkg_version="${GITHUB_REF_NAME#v}"
+          pkg_version="${TAG#v}"
           echo "name=${pkg_name}" >> "$GITHUB_OUTPUT"
           echo "version=${pkg_version}" >> "$GITHUB_OUTPUT"
 
@@ -31,7 +45,7 @@ jobs:
         id: notes
         run: |
           set -euo pipefail
-          version="${GITHUB_REF_NAME#v}"
+          version="${TAG#v}"
           if [[ -f CHANGELOG.md ]]; then
             body="$(python scripts/extract-changelog.py "$version")"
           else
@@ -47,8 +61,14 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
         with:
-          tag_name: ${{ github.ref_name }}
+          tag_name: ${{ inputs.tag || github.ref_name }}
           name: ${{ steps.meta.outputs.name }} ${{ steps.meta.outputs.version }}
           body: ${{ steps.notes.outputs.body }}
           generate_release_notes: false
-          make_latest: true
+          # Let GitHub decide by tag date/semver rather than by run order. On a
+          # push the tag is the newest version and becomes latest; on a dispatch
+          # repairing an older tag, a newer release keeps the badge. Note `false`
+          # is not "leave alone" — it explicitly marks a release NOT latest, so
+          # gating on the event would demote the newest tag in the very case this
+          # trigger exists for: repairing its Release after a failed push run.
+          make_latest: legacy

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [0.12.0] - 2026-08-11
+
+### Added
+
+- Table storage layout, both directions. `add_managed_table()` and
+  `create_managed_database()` take `partition_by` / `sorted_by`, and
+  `managed_table_layout()` reads back what was actually declared as a
+  `TableLayout`. `TablePartitionKey` and `TableSortKey` are re-exported so
+  callers need one import.
+
+  Both halves matter because a layout is fixed when the table is created and
+  there is no alter path: a table declared without one keeps that shape until it
+  is recreated and its data rewritten. So declaring is not enough — a caller has
+  to be able to confirm it took, and to refuse to load when it cannot.
+
+  `managed_table_layout()` raises `KeyError` for a table that is not declared,
+  rather than returning an empty layout. "Not there" and "declared without a
+  layout" lead to opposite decisions for a caller.
+
+  Until now this package could not express a layout at all, which is why at least
+  one consumer hand-built the HTTP request instead. The generated key models are
+  passed through rather than wrapped, so the transform vocabulary stays exactly
+  the API's.
+
+### Changed
+
+- Require `hotdata>=0.9.0,<0.10`. 0.9.0 is the first release whose models carry
+  `partition_by` / `sorted_by` on the add-table request, the create-database
+  table declarations, and the table-info response. On an older `hotdata` the
+  fields would be silently dropped by the model and the table declared without a
+  layout, returning success — which is the failure this feature exists to end.
+
 ## [0.11.0] - 2026-08-11
 
 ### Changed

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/CONTRACT.md

@@ -31,6 +31,9 @@ The supported import surface is:
 - `WorkspaceSelection`
 - `ManagedDatabase`
 - `ManagedTable`
+- `TableLayout`
+- `TablePartitionKey`
+- `TableSortKey`
 - `LoadManagedTableResult`
 - `CreateIndexResult`
 - `DEFAULT_SCHEMA`
@@ -56,6 +59,8 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
   adapters should pass `connection_id` when known.
 - `uploads()` returns the uploads API wrapper for parquet staging.
 - `list_managed_databases()` returns all databases via the `/databases` API.
+- `add_managed_table(...)` and `create_managed_database(...)` accept `partition_by` / `sorted_by` to declare a table's storage layout. The layout is fixed when the table is created and cannot be altered afterwards, so omitting it is permanent for that table.
+- `managed_table_layout(database, table, schema=...)` returns the declared layout as `TableLayout`. Empty lists mean no layout was declared — sound only because the table is resolved through a managed database. Raises `KeyError` when the table is not declared, keeping "absent" distinct from "declared without a layout".
 - `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan). A `403` from `/databases` surfaces as `RuntimeError` (forbidden, not absent), preserving the underlying `ApiException` as `__cause__`.
 - `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front. Returns a `ManagedDatabase` (id + `default_connection_id`) sufficient to load without a further read.
 - `delete_managed_database(name_or_id)` deletes a database via the `/databases` API.
@@ -64,7 +69,7 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
 - `load_managed_table(database, table, schema=..., upload_id=..., file=...)` publishes parquet data into a declared managed table.
 - `delete_managed_table(database, table, schema=...)` deletes a managed table.
 - `create_index(database, table, schema=..., columns=..., index_type=..., index_name=...)` builds a `"sorted"`, `"bm25"`, or `"vector"` index on a managed table and returns a `CreateIndexResult`. It is the framework-side equivalent of the CLI's `hotdata indexes create`; indexing a table on a plain (non-managed) connection is out of scope. `index_name` defaults to `{table}_{columns}_{index_type}`, matching the CLI's derivation when `--name` is omitted. `index_type` is required rather than defaulting to the API's `"sorted"`. The build runs as a background job; the call polls it to a terminal state and raises `RuntimeError` with the job's `error_message` when it fails, because the submit call reports success regardless. `wait=False` returns as soon as the job is accepted, with `status="pending"` and a `job_id` for the caller to poll. For `index_type="vector"`, omitting `embedding_provider_id` indexes an existing vector column and `metric` (`"l2"`, `"cosine"`, `"dot"`) selects the distance function the index accelerates — a query using a different function silently falls back to a full scan; setting `embedding_provider_id` indexes a source *text* column instead, and the returned `source_column` names the column to pass to `vector_distance`. Argument combinations the server would silently ignore raise `ValueError` before any request is sent.
-- The `database` argument of `list_managed_tables`, `load_managed_table`, `add_managed_table`, `delete_managed_table`, `delete_managed_database`, `create_index`, and `execute_sql` accepts a name/id **or** an already-resolved `ManagedDatabase`. Passing a `ManagedDatabase` skips the name/id read probe, so a create-scoped key that cannot read `/databases` can load into a database it just created.
+- The `database` argument of `list_managed_tables`, `load_managed_table`, `add_managed_table`, `delete_managed_table`, `delete_managed_database`, `create_index`, `managed_table_layout`, and `execute_sql` accepts a name/id **or** an already-resolved `ManagedDatabase`. Passing a `ManagedDatabase` skips the name/id read probe, so a create-scoped key that cannot read `/databases` can load into a database it just created.
 
 ### `QueryResult`
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hotdata-framework
-Version: 0.11.0
+Version: 0.12.0
 Summary: Python framework for building Hotdata integrations: workspace 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.9,>=0.8.0
+Requires-Dist: hotdata<0.10,>=0.9.0
 Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=14.0
 Description-Content-Type: text/markdown

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/RELEASING.md

@@ -34,6 +34,27 @@ Pushing a `vX.Y.Z` tag triggers two workflows:
 | `publish.yml` | Build wheel/sdist and publish to PyPI |
 | `release.yml` | Create the GitHub Release with notes from `CHANGELOG.md` |
 
+## If a release workflow fails
+
+Both workflows also accept a manual re-run against an existing tag, so a failure
+unrelated to the code — a stale action pin, a PyPI outage — does not require
+deleting the tag or burning a version number:
+
+```bash
+gh workflow run "Publish to PyPI" --ref main -f tag=vX.Y.Z
+gh workflow run "GitHub Release"  --ref main -f tag=vX.Y.Z
+```
+
+`--ref main` selects the workflow *definition*, so a fix to the workflow file
+itself is picked up; everything it runs — including `scripts/extract-changelog.py`
+— still comes from the tag, since that is what is being built and released. The
+two refs serve different purposes, which is why they can differ.
+
+A version is only spent once PyPI has accepted an upload. If the publish failed
+before that, the same version can still be published — check with
+`curl -s -o /dev/null -w '%{http_code}' https://pypi.org/pypi/<pkg>/<version>/json`
+returning 404.
+
 ## Enforcement
 
 - **PR check** (`check-release.yml`): if `pyproject.toml` version changes, `CHANGELOG.md` must contain a matching `## [X.Y.Z]` section.

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

@@ -2,6 +2,9 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
+from hotdata.models.table_partition_key import TablePartitionKey
+from hotdata.models.table_sort_key import TableSortKey
+
 from hotdata_framework.client import (
     HotdataClient,
     ResultSummary,
@@ -14,6 +17,7 @@ from hotdata_framework.databases import (
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
+    TableLayout,
     is_parquet_path,
 )
 from hotdata_framework.env import (
@@ -55,6 +59,9 @@ __all__ = [
     "QueryResult",
     "ResultSummary",
     "RunHistoryItem",
+    "TableLayout",
+    "TablePartitionKey",
+    "TableSortKey",
     "WorkspaceSelection",
     "__version__",
     "classify_sdk_error",

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/hotdata_framework/client.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import functools
 import time
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
 from dataclasses import asdict, dataclass
 from typing import Any, Literal, get_args
 
@@ -15,9 +15,6 @@ from hotdata.api.jobs_api import JobsApi
 from hotdata.api.query_api import QueryApi
 from hotdata.api.query_runs_api import QueryRunsApi
 from hotdata.api.results_api import ResultsApi
-# The enriched wrapper (hotdata.uploads), NOT the generated hotdata.api class:
-# it adds the full upload_file orchestration used by upload_parquet.
-from hotdata.uploads import UploadError, UploadsApi
 from hotdata.exceptions import ApiException
 from hotdata.models.add_managed_table_request import AddManagedTableRequest
 from hotdata.models.async_query_response import AsyncQueryResponse
@@ -32,6 +29,12 @@ from hotdata.models.query_request import QueryRequest
 from hotdata.models.query_response import QueryResponse
 from hotdata.models.submit_job_response import SubmitJobResponse
 from hotdata.models.table_info import TableInfo
+from hotdata.models.table_partition_key import TablePartitionKey
+from hotdata.models.table_sort_key import TableSortKey
+
+# The enriched wrapper (hotdata.uploads), NOT the generated hotdata.api class:
+# it adds the full upload_file orchestration used by upload_parquet.
+from hotdata.uploads import UploadError, UploadsApi
 from urllib3.exceptions import HTTPError as Urllib3HTTPError
 from urllib3.exceptions import ProtocolError
 
@@ -41,6 +44,7 @@ from hotdata_framework.databases import (
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
+    TableLayout,
     api_error_message,
     enum_value,
     is_parquet_path,
@@ -286,18 +290,44 @@ class HotdataClient:
         schema: str = DEFAULT_SCHEMA,
         tables: list[str] | None = None,
         keys: dict[str, list[str]] | None = None,
+        partition_by: dict[str, Sequence[TablePartitionKey]] | None = None,
+        sorted_by: dict[str, Sequence[TableSortKey]] | 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."""
+        (enabling delete/update/upsert on it); omitted tables are keyless.
+
+        ``partition_by`` and ``sorted_by`` are keyed the same way — table name to
+        that table's keys, in declaration order — so a database can be created
+        with its tables already laid out. Tables absent from the mapping get no
+        layout, and a layout cannot be added afterwards: it is fixed at table
+        creation, so a table created here without one stays that way.
+        """
         keys = keys or {}
+        partition_by = partition_by or {}
+        sorted_by = sorted_by or {}
+        # A layout aimed at a table that is not being created would otherwise be
+        # dropped in silence, and the table it was meant for created flat — which
+        # is permanent, since a layout is fixed at creation with no alter path. A
+        # typo'd `keys` entry costs nothing by comparison: load_managed_table
+        # takes `key=` per call, so it can be corrected later.
+        unknown = (set(partition_by) | set(sorted_by)) - set(tables or ())
+        if unknown:
+            raise ValueError(
+                f"layout given for tables not being created: {', '.join(sorted(unknown))}"
+            )
         schemas = None
         if tables:
             schemas = [
                 DatabaseDefaultSchemaDecl(
                     name=schema,
                     tables=[
-                        DatabaseDefaultTableDecl(name=t, key=list(keys.get(t, [])))
+                        DatabaseDefaultTableDecl(
+                            name=t,
+                            key=list(keys.get(t, [])),
+                            partition_by=list(partition_by.get(t, ())) or None,
+                            sorted_by=list(sorted_by.get(t, ())) or None,
+                        )
                         for t in tables
                     ],
                 )
@@ -417,6 +447,8 @@ class HotdataClient:
         *,
         schema: str = DEFAULT_SCHEMA,
         key: list[str] | None = None,
+        partition_by: Sequence[TablePartitionKey] | None = None,
+        sorted_by: Sequence[TableSortKey] | None = None,
     ) -> ManagedTable:
         """Declare a new table on an existing managed database.
 
@@ -424,9 +456,24 @@ class HotdataClient:
         :meth:`load_managed_table`. Use this to evolve a managed database's
         schema after creation without recreating it. ``key`` sets the
         row-identity columns for delete/update/upsert; omit for keyless.
+
+        ``partition_by`` and ``sorted_by`` declare the table's storage layout, in
+        the order given. THIS IS THE ONLY CHANCE TO SET IT: a layout is fixed
+        when the table is created and there is no alter path, so a table declared
+        without one keeps that shape until it is recreated and its data rewritten.
+        Confirm what was applied with :meth:`managed_table_layout`.
+
+        The generated key models are passed through rather than wrapped, so the
+        transform vocabulary and field names stay exactly the API's. Both are
+        re-exported from ``hotdata_framework`` so callers need one import.
         """
         db = self._as_managed_database(database)
-        request = AddManagedTableRequest(name=table, key=list(key or []))
+        request = AddManagedTableRequest(
+            name=table,
+            key=list(key or []),
+            partition_by=list(partition_by) if partition_by else None,
+            sorted_by=list(sorted_by) if sorted_by else None,
+        )
         try:
             self._databases_api().add_database_table(db.id, schema, request)
         except ApiException as e:
@@ -439,6 +486,51 @@ class HotdataClient:
             last_sync=None,
         )
 
+    def managed_table_layout(
+        self,
+        database: str | ManagedDatabase,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+    ) -> TableLayout:
+        """Read back a managed table's declared storage layout.
+
+        The counterpart to the ``partition_by`` / ``sorted_by`` arguments on
+        :meth:`add_managed_table` and :meth:`create_managed_database`. Declaring a
+        layout is only half of it: it is fixed at table creation with no alter
+        path, so a caller that cares whether the layout took has to look, and a
+        caller that cannot confirm it should refuse to load rather than fill a
+        table it can never repair.
+
+        Empty lists here mean no layout was declared. That reading is sound
+        because the table is resolved through a managed database — the same fields
+        on a table discovered from an external connection are empty because its
+        layout belongs to the upstream system, which is not the same claim.
+
+        Raises KeyError when the table is not present on the database, so that
+        "no such table" is distinguishable from "declared without a layout"; the
+        two are very different for a caller deciding whether to load.
+        """
+        db = self._as_managed_database(database)
+        # Filtered server-side rather than paging iter_tables: this answers a
+        # single-table question, and a table sorting late in the listing would
+        # otherwise cost several round trips. include_columns is left off — the
+        # layout lives on the table row, not the columns.
+        resp = self._information_schema().information_schema(
+            connection_id=db.default_connection_id,
+            var_schema=schema,
+            table=table,
+            limit=1,
+        )
+        for info in resp.tables:
+            return TableLayout(
+                schema_name=schema,
+                table_name=table,
+                partition_by=list(info.partition_by or []),
+                sorted_by=list(info.sorted_by or []),
+            )
+        raise KeyError(f"{schema}.{table} is not declared on database {db.id}")
+
     def delete_managed_table(
         self,
         database: str | ManagedDatabase,

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/hotdata_framework/databases.py

@@ -7,6 +7,8 @@ from pathlib import Path
 from typing import Any
 
 from hotdata.exceptions import ApiException
+from hotdata.models.table_partition_key import TablePartitionKey
+from hotdata.models.table_sort_key import TableSortKey
 
 DEFAULT_SCHEMA = "public"
 
@@ -33,6 +35,47 @@ class ManagedTable:
         return asdict(self)
 
 
+@dataclass(frozen=True)
+class TableLayout:
+    """A managed table's declared storage layout, as the server reports it.
+
+    Both lists carry the generated `TablePartitionKey` / `TableSortKey` models,
+    in the order they were declared. A layout is fixed when the table is created
+    and cannot be altered, so reading it back is the only way to confirm what was
+    actually applied — which is why this exists as a first-class return rather
+    than a field on `ManagedTable`, whose other fields describe sync state.
+
+    Empty lists mean no layout was declared. That reading is only safe because
+    this is resolved through a MANAGED database: the same fields on a table
+    discovered from an external connection are empty because its layout belongs
+    to the upstream system, which is "not known from here" rather than
+    "confirmed none".
+    """
+
+    schema_name: str
+    table_name: str
+    partition_by: list[TablePartitionKey]
+    sorted_by: list[TableSortKey]
+
+    # NO to_dict(), unlike every other dataclass here, and deliberately so.
+    # `asdict()` would copy the pydantic key models through untouched rather than
+    # flatten them, so it would not return a plain dict. Mapping each key through
+    # its own `to_dict()` does flatten, but returns `dict[str, Any]` and adds
+    # eight errors under this package's strict mypy settings; hand-building the
+    # dict from named fields avoids that but silently drops any field a later
+    # spec adds to the key models, which is the failure this whole feature exists
+    # to prevent. A caller wanting dicts can map `k.to_dict()` itself and own
+    # that choice.
+
+    @property
+    def is_partitioned(self) -> bool:
+        return bool(self.partition_by)
+
+    @property
+    def is_sorted(self) -> bool:
+        return bool(self.sorted_by)
+
+
 @dataclass(frozen=True)
 class LoadManagedTableResult:
     connection_id: str

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hotdata-framework"
-version = "0.11.0"
+version = "0.12.0"
 description = "Python framework for building Hotdata integrations: workspace runtime, query execution, and managed databases"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,7 +37,7 @@ dependencies = [
   # uncapped floor turns someone else's release into a break in ours,
   # with no commit of our own to point at. Raise the cap deliberately, after
   # running the suite against the new minor.
-  "hotdata>=0.8.0,<0.9",
+  "hotdata>=0.9.0,<0.10",
   "pandas>=2.0",
   "pyarrow>=14.0",
 ]

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/tests/test_contract.py

@@ -23,6 +23,9 @@ def test_public_exports_contract():
         "QueryResult",
         "ResultSummary",
         "RunHistoryItem",
+        "TableLayout",
+        "TablePartitionKey",
+        "TableSortKey",
         "WorkspaceSelection",
         "__version__",
         "classify_sdk_error",

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/tests/test_databases.py

@@ -9,10 +9,13 @@ from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
 
 from hotdata_framework.client import HotdataClient
 from hotdata_framework.databases import (
+    ManagedDatabase,
     is_parquet_path,
     managed_database_from_detail,
 )
 
+_MANAGED_DB = ManagedDatabase(id="db_1", description="d", default_connection_id="conn_1")
+
 
 def _decl_key_supported() -> bool:
     # `key` ships with the regenerated client; the key tests activate once it does.
@@ -383,3 +386,173 @@ class _Any:
 
     def __eq__(self, other: object) -> bool:
         return True
+
+
+# ---------------------------------------------------------------------------
+# Table layout: declaring it, and reading it back
+#
+# A layout is fixed when the table is created and there is no alter path, so a
+# silently dropped argument produces a table that can never be repaired — only
+# recreated with its data rewritten. That is why these assert on the REQUEST
+# object reaching the API rather than on the call succeeding: the generated model
+# ignores unknown fields, so passing `partition_by=` to a client whose model
+# lacks it returns 201 and declares a layout-less table. That exact silent drop
+# is why this package could not express a layout until now.
+
+
+def _layout():
+    from hotdata_framework import TablePartitionKey, TableSortKey
+
+    return (
+        [TablePartitionKey(column="event_date", transform="identity")],
+        [TableSortKey(column="event_time", direction="desc", nulls="last")],
+    )
+
+
+def test_add_managed_table_sends_the_layout():
+
+    parts, sorts = _layout()
+    client = _client()
+    captured = {}
+
+    class FakeDatabasesApi:
+        def add_database_table(self, db_id, schema, request):
+            captured["request"] = request
+            captured["schema"] = schema
+
+    with patch.object(client, "_databases_api", return_value=FakeDatabasesApi()), patch.object(
+        client, "_as_managed_database", return_value=_MANAGED_DB
+    ):
+        client.add_managed_table("db_1", "files", key=["id"], partition_by=parts, sorted_by=sorts)
+
+    req = captured["request"]
+    # Serialised, because that is what actually goes on the wire — a field the
+    # model does not know about vanishes here rather than at the call site.
+    body = req.to_dict()
+    assert body["partition_by"] == [{"column": "event_date", "transform": "identity"}]
+    assert body["sorted_by"] == [{"column": "event_time", "direction": "desc", "nulls": "last"}]
+    assert body["key"] == ["id"]
+
+
+def test_add_managed_table_omits_layout_when_not_asked():
+    """Omitted must stay omitted: sending empty arrays would declare "explicitly
+    no layout" on a server that distinguishes absent from empty."""
+
+    client = _client()
+    captured = {}
+
+    class FakeDatabasesApi:
+        def add_database_table(self, db_id, schema, request):
+            captured["request"] = request
+
+    with patch.object(client, "_databases_api", return_value=FakeDatabasesApi()), patch.object(
+        client, "_as_managed_database", return_value=_MANAGED_DB
+    ):
+        client.add_managed_table("db_1", "files")
+
+    body = captured["request"].to_dict()
+    assert body.get("partition_by") is None
+    assert body.get("sorted_by") is None
+
+
+def test_create_managed_database_sends_per_table_layout():
+
+    parts, sorts = _layout()
+    client = _client()
+    captured = {}
+
+    class FakeDatabasesApi:
+        def create_database(self, request):
+            captured["request"] = request
+            return _detail(id="db_new", description="demo")
+
+    with patch.object(client, "_databases_api", return_value=FakeDatabasesApi()):
+        client.create_managed_database(
+            "demo",
+            tables=["files", "other"],
+            keys={"files": ["id"]},
+            partition_by={"files": parts},
+            sorted_by={"files": sorts},
+        )
+
+    decls = captured["request"].to_dict()["schemas"][0]["tables"]
+    by_name = {d["name"]: d for d in decls}
+    assert by_name["files"]["partition_by"] == [
+        {"column": "event_date", "transform": "identity"}
+    ]
+    assert by_name["files"]["sorted_by"] == [
+        {"column": "event_time", "direction": "desc", "nulls": "last"}
+    ]
+    # A table absent from the mapping gets no layout, not an empty one.
+    assert by_name["other"].get("partition_by") is None
+    assert by_name["other"].get("sorted_by") is None
+
+
+def test_managed_table_layout_reads_it_back():
+    parts, sorts = _layout()
+    client = _client()
+    info = SimpleNamespace(
+        table="files", var_schema="public", partition_by=parts, sorted_by=sorts
+    )
+    captured = {}
+
+    class FakeInfoSchema:
+        def information_schema(self, **kwargs):
+            captured.update(kwargs)
+            return SimpleNamespace(tables=[info])
+
+    with patch.object(client, "_information_schema", return_value=FakeInfoSchema()), patch.object(
+        client, "_as_managed_database", return_value=_MANAGED_DB
+    ):
+        layout = client.managed_table_layout("db_1", "files")
+
+    assert layout.table_name == "files"
+    assert [p.column for p in layout.partition_by] == ["event_date"]
+    assert [s.column for s in layout.sorted_by] == ["event_time"]
+    assert layout.is_partitioned is True
+    assert layout.is_sorted is True
+    # Filtered server-side, not by paging the whole listing.
+    assert captured["var_schema"] == "public"
+    assert captured["table"] == "files"
+    assert captured["connection_id"] == _MANAGED_DB.default_connection_id
+
+
+def test_managed_table_layout_distinguishes_absent_from_unpartitioned():
+    """KeyError for a table the server does not report, empty lists for one
+    declared without a layout. Collapsing the two would let a caller read "table
+    isn't there" as "confirmed no layout" and load into something unverified.
+
+    Each call gets a FRESH response via side_effect. Sharing one would leave the
+    second assertion inspecting a consumed result rather than the case named
+    here.
+    """
+    client = _client()
+    plain = SimpleNamespace(table="files", var_schema="public", partition_by=[], sorted_by=[])
+
+    def respond(**kwargs):
+        found = [plain] if kwargs.get("table") == "files" else []
+        return SimpleNamespace(tables=found)
+
+    api = SimpleNamespace(information_schema=respond)
+    with patch.object(client, "_information_schema", return_value=api), patch.object(
+        client, "_as_managed_database", return_value=_MANAGED_DB
+    ):
+        layout = client.managed_table_layout("db_1", "files")
+        assert layout.is_partitioned is False and layout.is_sorted is False
+
+        with pytest.raises(KeyError, match="missing"):
+            client.managed_table_layout("db_1", "missing")
+
+
+def test_create_managed_database_refuses_layout_for_a_table_it_is_not_creating():
+    """A typo'd table name in the layout mapping would otherwise be dropped, and
+    the table it was meant for created flat — permanently, since a layout cannot
+    be added later."""
+    parts, _ = _layout()
+    client = _client()
+
+    with patch.object(client, "_databases_api") as dbs, pytest.raises(ValueError, match="fils"):
+        client.create_managed_database(
+            "demo", tables=["files"], partition_by={"fils": parts}
+        )
+    dbs.return_value.create_database.assert_not_called()

{hotdata_framework-0.11.0 → hotdata_framework-0.12.0}/uv.lock

@@ -86,7 +86,7 @@ wheels = [
 
 [[package]]
 name = "hotdata"
-version = "0.8.0"
+version = "0.9.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/8a/38/30ed3d1d99413e7684672fa424baef85a347db465b90c774443320cf1cea/hotdata-0.8.0.tar.gz", hash = "sha256:cdac515ffa193ed028491e4b7abcd1b6404d4e3f96986c9c0a2b2f407db42eb6", size = 216848, upload-time = "2026-07-20T06:30:37.659Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/6e/db/91d0e8f8a8bfc9a76b588c8dc2ecb054d3e70ebf2ee7a70cd6e4a99a7dec/hotdata-0.9.0.tar.gz", hash = "sha256:35e4a569b7223e025c26b0d3299c8b4cd493276f32826682de6df9e583cea4ef", size = 217368, upload-time = "2026-08-11T14:09:08.166Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/bc/0f/f2ccaeb0f910c3f8cd84a911d934704277f0d6e5a20f8b49cf0eedb2a8aa/hotdata-0.8.0-py3-none-any.whl", hash = "sha256:5d64bfc185a0e7e2bf34ebdcea50787d3418fb250dacc53e00dc74d64e99f753", size = 316923, upload-time = "2026-07-20T06:30:35.778Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/48/9b2f5cbbcc92e6dc06a6980fcf4413b83484af302a78263381a22236c308/hotdata-0.9.0-py3-none-any.whl", hash = "sha256:9d942a0d78979552ad641419e5706c9703d5165db0cf3497ae49344cd032e635", size = 316070, upload-time = "2026-08-11T14:09:06.589Z" },
 ]
 
 [[package]]
 name = "hotdata-framework"
-version = "0.11.0"
+version = "0.12.0"
 source = { editable = "." }
 dependencies = [
     { name = "hotdata" },
@@ -120,7 +120,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "hotdata", specifier = ">=0.8.0,<0.9" },
+    { name = "hotdata", specifier = ">=0.9.0,<0.10" },
     { name = "pandas", specifier = ">=2.0" },
     { name = "pyarrow", specifier = ">=14.0" },
 ]

hotdata_framework-0.11.0/.github/dependabot.yml

@@ -1,8 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: uv
-    directory: "/"
-    schedule:
-      interval: daily
-    allow:
-      - dependency-name: hotdata