hotdata-framework 0.4.0__tar.gz

hotdata_framework-0.4.0/.github/dependabot.yml

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

hotdata_framework-0.4.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_framework-0.4.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_framework-0.4.0/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,17 @@
+name: Dependabot auto-merge
+
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Enable auto-merge
+        run: gh pr merge --squash --auto "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

hotdata_framework-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+concurrency:
+  group: pypi-publish-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - 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 [[ ! "$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
+          fi
+          tag="${GITHUB_REF_NAME#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/
+
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

hotdata_framework-0.4.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@da05d552573ad5aba039eaac05058a918a7bf631 # 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_framework-0.4.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing / coverage
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+.DS_Store

hotdata_framework-0.4.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# 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.4.0] - 2026-06-26
+
+### Changed
+
+- **Renamed the distribution from `hotdata-runtime` to `hotdata-framework`** and the import package from `hotdata_runtime` to `hotdata_framework`. Consumers should depend on `hotdata-framework` and use `import hotdata_framework`. The GitHub repository is now `sdk-python-framework`.
+- Added PyPI classifiers, keywords, and an updated description identifying the project as a Python framework.
+
+## [0.3.0] - 2026-06-22
+
+### Added
+
+- Adopt the `hotdata` 0.4.1 SDK surface.
+- New typed error-handling public API: `HotdataError`, `HotdataTerminalError`, `HotdataTransientError`, and `classify_sdk_error` (`hotdata_framework/errors.py`).
+- `ManagedDatabaseClient` for managed database operations (`hotdata_framework/managed_client.py`).
+- `py.typed` marker so downstream consumers pick up inline type information.
+
+### Changed
+
+- Bump the `hotdata` dependency pin to `>=0.4.1`.
+- Add ruff and mypy tooling configuration and dev dependencies (`ruff>=0.5`, `mypy>=1.5`); apply ruff lint/format cleanup across the package.
+
+
+## [0.2.4] - 2026-06-01
+
+### Changed
+
+- Release 0.2.4
+
+## [0.2.3] - 2026-05-27
+
+### Changed
+
+- Release 0.2.3
+
+## [0.2.2] - 2026-05-27
+
+### Changed
+
+- Release 0.2.2
+
+## [0.2.1] - 2026-05-24
+
+### Added
+
+- `execute_sql` accepts an optional `database` keyword argument. When provided, the database name is resolved to an ID and sent as the `X-Database-Id` header so SQL can reference managed database tables as `"default"."<schema>"."<table>"`. Behaviour is unchanged when `database` is omitted.
+
+## [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_framework-0.4.0/CONTRACT.md

@@ -0,0 +1,106 @@
+# hotdata-framework Contract
+
+`hotdata-framework` is the framework-agnostic runtime contract for Hotdata integrations.
+
+## Scope
+
+This package provides shared primitives for:
+
+- Environment and workspace resolution
+- Query execution and polling
+- Normalized tabular result handling
+- Basic workspace health checks
+
+## Public Runtime Contract
+
+The supported import surface is:
+
+- `HotdataClient`
+- `QueryResult`
+- `from_env`
+- `workspace_health_lines`
+- `default_api_key`
+- `default_host`
+- `default_session_id`
+- `explicit_workspace_id`
+- `list_workspaces`
+- `normalize_host`
+- `pick_workspace`
+- `resolve_workspace_selection`
+- `ResultSummary`
+- `RunHistoryItem`
+- `WorkspaceSelection`
+- `ManagedDatabase`
+- `ManagedTable`
+- `LoadManagedTableResult`
+- `DEFAULT_SCHEMA`
+- `is_parquet_path`
+
+Adapters should import from `hotdata_framework` and treat this surface as the stable API.
+
+## Semantic Guarantees
+
+### `HotdataClient`
+
+- Represents runtime context: API key, host, workspace, optional session.
+- `from_env()` resolves runtime context from env vars and selected workspace.
+- `execute_sql(sql)` returns `QueryResult` or raises `RuntimeError`/`TimeoutError`.
+- `get_result(result_id)` returns a ready `QueryResult` and waits for readiness when needed.
+- `connections()` returns the connections API wrapper for adapter UI/status features.
+- `query_runs()` returns the query-runs API wrapper for adapter history views.
+- `results()` returns the results API wrapper for adapter result pickers.
+- `list_recent_results(...)` returns normalized `ResultSummary` entries.
+- `list_run_history(limit=...)` returns normalized `RunHistoryItem` entries.
+- `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`
+
+- Canonical tabular result model with `columns`, `rows`, and `row_count`.
+- Carries server identifiers and execution metadata when available.
+- `to_pandas()` converts to a DataFrame with stable column ordering.
+- `to_records(max_rows=...)` returns row dicts keyed by column names.
+- `metadata_dict()` returns normalized result metadata for adapter rendering.
+
+### Env Resolution
+
+- `default_api_key()` reads `HOTDATA_API_KEY`.
+- `default_host()` reads `HOTDATA_API_URL` (default: `https://api.hotdata.dev`) and normalizes it.
+- `default_session_id()` reads `HOTDATA_SANDBOX`.
+- `explicit_workspace_id()` reads `HOTDATA_WORKSPACE` (workspace public id).
+- `pick_workspace()` prefers explicit env workspace, then active workspace, then first workspace.
+- `resolve_workspace_selection()` is the canonical workspace selection algorithm. It returns `WorkspaceSelection` with selected workspace id, selection source, and discovered workspaces when auto-selected.
+
+## Adapter Responsibilities
+
+Framework packages (Jupyter, Marimo, LangChain, LangGraph, LlamaIndex, Streamlit) own:
+
+- Framework-native lifecycle and state management
+- Rendering/UI concerns
+- Tool/agent wrappers and callback integration
+
+They should not duplicate runtime env/workspace/query semantics.
+
+## Runtime Non-Goals
+
+`hotdata-framework` does not define framework UI primitives and does not require framework dependencies.
+
+## Versioning Policy
+
+- Backward-incompatible contract changes require a major version bump.
+- Additive contract changes are minor versions.
+- Bug fixes that preserve contract semantics are patch versions.
+
+## Enforcement
+
+Contract stability is enforced by tests that verify the public export surface and key behavioral invariants.

hotdata_framework-0.4.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: hotdata-framework
+Version: 0.4.0
+Summary: Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases
+Project-URL: Homepage, https://www.hotdata.dev
+Project-URL: Documentation, https://www.hotdata.dev/docs
+Project-URL: Repository, https://github.com/hotdata-dev/sdk-python-framework
+License: MIT
+Keywords: analytics,arrow,data,framework,hotdata,pandas,python,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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.4.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Description-Content-Type: text/markdown
+
+# hotdata-framework
+
+**A Python framework for building Hotdata integrations.**
+
+Shared runtime primitives for Hotdata integrations: workspace/session semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.
+
+Runtime boundary and guarantees are defined in `CONTRACT.md`.
+
+## Features
+
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, `HOTDATA_WORKSPACE`, and `HOTDATA_SANDBOX`.
+- **Workspace resolution** — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
+- **Sandbox/session propagation** — pass sandbox session context through the SDK via `X-Session-Id`.
+- **HTTP resilience** — configure SDK retries for transient connection failures and retry SQL execution on stale pooled sockets.
+- **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:
+
+```bash
+uv pip install hotdata-framework
+# or: pip install hotdata-framework
+```
+
+Example:
+
+```bash
+python examples/basic_usage.py
+```
+
+Development (uses **uv**; creates `.venv/` in this repo):
+
+```bash
+uv sync --locked
+uv run pytest
+```
+
+`uv.lock` is checked in so CI can run `uv sync --locked`. The default **dev** group (pytest) is enabled via `[tool.uv] default-groups`.

hotdata_framework-0.4.0/README.md

@@ -0,0 +1,41 @@
+# hotdata-framework
+
+**A Python framework for building Hotdata integrations.**
+
+Shared runtime primitives for Hotdata integrations: workspace/session semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.
+
+Runtime boundary and guarantees are defined in `CONTRACT.md`.
+
+## Features
+
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, `HOTDATA_WORKSPACE`, and `HOTDATA_SANDBOX`.
+- **Workspace resolution** — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
+- **Sandbox/session propagation** — pass sandbox session context through the SDK via `X-Session-Id`.
+- **HTTP resilience** — configure SDK retries for transient connection failures and retry SQL execution on stale pooled sockets.
+- **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:
+
+```bash
+uv pip install hotdata-framework
+# or: pip install hotdata-framework
+```
+
+Example:
+
+```bash
+python examples/basic_usage.py
+```
+
+Development (uses **uv**; creates `.venv/` in this repo):
+
+```bash
+uv sync --locked
+uv run pytest
+```
+
+`uv.lock` is checked in so CI can run `uv sync --locked`. The default **dev** group (pytest) is enabled via `[tool.uv] default-groups`.

hotdata_framework-0.4.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_framework-0.4.0/examples/basic_usage.py

@@ -0,0 +1,25 @@
+"""Basic hotdata-framework usage."""
+
+from hotdata_framework import from_env
+
+
+def main() -> None:
+    client = from_env()
+    result = client.execute_sql("SELECT 1 AS ok")
+
+    print("result metadata:", result.metadata_dict())
+    print("records:", result.to_records(max_rows=5))
+
+    print("recent results:")
+    for item in client.list_recent_results(limit=5, offset=0):
+        print(item.to_dict())
+
+    print("run history:")
+    for item in client.list_run_history(limit=5):
+        print(item.to_dict())
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()