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.3.tar.gz (238.0 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.3-py3-none-any.whl (239.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: rocky_sdk-0.8.3.tar.gz
  • Upload date:
  • Size: 238.0 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.3.tar.gz
Algorithm Hash digest
SHA256 4112f51a6490a883bdd592c96f7df7c86956eb994c5a6d9b94d94bac8ffa1e46
MD5 5022b78ddf061712006ffb1994d0f986
BLAKE2b-256 95fd7dd7997cd6ce9c16b8b2518a567f68424de74681cbe5eb68e6de770cebd3

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: rocky_sdk-0.8.3-py3-none-any.whl
  • Upload date:
  • Size: 239.9 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.3-py3-none-any.whl
Algorithm Hash digest
SHA256 fe902b6e035ca66bb543d84d1675cd5493211ef0fc7619259edceafb59f9298f
MD5 5e8b6a3d9e90dc3fc7eb893946cf8547
BLAKE2b-256 d0838154ade916ebe619052044633ed7a644d88827c295480d84398adfed9f95

See more details on using hashes here.

Provenance

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