Deployments and configurations

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

Deployments

Deployments

The deployments of one workspace.

list() yields the newest version first.

Deployments.upload()

upload(*, code: bytes | BinaryIO, requirements: bytes | BinaryIO) -> Deployment

Store a new version of the workspace's code.

The platform derives the hash, the size and the file list by reading the package. To skip an unchanged upload, compare the hash dlt's package builder returned with latest().content_hash.

Arguments

Name	Type	Description
code	bytes | BinaryIO	A deployment package built by dlt's package builder (a gzipped tar that carries dlt's manifest.yaml), as bytes or a binary file object.
requirements	bytes | BinaryIO	The requirements manifest that goes with it, as bytes or a binary file object. Opaque to the SDK.

Returns: Deployment — The stored deployment, one version above the last; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
DataplaneTokenRejected	The data plane rejected the token the platform issued for it.
InvalidResponse	The platform returned an upload address this SDK version cannot use; upgrade dlthub-client.
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.
TransportError	The upload did not complete. A version is written only once the content arrives, but a request that never produced a response cannot say whether it did — read latest() before retrying.

Deployments.get()

get(*, version: int) -> Deployment

Return one deployment by version.

Arguments

Name	Type	Description
version	int	The version to read, counting up from 1.

Returns: Deployment — The deployment; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace has no such version.
ScopeMissing	Reached without a workspace in scope.

Deployments.latest()

latest() -> Deployment

Return the deployment a run would use now.

Returns: Deployment — The newest version; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace has none yet.
ScopeMissing	Reached without a workspace in scope.

Deployments.count()

count() -> int

Return how many versions the workspace holds.

Returns: int — The count; awaitable in async mode. Saturates at 10,001.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.

Deployments.list()

list(
    *,
    limit: int | None = None,
    offset: int = 0,
) -> Iterable[Deployment] | AsyncIterable[Deployment]

Yield the workspace's deployments, paging lazily.

Arguments

Name	Type	Description
limit	int | None	Return at most this many. None walks to the end, or to row 10,100, past which the platform does not page.
offset	int	Skip this many, server-side.

Returns: Iterable[Deployment] | AsyncIterable[Deployment] — An iterable of deployments; async-iterable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.
ValueError	A negative limit or offset.

Deployment

One uploaded version of a workspace's code.

Attributes

Name	Type	Description
version	int	Version number within the workspace, starting at 1 and incremented by each upload.
id	str	Unique ID (a UUID).
content_hash	str	Hash of the package contents: base64 SHA3-256 over each file's path and digest, as dlt computes when building the package; identical file sets give identical hashes.
file_count	int	Number of files in the package.
size_bytes	int	Size of the uploaded package in bytes.
requirements_size_bytes	int	Size of the uploaded requirements file in bytes.
created_at	datetime	When it was created.
created_by	str	The organization_membership_id of the member who uploaded it.
updated_at	datetime	When it was last changed.

Deployment.files()

files() -> tuple[FileEntry, ...]

List the files this deployment holds.

The manifest is stored with the content rather than with the record, so this is a fresh read every time.

Returns: tuple[FileEntry, ...] — One entry per file, in the platform's order; awaitable in async mode.

Raises

Exception	When
DataplaneTokenRejected	The data plane rejected the token the platform issued for it.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The deployment no longer exists.
ScopeMissing	Reached without a workspace in scope.

Configurations

Configurations

The configurations of one workspace.

list() yields the newest version first.

Configurations.upload()

upload(*, data: bytes | BinaryIO) -> Configuration

Store a new version of the workspace's configuration.

The platform reads the package for the hash, the file list and the profile names. To skip an unchanged upload, compare the hash dlt's package builder returned with latest().content_hash.

Arguments

Name	Type	Description
data	bytes | BinaryIO	A configuration package built by dlt's package builder (a gzipped tar of the .dlt settings folder that carries dlt's manifest.yaml), as bytes or a binary file object.

Returns: Configuration — The stored configuration, one version above the last; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
Conflict	The current state does not allow the call, e.g. the workspace is archived; code and message say why.
DataplaneTokenRejected	The data plane rejected the token the platform issued for it.
InvalidResponse	The platform returned an upload address this SDK version cannot use; upgrade dlthub-client.
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.
TransportError	The upload did not complete. A version is written only once the content arrives, but a request that never produced a response cannot say whether it did — read latest() before retrying.

Configurations.get()

get(*, version: int) -> Configuration

Return one configuration by version.

Arguments

Name	Type	Description
version	int	The version to read, counting up from 1.

Returns: Configuration — The configuration; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace has no such version.
ScopeMissing	Reached without a workspace in scope.

Configurations.latest()

latest() -> Configuration

Return the configuration a run would use now.

Returns: Configuration — The newest version; awaitable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The workspace has none yet.
ScopeMissing	Reached without a workspace in scope.

Configurations.count()

count() -> int

Return how many versions the workspace holds.

Returns: int — The count; awaitable in async mode. Saturates at 10,001.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.

Configurations.list()

list(
    *,
    limit: int | None = None,
    offset: int = 0,
) -> Iterable[Configuration] | AsyncIterable[Configuration]

Yield the workspace's configurations, paging lazily.

Arguments

Name	Type	Description
limit	int | None	Return at most this many. None walks to the end, or to row 10,100, past which the platform does not page.
offset	int	Skip this many, server-side.

Returns: Iterable[Configuration] | AsyncIterable[Configuration] — An iterable of configurations; async-iterable in async mode.

Raises

Exception	When
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.
ValueError	A negative limit or offset.

Configuration

One uploaded version of a workspace's configuration.

Attributes

Name	Type	Description
version	int	Version number within the workspace, starting at 1 and incremented by each upload.
id	str	Unique ID (a UUID).
content_hash	str	Hash of the package contents: base64 SHA3-256 over each file's path and digest, as dlt computes when building the package; identical file sets give identical hashes.
file_count	int	Number of files in the package.
size_bytes	int	Size of the uploaded package in bytes.
profiles	tuple[str, ...]	Profile names found in <profile>.config.toml / <profile>.secrets.toml file names, sorted.
created_at	datetime	When it was created.
created_by	str	The organization_membership_id of the member who uploaded it.
updated_at	datetime	When it was last changed.

Configuration.files()

files() -> tuple[FileEntry, ...]

List the files this configuration holds.

The manifest is stored with the content rather than with the record, so this is a fresh read every time.

Returns: tuple[FileEntry, ...] — One entry per file, in the platform's order; awaitable in async mode.

Raises

Exception	When
DataplaneTokenRejected	The data plane rejected the token the platform issued for it.
NotAuthorized	The caller lacks the access this call needs; message says why.
NotFound	The configuration no longer exists.
ScopeMissing	Reached without a workspace in scope.

Files

FileEntry

One file the platform holds for a deployment or a configuration.

Attributes

Name	Type	Description
relative_path	str	Path of the file inside the package, with / separators: relative to the workspace root for a deployment, and to the .dlt settings folder for a configuration.
size_bytes	int	Size of the file in bytes; 0 for a symlink.
sha3_256	str	Base64 SHA3-256 of the file contents, or of the linkname string for a symlink.
linkname	str | None	Symlink target; set for symlink entries only.