Skip to main content

Client

This article refers to SDK version v0.5.0. The current SDK version is N/A.

BarbaraClient and AsyncBarbaraClient are the SDK's entry points: every other resource (.nodes, .clusters, .applications, ...) hangs off an instance of one of these two. See the Overview for narrative examples, and Authenticate in the Getting started guide for how to build one.

BarbaraClient​

BarbaraClient(
    config: BarbaraConfig,
    *,
    timeout: float = 30.0,
    http2: bool = False,
    max_retries: int = 0,
)

Synchronous client. Use as a context manager to close the underlying session.

Not thread-safe: a single instance shares one mutable token cache (~barbara.auth.TokenManager) with no locking, by design (kept simple) — two threads racing a token refresh on the same instance can both issue a fetch. Create one client per thread, or add your own locking around calls, if you're using real threads (this does not apply to asyncio/AsyncBarbaraClient, which is single-threaded by nature).

Example:

with BarbaraClient.from_env() as client:
    nodes = client.nodes.list()

http2 requires the optional h2 dependency (pip install barbara-api-sdk[http2]) — mainly useful if you issue many concurrent requests (see AsyncBarbaraClient with asyncio.gather), since it lets them multiplex over one connection instead of opening several; negligible benefit for purely sequential calls. max_retries (default 0, i.e. no change from prior behavior) retries a request that fails with a connection error or a 429/502/503/504 response, with exponential backoff (honoring Retry-After on a 429) — does not apply to the existing single 401-retry-with-fresh-token behavior below, which is unconditional.

request​

request(method: str, path: str, **kwargs: Any) -> Any

Issue an authenticated request, retrying once on a 401 with a fresh token (always), plus — if max_retries was set on this client — retrying a connection error or a 429/502/503/504 response with backoff.

api_version​

api_version() -> Any

close​

close() -> None

AsyncBarbaraClient​

AsyncBarbaraClient(
    config: BarbaraConfig,
    *,
    timeout: float = 30.0,
    http2: bool = False,
    max_retries: int = 0,
)

Async counterpart of BarbaraClient, same resource surface. See http2/max_retries on BarbaraClient.__init__ — same meaning here.

request​

request(method: str, path: str, **kwargs: Any) -> Any

Async counterpart of BarbaraClient.request — same 401-retry-always plus optional transient-error-retry-with-backoff behavior, gated by self.settings.max_retries.

api_version​

api_version() -> Any

close​

close() -> None

Signatures above are generated from barbara-api-sdk 0.5.0 docstrings. If a new SDK release changes one, this page needs a re-sync — the surrounding prose does not update itself.