Skip to content

Compound workflows

A compound is one Python method that orchestrates a multi-call REST saga internally, with rollback discipline on partial failure. Compounds are the single biggest reason this SDK exists — they replace the hand-rolled try / except / rollback loops the JS reference client makes you script.

The shape

Every compound:

  1. Runs the steps of the saga sequentially.
  2. On a step failure, attempts to roll back anything it created.
  3. Raises PartialFailureError carrying step="..." so the caller knows exactly where it broke.
from rtls_sdk import PartialFailureError

try:
    tag = client.tags.create(name=..., attached_zone=...)
except PartialFailureError as exc:
    log.warning("compound failed at step=%s: %s", exc.step, exc)
    raise

The step string is part of the SDK's stable contract — a refactor inside the SDK does not change the names callers observe.

Where compounds live

Each compound is documented on its entity page, with the saga's ordered steps and the step strings the SDK emits on failure:

  • Tags — tags.create / update / delete.
  • Users — users.create / update with project_role.
  • Zones — dynamic-zone re-binding on create / update / delete.
  • Nodes — nodes.release with cross-scope override.
  • Groups — groups.delete cascade.

When to drop down

If you need to drive the saga yourself — to recover from a specific mid-step state, to interleave with custom logic, or to hit a rare server quirk — fall back to the *_raw methods. See raw REST methods.

Why not handle every error inside the SDK?

Two reasons:

  1. The caller's idea of "acceptable behaviour" varies. A retry that's safe for a script run by an operator may be dangerous in an automated pipeline. The SDK surfaces; the caller decides.
  2. Half-completed state is information. PartialFailureError carries completed_steps and partial_result so a retry can resume from the right point — that's only possible if the SDK exposes the partial state rather than swallowing it.