Client and integration runs

OblidogClient

Bases: OblidogClient

High-level Oblidog API client with resilient transport handling.

Read-only requests (GET, HEAD, and OPTIONS) retry transient transport failures and HTTP 502, 503, and 504 responses according to retry_policy. Mutating requests are never automatically replayed because the server may have applied a change before the client observed a transport failure.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the Oblidog API.	required
api_key	str	Integration API key used for authentication.	required
timeout	float	Request timeout in seconds.	10.0
retry_policy	RetryPolicy | None	Retry configuration. When omitted, RetryPolicy() is used.	None

Raises:

Type	Description
OblidogConnectionError	When a transport failure cannot be recovered or a retryable server response remains unavailable after all attempts.

RetryPolicy dataclass

Configure retries for transient Oblidog API failures.

Retries are deliberately limited to read-only HTTP methods. Mutating requests are attempted once because a transport failure can happen after the server has already applied the change.

Attributes:

Name	Type	Description
enabled	bool	Whether automatic retries are enabled. Connection failures are still translated to OblidogConnectionError when retries are disabled.
max_attempts	int	Maximum number of attempts, including the initial request. Must be at least 1.
initial_delay	float	Initial backoff delay in seconds before the first retry.
max_delay	float	Maximum delay in seconds between attempts, including jitter.
jitter	float	Maximum random jitter in seconds added to each backoff delay.

IntegrationsClient

Read authenticated integration context and report runs using its API key.

Callers own run IDs and bounded retries. A conflict must never automatically refresh a revision and replay an old invocation.

context()

Return context associated with the authenticated integration API key.

The returned object includes the integration and category selected by the API key. Its current revision is used by :meth:run for optimistic locking.

run()

Fetch context and start a run before synchronization work begins.

The context's current revision is used for optimistic locking. Use the returned object as a context manager and finish it explicitly on the successful path.

Example

with client.integrations.run() as run:
    # synchronize using run.context
    run.finish_success(changes_detected=False)

Raises:

Type	Description
TypeError	If the context does not contain an integration object with an integer revision.
OblidogConflictError	If another worker has changed state first.

start(*, run_id, expected_revision)

Start a run using a caller-provided ID and expected revision.

Prefer :meth:run for normal synchronization. This lower-level method is available when the caller explicitly owns scheduling and retries.

Raises:

Type	Description
OblidogConflictError	If the revision is stale or a run conflicts.
OblidogValidationError	If the request is invalid.

finish(*, run_id, result, changes_detected=None, error=None)

Finish a run using the same ID passed to :meth:start.

changes_detected is required by the protocol as a value but can be None when its value is unknown. For failures, supply a sanitized error and avoid secrets or tracebacks.

Raises:

Type	Description
OblidogConflictError	If the run cannot be completed in its state.
OblidogValidationError	If the completion request is invalid.

IntegrationRun

A started integration run that must be finished exactly once.

Obtain instances with :meth:IntegrationsClient.run and normally use them as context managers. An exception before completion reports a sanitized failure and is then propagated to the caller.

finish_success(*, changes_detected)

Report successful completion.

Parameters:

Name	Type	Description	Default
changes_detected	bool | None	True when this run changed Ledger data, False for a known no-op, or None when unknown.	required

Returns:

Type	Description
IntegrationPublic	The finished integration state.

Raises:

Type	Description
RuntimeError	If this run was already finished.

finish_failure(*, code='provider_failed', message='Provider unavailable')

Report a failure with a sanitized error summary.

Never put credentials, raw provider responses, or tracebacks in message.

IntegrationContextPublic

Attributes:

Name	Type	Description
category	IntegrationContextCategoryPublic
integration	IntegrationContextIntegrationPublic

IntegrationContextIntegrationPublic

Attributes:

Name	Type	Description
enabled	bool
id	UUID
name	str
revision	int

IntegrationContextCategoryPublic

Attributes:

Name	Type	Description
code	str
id	UUID
name	str