Usage

Create a context

A starlark_go.Starlark object is needed to provide a context (mainly, a set of global variables) for executing Starlark code. Creating an empty one is simple:

from starlark_go import Starlark

s = Starlark()

The globals keyword argument to the A starlark_go.Starlark constructor can be used to pass a dictionary containing some initial global variables:

from starlark_go import Starlark

s = Starlark(globals={"a": 1, "b": 3})

Evaluating code

starlark_go.Starlark.eval() can be used to evaluate a Starlark expression:

from starlark_go import Starlark

s = Starlark()

s.eval("2 + 2") # 4

Starlark syntax is more-or-less identical to Python. Expressions can reference variables, just like you might in Python:

from starlark_go import Starlark

s = Starlark(globals={"a": 1, "b": 3})

s.eval("a + b") # 4

Defining variables and functions

starlark_go.Starlark.eval() is only for evaluating expressions; if you want to define things in Starlark, you’ll need to use starlark_go.Starlark.exec().

from starlark_go import Starlark

s = Starlark()

s.exec("a = 1")
s.exec("b = 3")
s.eval("a + b") # 4

There is no distinction between variables set by globals versus variables set by exec; it is simply another way to set a variable.

starlark_go.Starlark.exec() can also be used to define functions in Starlark. Remember, Starlark’s syntax is more-or-less identical to Python:

from starlark_go import Starlark

s = Starlark()

s.exec("""
def add_one(x):
  return x + 1
""")

s.eval("add_one(3)") # 4

Defining variables from Python

starlark_go.Starlark.set() can be used to define one or more Starlark global variables:

from starlark_go import Starlark

s = Starlark()

s.set(a=1, b=3)

s.eval("a + b") # 4

There is no distinction between variables set by set versus other variables; it is simply another way to set a variable.

Retrieving variables

starlark_go.Starlark.get() can be used to retrieve a Starlark global variable:

from starlark_go import Starlark

s = Starlark(globals={"b": 3, "c": True})

s.exec("a = 1")
s.set(d=[1, 2, 3])

s.get("a") # 1
s.get("b") # 3
s.get("c") # True
s.get("d") # [1, 2, 3]

A default value can be provided to starlark_go.Starlark.get(); if one is not provided and the variable you are attempting to retrieve does not exist, a KeyError will be raised:

from starlark_go import Starlark

s = Starlark()

s.get("e") # !!! raises KeyError !!!
s.get("e", 72) # 72

Removing variables

starlark_go.Starlark.pop() functions identically to starlark_go.Starlark.get(), except that it removes the variable before returning its value:

from starlark_go import Starlark

s = Starlark(globals={"a": 1, "b": 2})

s.eval("a + b") # 4
s.pop("a") # 1
s.eval("a + b") # !!! raises ResolveError !!!

Overriding the print() function

By default, Starlark’s print() function is routed to Python’s built-in print(), but you can provide a different function to override it.

This can be done when you create the context:

import logging

from starlark_go import Starlark

s = Starlark(print=logging.warning)

…or after it is created:

import logging

from starlark_go import Starlark

s = Starlark()
s.print = logging.warning

…or for individual calls to starlark_go.Starlark.eval() and starlark_go.Starlark.exec():

import logging

from starlark_go import Starlark

s = Starlark()
s.exec('print("hello!")', print=logging.warning)