GetRatchet Python SDK

Install with pip install getratchet. For local development, use pip install ./python. The package uses only the Python standard library and supports Python 3.10+.

from getratchet import Ratchet

ratchet = Ratchet("https://getratchet.waelfz.com", "YOUR_PRODUCER_API_KEY")
run_id = ratchet.start_run("customer-onboarding", project_id="YOUR_PROJECT_ID", environment_id="YOUR_ENVIRONMENT_ID")
job = ratchet.enqueue(
    "send_welcome_email", "1", {"customerId": "cus_42"},
    idempotency_key="welcome:cus_42",
)
ratchet.finish_run()
print(run_id, job["stepId"])

Run a separate, long-lived worker process with a WORKER scoped API key. Register handlers before starting the worker. Restarting a worker registers it again; leased jobs return to the queue after the lease expires. Register the exact version used by queued jobs.

from getratchet import Ratchet

worker = Ratchet("https://getratchet.waelfz.com", "YOUR_WORKER_API_KEY")

def send_welcome(payload, context):
    context.check_cancelled()
    # Pass context.idempotency_key to the mail/payment provider if it supports one.
    return {"providerMessageId": send_mail(payload, idempotency_key=context.idempotency_key)}

worker.register_tool("send_welcome_email", "1", send_welcome)
worker.worker.start(concurrency=4)

Use worker.worker.stop() for graceful shutdown. Handlers should call context.check_cancelled() around expensive or irreversible operations. Python cannot forcibly terminate a running thread; a handler that blocks forever also blocks worker shutdown. Set explicit timeouts on downstream network calls. A failure between an external side effect and the job report can repeat that effect, so pass the stable idempotency key to the destination service or record it there. Raising NonRetryableError prevents another attempt; other handler errors are retried under the endpoint policy.

Use ratchet.replay_preview(step_id) to review replay risk before calling ratchet.replay(step_id, reason=...). Replay can run an irreversible action again and should use a fresh destination-side deduplication decision.

Pass after_step_id=primary["stepId"], after_status="FAILED" to enqueue for a fallback, or after_status="SUCCEEDED" for a follow-up. Enqueue dependencies before finish_run(). Independent calls may run in parallel. Unused branches are marked SKIPPED without invoking a handler.