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 failed_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.failed_step, exc)
    raise

The failed_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 failed_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.