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

Uploaded Python 3

File details

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

File metadata

  • Download URL: rocky_sdk-0.8.0.tar.gz
  • Upload date:
  • Size: 235.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.0.tar.gz
Algorithm Hash digest
SHA256 0796265df9b5214d31d71547fa61eca33b4674b7c11415e465ff60c044aa3b98
MD5 81fe723c2556d0b74447344debf5df93
BLAKE2b-256 655fdcc3ec69db21adb4d05a7e5d4f0bcb8c71e2bbcdfeaa996483f632ef0016

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: rocky_sdk-0.8.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.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3b6abe0801914d1407ec76f561327f322e4bd44607ec50491bcf774ae17153ee
MD5 9d20c443307defaf6ce4075c08ad4890
BLAKE2b-256 1f9897824a9b77a2f054d63d88cadb4a5c67bc4a283305432c53478d7cc94ae0

See more details on using hashes here.

Provenance

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