hotdata-runtime 0.1.0__tar.gz → 0.2.0__tar.gz

hotdata_runtime-0.2.0/.github/workflows/check-release.yml

@@ -0,0 +1,26 @@
+name: Check release metadata
+
+on:
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'CHANGELOG.md'
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Verify changelog matches version bump
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Check release metadata
+        run: python scripts/check-release.py

hotdata_runtime-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python 3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Test
+        run: uv run pytest -v

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/.github/workflows/publish.yml

@@ -28,7 +28,6 @@ jobs:
 
       - name: Verify tag matches pyproject version
         run: |
-          # Release tags must start with `v` followed by a PEP 440 version (e.g. v1.2.3, v1.2.3a1).
           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
             exit 1

hotdata_runtime-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: GitHub Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - 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="${GITHUB_REF_NAME#v}"
+          echo "name=${pkg_name}" >> "$GITHUB_OUTPUT"
+          echo "version=${pkg_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract changelog notes
+        id: notes
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#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@1e812e8210a4a8a0b23075e5795f2a4e2b2a0b7 # v2.2.2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ steps.meta.outputs.name }} ${{ steps.meta.outputs.version }}
+          body: ${{ steps.notes.outputs.body }}
+          generate_release_notes: false
+          make_latest: true

hotdata_runtime-0.2.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-24
+
+### Changed
+
+- Switch managed database operations from the connections API to the dedicated `/databases` API (`hotdata>=0.2.3` required).
+- `create_managed_database` first parameter renamed from `name` to `description` (keyword-only).
+- `ManagedDatabase` dataclass: replace `name`/`source_type` fields with `description`/`default_connection_id`.
+- `resolve_managed_database` tries direct ID lookup first, then falls back to a description scan.
+- `list_managed_databases` now fetches all databases regardless of source type.
+- `list_managed_tables`, `load_managed_table`, and `delete_managed_table` use `default_connection_id` instead of database `id` for connection-scoped operations.
+
+### Added
+
+- `create_managed_database` accepts an optional `expires_at` parameter.
+
+### Removed
+
+- `MANAGED_SOURCE_TYPE`, `build_managed_config`, and `create_connection_request` removed from the public API.
+
+## [0.1.1] - 2026-05-19
+
+### Added
+
+- Managed database helpers on `HotdataClient`.
+
+## [0.1.0] - 2026-05-06
+
+### Added
+
+- Initial release.

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/CONTRACT.md

@@ -30,6 +30,11 @@ The supported import surface is:
 - `ResultSummary`
 - `RunHistoryItem`
 - `WorkspaceSelection`
+- `ManagedDatabase`
+- `ManagedTable`
+- `LoadManagedTableResult`
+- `DEFAULT_SCHEMA`
+- `is_parquet_path`
 
 Adapters should import from `hotdata_runtime` and treat this surface as the stable API.
 
@@ -49,6 +54,15 @@ Adapters should import from `hotdata_runtime` and treat this surface as the stab
 - `list_qualified_table_names(...)` returns sorted fully qualified table names.
 - `columns_for_qualified(qualified, connection_id=...)` resolves table columns, and
   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.
+- `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan).
+- `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front.
+- `delete_managed_database(name_or_id)` deletes a database via the `/databases` API.
+- `list_managed_tables(database, schema=...)` lists tables in a managed database.
+- `upload_parquet(path)` uploads a local parquet file and returns an upload id.
+- `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.
 
 ### `QueryResult`
 

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: hotdata-runtime
-Version: 0.1.0
+Version: 0.2.0
 Summary: Workspace/session runtime primitives for Hotdata integrations
 License: MIT
 Requires-Python: >=3.10
-Requires-Dist: hotdata>=0.1.0
+Requires-Dist: hotdata>=0.2.3
 Requires-Dist: pandas>=2.0
 Description-Content-Type: text/markdown
 
@@ -23,6 +23,7 @@ Runtime boundary and guarantees are defined in `CONTRACT.md`.
 - **SQL execution helper** — run SQL through `POST /v1/query`, poll async query runs when needed, and return a `QueryResult`.
 - **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
 - **History helpers** — list recent results and query run history with normalized dataclasses.
+- **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
 - **Health helpers** — build compact API/workspace health summaries for UI integrations.
 
 Install:

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/README.md

@@ -13,6 +13,7 @@ Runtime boundary and guarantees are defined in `CONTRACT.md`.
 - **SQL execution helper** — run SQL through `POST /v1/query`, poll async query runs when needed, and return a `QueryResult`.
 - **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
 - **History helpers** — list recent results and query run history with normalized dataclasses.
+- **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
 - **Health helpers** — build compact API/workspace health summaries for UI integrations.
 
 Install:

hotdata_runtime-0.2.0/RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing
+
+Every release uses `./scripts/release.sh`. Do not bump versions, tag, or create GitHub Releases manually.
+
+## One-time setup
+
+- Install [GitHub CLI](https://cli.github.com/) (`gh`) and authenticate.
+- Ensure PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/) is configured for this repo (`publish.yml` uses the `pypi` GitHub environment).
+
+## Release steps
+
+1. Add user-facing notes under `## [Unreleased]` in `CHANGELOG.md`.
+2. Prepare the release PR:
+
+   ```bash
+   ./scripts/release.sh prepare patch   # or minor | major | 1.2.3
+   ```
+
+3. Merge the PR after CI passes (including the changelog check).
+4. Publish from a clean default branch checkout:
+
+   ```bash
+   git checkout main   # or master for hotdata-marimo
+   git pull
+   ./scripts/release.sh publish
+   ```
+
+## What happens automatically
+
+Pushing a `vX.Y.Z` tag triggers two workflows:
+
+| Workflow | Purpose |
+|----------|---------|
+| `publish.yml` | Build wheel/sdist and publish to PyPI |
+| `release.yml` | Create the GitHub Release with notes from `CHANGELOG.md` |
+
+## Enforcement
+
+- **PR check** (`check-release.yml`): if `pyproject.toml` version changes, `CHANGELOG.md` must contain a matching `## [X.Y.Z]` section.
+- **Tag check** (`publish.yml`): the tag (without `v`) must match `[project].version` in `pyproject.toml`.
+- **Publish guard** (`release.sh publish`): refuses to tag if the changelog section is missing.
+
+Together, these make it hard to ship a version without changelog notes or a GitHub Release.

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/hotdata_runtime/__init__.py

@@ -8,6 +8,13 @@ from hotdata_runtime.client import (
     RunHistoryItem,
     from_env,
 )
+from hotdata_runtime.databases import (
+    DEFAULT_SCHEMA,
+    LoadManagedTableResult,
+    ManagedDatabase,
+    ManagedTable,
+    is_parquet_path,
+)
 from hotdata_runtime.env import (
     default_api_key,
     default_host,
@@ -29,8 +36,13 @@ except PackageNotFoundError:
 
 __all__ = [
     "__version__",
+    "DEFAULT_SCHEMA",
     "HotdataClient",
+    "LoadManagedTableResult",
+    "ManagedDatabase",
+    "ManagedTable",
     "QueryResult",
+    "is_parquet_path",
     "workspace_health_lines",
     "default_api_key",
     "default_host",

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/hotdata_runtime/client.py

@@ -9,12 +9,18 @@ from urllib3.exceptions import ProtocolError
 
 from hotdata import ApiClient, Configuration
 from hotdata.api.connections_api import ConnectionsApi
+from hotdata.api.databases_api import DatabasesApi
 from hotdata.api.information_schema_api import InformationSchemaApi
 from hotdata.api.query_api import QueryApi
 from hotdata.api.query_runs_api import QueryRunsApi
 from hotdata.api.results_api import ResultsApi
+from hotdata.api.uploads_api import UploadsApi
 from hotdata.exceptions import ApiException
 from hotdata.models.async_query_response import AsyncQueryResponse
+from hotdata.models.create_database_request import CreateDatabaseRequest
+from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDecl
+from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
+from hotdata.models.load_managed_table_request import LoadManagedTableRequest
 from hotdata.models.query_request import QueryRequest
 from hotdata.models.query_response import QueryResponse
 from hotdata.models.table_info import TableInfo
@@ -26,6 +32,15 @@ from hotdata_runtime.env import (
     normalize_host,
     pick_workspace,
 )
+from hotdata_runtime.databases import (
+    DEFAULT_SCHEMA,
+    LoadManagedTableResult,
+    ManagedDatabase,
+    ManagedTable,
+    api_error_message,
+    is_parquet_path,
+    managed_database_from_detail,
+)
 from hotdata_runtime.http import default_http_retries
 from hotdata_runtime.result import QueryResult
 
@@ -117,6 +132,9 @@ class HotdataClient:
     def connections(self) -> ConnectionsApi:
         return ConnectionsApi(self._api)
 
+    def _databases_api(self) -> DatabasesApi:
+        return DatabasesApi(self._api)
+
     def _information_schema(self) -> InformationSchemaApi:
         return InformationSchemaApi(self._api)
 
@@ -135,6 +153,168 @@ class HotdataClient:
     def results(self) -> ResultsApi:
         return self._results_api()
 
+    def uploads(self) -> UploadsApi:
+        return UploadsApi(self._api)
+
+    def list_managed_databases(self) -> list[ManagedDatabase]:
+        listing = self._databases_api().list_databases()
+        result: list[ManagedDatabase] = []
+        for summary in listing.databases:
+            try:
+                detail = self._databases_api().get_database(summary.id)
+                result.append(managed_database_from_detail(detail))
+            except ApiException:
+                pass
+        return result
+
+    def resolve_managed_database(self, name_or_id: str) -> ManagedDatabase:
+        # Try direct ID lookup first
+        try:
+            detail = self._databases_api().get_database(name_or_id)
+            return managed_database_from_detail(detail)
+        except ApiException as e:
+            if e.status != 404:
+                raise RuntimeError(api_error_message(e)) from e
+
+        # Fall back to description-based lookup
+        listing = self._databases_api().list_databases()
+        match_id: str | None = None
+        for db in listing.databases:
+            if db.description == name_or_id:
+                match_id = db.id
+                break
+        if match_id is None:
+            raise KeyError(f"No database named or with id {name_or_id!r}")
+        try:
+            detail = self._databases_api().get_database(match_id)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return managed_database_from_detail(detail)
+
+    def create_managed_database(
+        self,
+        description: str | None = None,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+        tables: list[str] | None = None,
+        expires_at: str | None = None,
+    ) -> ManagedDatabase:
+        schemas = None
+        if tables:
+            schemas = [
+                DatabaseDefaultSchemaDecl(
+                    name=schema,
+                    tables=[DatabaseDefaultTableDecl(name=t) for t in tables],
+                )
+            ]
+        request = CreateDatabaseRequest(
+            description=description,
+            schemas=schemas,
+            expires_at=expires_at,
+        )
+        try:
+            created = self._databases_api().create_database(request)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return managed_database_from_detail(created)
+
+    def delete_managed_database(self, name_or_id: str) -> None:
+        db = self.resolve_managed_database(name_or_id)
+        try:
+            self._databases_api().delete_database(db.id)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+
+    def list_managed_tables(
+        self,
+        database: str,
+        *,
+        schema: str | None = None,
+    ) -> list[ManagedTable]:
+        db = self.resolve_managed_database(database)
+        rows: list[ManagedTable] = []
+        for t in self.iter_tables(connection_id=db.default_connection_id):
+            if schema is not None and t.var_schema != schema:
+                continue
+            rows.append(
+                ManagedTable(
+                    full_name=f"{db.id}.{t.var_schema}.{t.table}",
+                    schema=t.var_schema,
+                    table=t.table,
+                    synced=t.synced,
+                    last_sync=t.last_sync,
+                )
+            )
+        rows.sort(key=lambda row: (row.schema, row.table))
+        return rows
+
+    def upload_parquet(self, path: str) -> str:
+        if not is_parquet_path(path):
+            raise ValueError(
+                f"Managed table loads require a parquet file (got {path!r})"
+            )
+        with open(path, "rb") as f:
+            data = f.read()
+        try:
+            uploaded = self.uploads().upload_file(
+                data,
+                _content_type="application/octet-stream",
+            )
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return uploaded.id
+
+    def load_managed_table(
+        self,
+        database: str,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+        upload_id: str | None = None,
+        file: str | None = None,
+    ) -> LoadManagedTableResult:
+        if (upload_id is None) == (file is None):
+            raise ValueError("Exactly one of upload_id or file is required")
+        db = self.resolve_managed_database(database)
+        if upload_id is not None:
+            resolved_upload_id = upload_id
+        else:
+            assert file is not None
+            resolved_upload_id = self.upload_parquet(file)
+        request = LoadManagedTableRequest(
+            mode="replace",
+            upload_id=resolved_upload_id,
+        )
+        try:
+            loaded = self.connections().load_managed_table(
+                db.default_connection_id,
+                schema,
+                table,
+                request,
+            )
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return LoadManagedTableResult(
+            connection_id=loaded.connection_id,
+            schema_name=loaded.schema_name,
+            table_name=loaded.table_name,
+            row_count=loaded.row_count,
+            full_name=f"{db.id}.{loaded.schema_name}.{loaded.table_name}",
+        )
+
+    def delete_managed_table(
+        self,
+        database: str,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+    ) -> None:
+        db = self.resolve_managed_database(database)
+        try:
+            self.connections().delete_managed_table(db.default_connection_id, schema, table)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+
     def list_recent_results(
         self,
         *,

hotdata_runtime-0.2.0/hotdata_runtime/databases.py

@@ -0,0 +1,61 @@
+"""Managed database helpers (Hotdata-owned catalogs with parquet table loads)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from hotdata.exceptions import ApiException
+
+DEFAULT_SCHEMA = "public"
+
+
+@dataclass(frozen=True)
+class ManagedDatabase:
+    id: str
+    description: str | None
+    default_connection_id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ManagedTable:
+    full_name: str
+    schema: str
+    table: str
+    synced: bool
+    last_sync: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class LoadManagedTableResult:
+    connection_id: str
+    schema_name: str
+    table_name: str
+    row_count: int
+    full_name: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def is_parquet_path(path: str) -> bool:
+    return Path(path).suffix.lower() == ".parquet"
+
+
+def managed_database_from_detail(detail: Any) -> ManagedDatabase:
+    return ManagedDatabase(
+        id=str(detail.id),
+        description=detail.description,
+        default_connection_id=str(detail.default_connection_id),
+    )
+
+
+def api_error_message(exc: ApiException) -> str:
+    return exc.reason or str(exc)

{hotdata_runtime-0.1.0 → hotdata_runtime-0.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hotdata-runtime"
-version = "0.1.0"
+version = "0.2.0"
 description = "Workspace/session runtime primitives for Hotdata integrations"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
 dependencies = [
-  "hotdata>=0.1.0",
+  "hotdata>=0.2.3",
   "pandas>=2.0",
 ]
 

hotdata_runtime-0.2.0/scripts/check-release.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Fail CI when pyproject.toml version changes without a matching CHANGELOG entry."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def git_show(path: str, ref: str) -> str:
+    try:
+        return subprocess.check_output(["git", "show", f"{ref}:{path}"], text=True)
+    except subprocess.CalledProcessError:
+        return ""
+
+
+def read_version(text: str) -> str:
+    match = re.search(r'(?m)^version = "([^"]+)"', text)
+    if not match:
+        raise SystemExit("could not read version from pyproject.toml")
+    return match.group(1)
+
+
+def has_changelog_section(version: str) -> bool:
+    changelog = Path("CHANGELOG.md")
+    if not changelog.exists():
+        return False
+    return bool(re.search(rf"^## \[{re.escape(version)}\]", changelog.read_text(), re.M))
+
+
+def main() -> None:
+    base = "origin/main"
+    for candidate in ("origin/main", "origin/master"):
+        if subprocess.call(["git", "rev-parse", "--verify", candidate], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) == 0:
+            base = candidate
+            break
+
+    current = Path("pyproject.toml").read_text()
+    previous = git_show("pyproject.toml", base)
+    if not previous:
+        print("skip: no base pyproject.toml to compare")
+        return
+
+    old_version = read_version(previous)
+    new_version = read_version(current)
+    if old_version == new_version:
+        print(f"version unchanged ({new_version})")
+        return
+
+    if not has_changelog_section(new_version):
+        raise SystemExit(
+            f"pyproject.toml version bumped to {new_version} but CHANGELOG.md "
+            f"has no '## [{new_version}]' section"
+        )
+
+    print(f"release metadata ok for {new_version}")
+
+
+if __name__ == "__main__":
+    main()

hotdata_runtime-0.2.0/scripts/extract-changelog.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Print the Keep a Changelog section for a release version."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+def extract(changelog: str, version: str) -> str:
+    pattern = rf"^## \[{re.escape(version)}\].*$"
+    match = re.search(pattern, changelog, re.M)
+    if not match:
+        raise SystemExit(f"no changelog section for {version}")
+
+    start = match.start()
+    rest = changelog[match.end() :]
+    next_heading = re.search(r"^## \[", rest, re.M)
+    end = match.end() + (next_heading.start() if next_heading else len(rest))
+    section = changelog[start:end].strip()
+    title, _, body = section.partition("\n")
+    return body.strip() or f"Release {version}."
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        raise SystemExit("usage: extract-changelog.py VERSION")
+
+    version = sys.argv[1]
+    changelog = Path("CHANGELOG.md").read_text()
+    print(extract(changelog, version))
+
+
+if __name__ == "__main__":
+    main()