rocky-sdk

A typed Python client for the Rocky SQL transformation engine.

rocky-sdk wraps the rocky CLI binary (subprocess + --output json) behind a typed RockyClient. Each method builds the right argv, runs the binary, parses the JSON output, and returns a Pydantic model. Failures surface as RockyError subclasses carrying structured fields (exit code, stderr tail, version strings) rather than opaque messages.

It is for human Python callers: notebooks, scripts, and orchestrators. The dagster-rocky integration is a thin Dagster adapter built on this client. For AI agents, use rocky mcp; for a language-agnostic HTTP surface, use rocky serve.

Install

pip install rocky-sdk

The rocky binary is not bundled. Install it separately and put it on $PATH (or pass binary_path=). See the releases page. The SDK requires engine v1.34.0 or newer.

Usage

from rocky_sdk import RockyClient

client = RockyClient(config_path="rocky.toml")

# Read-only inspection — all return typed Pydantic models
result = client.compile()
for diag in result.diagnostics:
    print(diag.severity, diag.message)

lineage = client.lineage("customer_orders", column="email")
catalog = client.catalog()

# Execute a pipeline; stream live progress to a callback
run = client.run(filter="tenant=acme", log_callback=print)
print(run.summary)

Errors

from rocky_sdk import RockyClient
from rocky_sdk.exceptions import RockyVersionError, RockyCommandError, RockyTimeoutError

client = RockyClient(config_path="rocky.toml", timeout_seconds=600)
try:
    client.run(filter="tenant=acme")
except RockyTimeoutError as exc:
    print("timed out after", exc.timeout_seconds, "s")
    print(exc.stderr_tail)
except RockyCommandError as exc:
    print("exit", exc.returncode)
    print(exc.stderr_tail)

RockyError is the base of the hierarchy:

Exception Raised when
RockyBinaryNotFoundError the rocky binary is missing
RockyVersionError the binary is older than the SDK's minimum
RockyTimeoutError a command exceeds timeout_seconds
RockyCommandError a command exits non-zero
RockyPartialFailure a non-zero run still returned a parseable partial result (only with allow_partial=False)
RockyOutputParseError stdout was not the expected JSON shape
RockyServerError a rocky serve HTTP request failed
RockyGovernanceError a governance_override would silently full-revoke

Example

A runnable end-to-end script lives at examples/quickstart.py. With the rocky binary on your PATH:

python examples/quickstart.py

It spins up a throwaway DuckDB playground (no credentials) and walks through compile, DAG, lineage, a real run, and typed error handling.

License

Apache-2.0

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.10.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rocky-data from gravatar.com rocky-data

Credits

Author: Hugo Correia

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Tags

client data-engineering rocky sdk sql transformation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rocky_sdk-0.8.2.tar.gz (236.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

rocky_sdk-0.8.2-py3-none-any.whl (239.5 kB view details)

Uploaded Python 3

File details

Details for the file rocky_sdk-0.8.2.tar.gz.

File metadata

  • Download URL: rocky_sdk-0.8.2.tar.gz
  • Upload date:
  • Size: 236.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for rocky_sdk-0.8.2.tar.gz
Algorithm Hash digest
SHA256 9fc96ec7648def8486e9dd76c5aee95af31edde38cdb78cd6bce4fb4dd6e0a46
MD5 4cdc050cc369a69053157237801e87e1
BLAKE2b-256 a4b02a2303888aadceaad1e8c008a34c789e4ac1593252d46218f45f5d361d7e

See more details on using hashes here.

Provenance

The following attestation bundles were made for rocky_sdk-0.8.2.tar.gz:

Publisher: sdk-release.yml on rocky-data/rocky

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rocky_sdk-0.8.2-py3-none-any.whl.

File metadata

  • Download URL: rocky_sdk-0.8.2-py3-none-any.whl
  • Upload date:
  • Size: 239.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for rocky_sdk-0.8.2-py3-none-any.whl
Algorithm Hash digest
SHA256 2f0767e4f874421c655538d23ad1de11a88e5b264b528ab780a92c32d1c46d8b
MD5 159c545475935de900bf765f1a82f00c
BLAKE2b-256 8ad7d3c2f81fcb5d60310dbef15b194b163f0a3372f898ba59ac7bdebc3b0648

See more details on using hashes here.

Provenance

The following attestation bundles were made for rocky_sdk-0.8.2-py3-none-any.whl:

Publisher: sdk-release.yml on rocky-data/rocky

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page