Python SDK Reference

The Python SDK is a thin native wrapper around the Rust SDK. Python code gets an idiomatic async API while rototo keeps workspace loading, linting, refresh, and resolution behavior in the Rust core.

Install

rototo is currently published as an alpha package for Python 3.10 and newer:

python -m pip install rototo

If your package resolver is constrained to stable releases, allow prereleases explicitly:

python -m pip install --pre rototo

The rototo release version stays SemVer, for example 0.1.0-alpha.4. Python packaging tools may display the equivalent PEP 440 spelling 0.1.0a4 for the distribution.

Load A Workspace

import rototo

workspace = await rototo.Workspace.load("examples/basic")

Workspace.load accepts the same source strings as the CLI. It lints the workspace and rejects lint failures before returning.

Resolve A Variable

resolution = await workspace.resolve_variable(
    "premium-message",
    {"user": {"tier": "premium"}},
)

print(resolution.value_key)
print(resolution.value)

VariableResolution has:

Resolve A Qualifier

resolution = await workspace.resolve_qualifier(
    "premium-users",
    {"user": {"tier": "premium"}},
)

print(resolution.value)

QualifierResolution has id and value.

Context Validation

Resolution validates context against schemas/context.schema.json by default. Skip validation for one call when a tool needs to evaluate partial context:

resolution = await workspace.resolve_variable(
    "premium-message",
    context,
    validate_context=False,
)

The context still must be a JSON object.

Inspect And Lint

workspace = await rototo.Workspace.inspect("examples/basic")
lint = await workspace.lint()

Inspection is for tools. A workspace loaded through inspect cannot resolve variables or qualifiers because it does not compile the runtime model.

Refreshing Workspace

workspace = await rototo.RefreshingWorkspace.load(
    source,
    period_seconds=30,
)

resolution = await workspace.resolve_variable("premium-message", context)
status = await workspace.status()
await workspace.shutdown()

RefreshingWorkspace keeps serving the last successfully loaded workspace when refresh fails. status returns a RefreshStatus dataclass with fingerprint, success, attempt, failure, error, refreshing, and immutable fields.

Errors

Rust RototoError values become rototo.RototoError in Python:

try:
    await workspace.resolve_variable("missing", {})
except rototo.RototoError as error:
    print(error)

Invalid Python option values, such as an unknown lint mode, raise Python ValueError.

Public Types