Welcome to starlark-pyo3’s documentation!

This package provides a sandboxed/restricted Python-like environment by exposing the starlark-rust interpreter for the Starlark Python-like language to Python via PyO3.

Starlark claims the following design principles:

  • Deterministic evaluation. Executing the same code twice will give the same results.

  • Hermetic execution. Execution cannot access the file system, network, system clock. It is safe to execute untrusted code.

  • Parallel evaluation. Modules can be loaded in parallel. To guarantee a thread-safe execution, shared data becomes immutable.

  • Simplicity. We try to limit the number of concepts needed to understand the code. Users should be able to quickly read and write code, even if they are not expert. The language should avoid pitfalls as much as possible.

  • Focus on tooling. We recognize that the source code will be read, analyzed, modified, by both humans and tools.

  • Python-like. Python is a widely used language. Keeping the language similar to Python can reduce the learning curve and make the semantics more obvious to users.

Here’s an example:

import starlark as sl


A_STAR = """
load("zz.star", "zz")
z = 3
z = 4

def f(x):
    z = 0
    for i in range(13):
        z += i*x
    return x*x - 5 + z

res = f(a - z + zz)

g_res = g(123)
res
"""


glb = sl.Globals.standard()
mod = sl.Module()
mod["a"] = 5


def g(x):
    print(f"g called with {x}")
    return 2 * x


mod.add_callable("g", g)

ast = sl.parse("a.star", A_STAR)


def load(name):
    if name == "zz.star":
        ast = sl.parse(name, "zz = 15")
        mod = sl.Module()
        sl.eval(mod, ast, glb)
        return mod.freeze()
    else:
        raise FileNotFoundError(name)


for lnt in ast.lint():
    print(lnt)
    print(lnt.severity)
    pass

val = sl.eval(mod, ast, glb, sl.FileLoader(load))
print(val)

print(mod["res"])
print(mod["g_res"])

Contents

Indices and tables