API reference

Auto-generated documentation from source code docstrings.

Public API

The main entry point for programmatic use. All functions are importable from dss_provisioner.config.

dss_provisioner.config

YAML configuration loading and convenience plan/apply API.

load(path)

Load a YAML configuration file.

plan(config, *, destroy=False, refresh=True)

Plan changes for the given configuration.

apply(plan_obj, config, *, progress=None)

Apply a previously computed plan.

plan_and_apply(config, *, destroy=False, refresh=True)

Plan and apply in one step.

refresh(config)

Refresh state from the live DSS instance (not persisted).

Returns the list of drift changes and the new state. Call :func:save_state to persist the returned state to disk.

save_state(config, state)

Persist state to disk.

drift(config)

Detect drift between state file and live DSS.

Configuration

Config

dss_provisioner.config.schema.Config

Bases: BaseModel

Provisioning configuration — validates YAML structure directly.

resources property

All declared resources — ordering is not significant.

ProviderConfig

dss_provisioner.config.schema.ProviderConfig

Bases: BaseSettings

DSS provider connection settings.

Fields can be set via YAML (constructor kwargs) or environment variables with the DSS_ prefix. Constructor kwargs take precedence.

api_key is typically provided via the DSS_API_KEY environment variable rather than YAML to avoid committing secrets to version control.

Engine types

Plan

dss_provisioner.engine.types.Plan

Bases: BaseModel

ResourceChange

dss_provisioner.engine.types.ResourceChange

Bases: BaseModel

Action

dss_provisioner.engine.types.Action

Bases: str, Enum

ApplyResult

dss_provisioner.engine.types.ApplyResult

Bases: BaseModel

PlanMetadata

dss_provisioner.engine.types.PlanMetadata

Bases: BaseModel

Engine

DSSEngine

dss_provisioner.engine.engine.DSSEngine(*, provider, project_key, state_path, registry)

Terraform-like plan/apply engine for DSS resources.

refresh(*, persist=False)

Refresh state from DSS. Returns (pre_refresh, post_refresh).

State

State

dss_provisioner.core.state.State

Bases: BaseModel

Terraform-style state file for tracking deployed resources.

Attributes:

Name	Type	Description
version	int	State file format version
project_key	str	DSS project key
resources	dict[str, ResourceInstance]	Mapping of resource addresses to instances
outputs	dict[str, Any]	Output values from the configuration

save(path)

Save state to a JSON file.

• Writes atomically (temp file + rename)
• Writes a .backup copy of the previous state when overwriting

load(path) classmethod

Load state from a JSON file.

load_or_create(path, project_key) classmethod

Load existing state or create a new one.

ResourceInstance

dss_provisioner.core.state.ResourceInstance

Bases: BaseModel

A tracked resource instance in the state file.

Attributes:

Name	Type	Description
address	str	Unique resource address (e.g., "dss_recipe.join_orders")
resource_type	str	Type of the resource (e.g., "dss_join_recipe")
name	str	Resource name (e.g., "join_orders")
attributes	dict[str, Any]	Current attribute values
attributes_hash	str	SHA256 hash for change detection
dependencies	list[str]	Addresses of dependencies
created_at	datetime	When the resource was created
updated_at	datetime	When the resource was last updated

Provider

DSSProvider

dss_provisioner.core.provider.DSSProvider

Bases: BaseModel

Connection configuration for a DSS instance.

For external use, provide host and auth. For internal use (inside DSS notebooks/recipes), use the from_client classmethod to inject a client.

Examples:

External with API key

provider = DSSProvider( host="https://dss.company.com", auth=ApiKeyAuth(api_key="my-api-key"), )

Inside DSS notebook

import dataiku provider = DSSProvider.from_client(dataiku.api_client())

client cached property

Get the DSS client.

from_client(client) classmethod

Create a provider with an injected client.

Use this for running inside DSS or for testing with a mock client.

Parameters:

Name	Type	Description	Default
client	DSSClient	A pre-configured DSSClient instance	required

Example

import dataiku provider = DSSProvider.from_client(dataiku.api_client())

in_project(project_key)

Bind this provider to a single project for convenience.

ApiKeyAuth

dss_provisioner.core.provider.ApiKeyAuth

Bases: BaseModel

API key authentication for DSS.

Errors

dss_provisioner.engine.errors

Engine error types.

EngineError

Bases: Exception

Base exception for engine errors.

UnknownResourceTypeError(resource_type)

Bases: EngineError

Raised when a resource type has no registration/handler.

DuplicateAddressError(address)

Bases: EngineError

Raised when multiple desired resources share the same address.

DependencyCycleError(addresses)

Bases: EngineError

Raised when dependencies contain a cycle.

StateProjectMismatchError(expected, got)

Bases: EngineError

Raised when the on-disk state belongs to a different project.

StalePlanError

Bases: EngineError

Raised when applying a plan against a different state than planned.

StateLockError

Bases: EngineError

Raised when the state lock cannot be acquired or released.

ValidationError(errors)

Bases: EngineError

One or more resources failed plan validation.

ApplyError(*, applied, address, message)

Bases: EngineError

Raised when an apply fails mid-way through.

Carries the partial result (what was applied before the failure) so callers can inspect progress. The original exception is chained via __cause__.

ApplyCanceled

Bases: EngineError

Raised when an apply is canceled (e.g., Ctrl-C).