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

The package is built with maturin while rototo is in alpha:

cd sdks/python
python -m maturin develop

After release, install the published package:

python -m pip install 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