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.7.0.tar.gz (234.3 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.7.0-py3-none-any.whl (239.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: rocky_sdk-0.7.0.tar.gz
  • Upload date:
  • Size: 234.3 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.7.0.tar.gz
Algorithm Hash digest
SHA256 e346cf997dbd9d4318cbee649f911c74bdd1f5dde8f3b31a2b5de85cefbca904
MD5 80971d6dcd1276900f45c57e9be009e6
BLAKE2b-256 84d2f3091e9c472b91e41e8288a44393e5425c5e96c879e342e39545ca275b44

See more details on using hashes here.

Provenance

The following attestation bundles were made for rocky_sdk-0.7.0.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.7.0-py3-none-any.whl.

File metadata

  • Download URL: rocky_sdk-0.7.0-py3-none-any.whl
  • Upload date:
  • Size: 239.2 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.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 392b66c0f872ea4ea8c36efcedb6c78f3fc3e154ed014f5299d8b464e0379612
MD5 eeefc3f9747d4d741b27b090d2ba743f
BLAKE2b-256 48492b4a8d182aa691c7ff07ac787fa23d4c5977085f08a1bc32ca67d44c75f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for rocky_sdk-0.7.0-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