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
1 maintainer
Release files for rocky-sdk 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rocky_sdk-0.11.0.tar.gz | 253.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| rocky_sdk-0.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 507.6 kB
Release files / rocky_sdk-0.11.0.tar.gz
| Download URL | rocky_sdk-0.11.0.tar.gz |
|---|---|
| Size | 253.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ed5982926dde59f2e9a056f15686a2c28c9db6aa2d0ac5382331e5105668203
|
|
BLAKE2b-256 checksum How to use checksums |
7da71cb1f1528051f250229c2f6f54f5da01386324a9b67ba9c9f3234ad19bd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.
Transparency logRelease files / rocky_sdk-0.11.0-py3-none-any.whl
| Download URL | rocky_sdk-0.11.0-py3-none-any.whl |
|---|---|
| Size | 254.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
86ac6ac7b73987c10ed90e1bbeb524b00163db92e2f61a6c77d1ea8dd9c83f1a
|
|
BLAKE2b-256 checksum How to use checksums |
7405f2a96970450c08927acee49d5c5d11db44b07d73639f83710e87a9e02515
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.
Transparency log
