Variables

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

Variables

The variables of one workspace, across its scopes.

A whole scope is read at once — there is no paging and no per-variable address.

Variables.list()

list(*, profile: str | None | Keep = KEEP) -> tuple[VariableScope, ...]

Read the workspace's variables, by scope.

Arguments

Name	Type	Description
profile	str | None | Keep	Omit for every scope. Pass a profile name for that profile's scope, or WORKSPACE_PROFILE for the workspace-level one.

Returns: tuple[VariableScope, ...] — One entry per scope read, always as scopes even when one was selected; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
DataplaneTokenRejected	The data plane rejected the token the platform issued for it.
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.

Variables.apply()

apply(
    *,
    profile: str | None,
    upserts: Mapping[str, str] | None = None,
    secrets: Mapping[str, str] | None = None,
    deletes: Sequence[str] | None = None,
) -> tuple[VariableChange, ...]

Store and remove variables in one scope, in a single request.

Arguments

Name	Type	Description
profile	str | None	The scope to write to, or WORKSPACE_PROFILE for the workspace-level one. Required: a write always names one scope.
upserts	Mapping[str, str] | None	Names and values to store as plain text.
secrets	Mapping[str, str] | None	Names and values to store as secrets.
deletes	Sequence[str] | None	Names to remove. Removing an absent name is reported, not raised.

Returns: tuple[VariableChange, ...] — One result per name in the request; 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.
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.
ValueError	Nothing to do, or a name appears in more than one of the three arguments, where the outcome would be undefined.

Variables.set()

set(name: str, value: str, *, profile: str | None, secret: bool = False) -> VariableChange

Store one variable.

Arguments

Name	Type	Description
name	str	The variable's name.
value	str	Its value.
profile	str | None	The scope to write to, or WORKSPACE_PROFILE.
secret	bool	Store it as a secret, so reads never return the value.

Returns: VariableChange — What the platform did with it; 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.
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.

Variables.delete()

delete(name: str, *, profile: str | None) -> VariableChange

Remove one variable.

Arguments

Name	Type	Description
name	str	The variable's name.
profile	str | None	The scope to remove it from, or WORKSPACE_PROFILE.

Returns: VariableChange — What the platform did; a name that was not there comes back as attr:VariableChangeStatus.NOT_FOUND rather than raising. 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.
NotAuthorized	The caller lacks the access this call needs; message says why.
ScopeMissing	Reached without a workspace in scope.

Variables.get()

get(name: str, *, profile: str | None) -> Variable

Return one variable from one scope.

There is no single-variable endpoint, so this reads the whole scope.

Arguments

Name	Type	Description
name	str	The variable's name.
profile	str | None	The scope to read, or WORKSPACE_PROFILE.

Returns: Variable — The variable; awaitable in async mode.

Raises

Exception	When
BadRequest	The request was rejected as invalid; message, code and fields say why.
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	No variable of that name in that scope.
ScopeMissing	Reached without a workspace in scope.

Variable

One variable, as the platform reports it.

A secret's value is None because it is withheld, not empty.

Attributes

Name	Type	Description
name	str	Environment variable name.
secret	bool	Whether the platform stores it as a secret.
value	str | None	The value, or None for a secret.
created_at	datetime	When the variable was created.
created_by	str	ID of the user who created the variable.
updated_at	datetime	When the variable was last updated.
updated_by	str	ID of the user who last updated the variable.

VariableChange

What a change did to one name.

Attributes

Name	Type	Description
name	str	Environment variable name.
status	VariableChangeStatus	What happened to this variable: upserted (created or updated), removed, or not_found (a delete named a variable that does not exist).

VariableScope

The variables one profile sees, or the workspace-level set.

Attributes

Name	Type	Description
profile	str | None	Profile owning this scope; None is the workspace-wide scope.
variables	tuple[Variable, ...]	Variables in this scope, secrets redacted.

VariableChangeStatus

What became of one name in a change.

Members

Member	Value	Description
UPSERTED	'upserted'	Stored, whether it existed before or not.
REMOVED	'removed'	Deleted.
NOT_FOUND	'not_found'	Asked to be deleted, but was not there.
UNKNOWN	'unknown'	A status this SDK version does not know.

WORKSPACE_PROFILE

WORKSPACE_PROFILE = None

The workspace-level variable scope, which every profile inherits.

Pass it as profile to read or write only that scope.