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

hotdata_framework-0.12.1/.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.12.1/.github/workflows/publish.yml

@@ -0,0 +1,105 @@
+name: Publish to PyPI
+
+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-${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+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:
+      # Before checkout, because checkout resolves the input as an arbitrary ref:
+      # a branch or SHA is fetched first and only rejected later by the version
+      # match below, which is also looser (`^v[0-9]`). Strict here so the dispatch
+      # contract matches release.yml — release.sh only ever produces X.Y.Z.
+      - name: Validate release tag format
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$INPUT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "tag must look like vX.Y.Z, got: $INPUT_TAG" >&2
+            exit 1
+          fi
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Verify tag matches pyproject version
+        run: |
+          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="${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
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hotdata-framework
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          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@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

hotdata_framework-0.12.1/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+name: GitHub Release
+
+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
+
+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:
+      # Before checkout, because checkout resolves the input as an arbitrary ref
+      # — and this workflow needs the guard more than publish.yml does. It holds
+      # `contents: write`, and action-gh-release CREATES a tag when tag_name does
+      # not resolve to one, so an unvalidated `tag: main` would check out cleanly
+      # and leave refs/tags/main plus a release named for it. The push path is
+      # constrained by the v[0-9]* filter; the dispatch path was not constrained
+      # at all.
+      - name: Validate release tag format
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$INPUT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "tag must look like vX.Y.Z, got: $INPUT_TAG" >&2
+            exit 1
+          fi
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Read package metadata
+        id: meta
+        run: |
+          pkg_name=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['name'])")
+          pkg_version="${TAG#v}"
+          echo "name=${pkg_name}" >> "$GITHUB_OUTPUT"
+          echo "version=${pkg_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract changelog notes
+        id: notes
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          if [[ -f CHANGELOG.md ]]; then
+            body="$(python scripts/extract-changelog.py "$version")"
+          else
+            body="Release ${version}."
+          fi
+          delimiter="EOF_${RANDOM}_${RANDOM}"
+          {
+            echo "body<<${delimiter}"
+            echo "$body"
+            echo "${delimiter}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
+        with:
+          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
+          # 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.1}/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [0.12.1] - 2026-08-18
+
+### Fixed
+
+- fix(load): submit managed loads as a job and poll, instead of holding one request open
+
+## [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.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hotdata-framework
-Version: 0.11.0
+Version: 0.12.1
 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.1}/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.1}/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",