Metadata-Version: 2.4
Name: getratchet
Version: 0.1.0
Summary: Python producer and worker SDK for GetRatchet
License: MIT
Project-URL: Homepage, https://github.com/wauul/getratchet
Project-URL: Documentation, https://github.com/wauul/getratchet/blob/main/python/README.md
Project-URL: Issues, https://github.com/wauul/getratchet/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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+.

```python
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.

```python
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.
