Client

New to the SDK? Getting started shows how to connect and use it.

Connecting

connect()

connect(
    *,
    token: str | None = None,
    credentials: Credentials | None = None,
    base_url: str = 'https://api.dlthub.com',
    organization_id: str | None = None,
    verify_ssl: bool = True,
    headers: Mapping[str, str] | None = None,
) -> Runtime[Sync]

Connect to the platform for blocking use.

Arguments

Name	Type	Description
token	str | None	An API key (dlt_u_/dlt_sa_ prefixed) or a user JWT, when the credential does not change. A JWT is not renewed, so a long-lived client should hold an API key or pass credentials.
credentials	Credentials | None	Where to read the credential before each request, for one that rotates. Renewed once if the platform rejects it. Exactly one of this and token is required.
base_url	str	Platform base URL. Override for local or staging.
organization_id	str | None	Default organization, so workspaces.list() needs no argument.
verify_ssl	bool	Verify the platform's TLS certificate. Applies on both planes.
headers	Mapping[str, str] | None	Sent with every request, on both planes.

Returns: Runtime[Sync] — A blocking Runtime.

Raises

Exception	When
ValueError	Both token and credentials, or neither.

connect_async()

connect_async(
    *,
    token: str | None = None,
    credentials: AsyncCredentials | None = None,
    base_url: str = 'https://api.dlthub.com',
    organization_id: str | None = None,
    verify_ssl: bool = True,
    headers: Mapping[str, str] | None = None,
) -> Runtime[Async]

Connect to the platform for awaited use.

Arguments

Name	Type	Description
token	str | None	As for connect().
credentials	AsyncCredentials | None	As for connect(), awaited.
base_url	str	Platform base URL. Override for local or staging.
organization_id	str | None	Default organization, so workspaces.list() needs no argument.
verify_ssl	bool	As for connect().
headers	Mapping[str, str] | None	As for connect().

Returns: Runtime[Async] — An awaiting Runtime.

Raises

Exception	When
ValueError	As for connect().

Runtime

Runtime

Entry point to the platform.

Build one with dlthub_sdk.connect() or dlthub_sdk.connect_async(); M records which, so every object reached from it stays in the same mode.

Usable as a context manager (with dlthub_sdk.connect(...) as runtime:), which closes it on the way out.

A runtime from connect_async needs async with; plain with raises TypeError.

Collections

Name	Type	Example	Description
runtime.organizations	Organizations	runtime.organizations.list()	Organization lookup.
runtime.dataplanes	Dataplanes	runtime.dataplanes.list()	The data planes a workspace can be placed on.
runtime.workspaces	Workspaces	runtime.workspaces.list()	Workspace lookup.

Runtime.me()

me() -> Caller

Return the person this token belongs to.

Works with a user token or a user API key. A service-account API key or a platform run's identity is refused; Organization.me() and Workspace.me() answer for those too.

Not side-effect free: it accepts the person's pending invitations, and on their first call creates a personal organization and playground workspace.

Returns: Caller — The caller, with every organization they belong to; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotAuthenticated	The token is missing, malformed, or rejected.

Runtime.close()

close() -> Any

Release the connections held for this client.

Anything reached from it — a workspace, a job, a collection — shares those connections, so close only when done with all of them. Calls after close raise RuntimeError.

Returns: Any — None; awaitable in async mode.

Credentials

AsyncCredentials

The awaited twin of Credentials, for connect_async.

AsyncCredentials.token()

token() -> str

Return the credential to send now.

Returns: str — The bearer token.

AsyncCredentials.refreshed()

refreshed() -> str | None

Renew the credential after the platform rejected it.

Returns: str | None — A token to retry with, or None to give up.

Credentials

A control-plane credential the SDK reads before each request.

Implement this for a credential that changes over the client's life. The SDK never stores what token() returns, so a rotation takes effect on the next request.

Credentials.token()

token() -> str

Return the credential to send now.

Called before every control-plane request, so an implementation that renews proactively does it here.

Returns: str — The bearer token.

Credentials.refreshed()

refreshed() -> str | None

Renew the credential after the platform rejected it.

Called at most once per request, only for a 401. Returning None makes the rejection final and the caller sees NotAuthenticated.

Returns: str | None — A token to retry with, or None to give up.

Conventions

Update methods leave a field as it is when you pass KEEP, the default of every optional update argument, clear it when you pass None and set it when you pass a value.

Async

Async = Literal['async']

Mode of a client from connect_async(), as in Runtime[Async].

Calls return awaitables and listings return async iterables.

KEEP

KEEP = _Keep.KEEP

Leave this field as it is: the default of every optional update argument.

Pass None to clear a field instead.

Keep

Keep = Literal[_Keep.KEEP]

The type of KEEP, for annotating an update argument: str | None | Keep.

Sync

Sync = Literal['sync']

Mode of a client from connect(), as in Runtime[Sync].

Calls return values and listings return iterables.