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.1.tar.gz (235.9 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.1-py3-none-any.whl (239.4 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: rocky_sdk-0.8.1.tar.gz
  • Upload date:
  • Size: 235.9 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.1.tar.gz
Algorithm Hash digest
SHA256 65842c736ad49cc5ab682aded321319a8fc1506e7db095fb99f0f182ca2d7d03
MD5 b48b0fdcdd534d8b58ad79943af299d4
BLAKE2b-256 543087eb8db44200f623b15c1243433dd9ff62113191885b4ad98a543c62bc58

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: rocky_sdk-0.8.1-py3-none-any.whl
  • Upload date:
  • Size: 239.4 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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 fc9d2aaf77b6b222ff93ceb844a39e116b3bbb603114b0c552450f4ff306433d
MD5 d6a9ac48b229673f4577ac04419892a1
BLAKE2b-256 fe9cb9a6a5fe029e6d64b7a4274c9b764d111f195f9e510996bf1616325d456b

See more details on using hashes here.

Provenance

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