API reference

exception starlark_go.ConversionError(error: str, error_type: str | None = None, *extra_args: Any)

Bases: StarlarkError

A base class for conversion errors.

exception starlark_go.ConversionToPythonFailed(error: str, error_type: str | None = None, *extra_args: Any)

Bases: ConversionError

An error when converting a Starlark value to a Python value.

This exception is raied by starlark_go.Starlark.eval() and starlark_go.Starlark.get() when a Starlark value can not be converted to a Python value.

exception starlark_go.ConversionToStarlarkFailed(error: str, error_type: str | None = None, *extra_args: Any)

Bases: ConversionError

An error when converting a Python value to a Starlark value.

This exception is raied by starlark_go.Starlark.set() when a Python value can not be converted to a Starlark value.

exception starlark_go.EvalError(error: str, error_type: str, filename: str, line: int, column: int, function_name: str, backtrace: str)

Bases: StarlarkError

A Starlark evaluation error.

This exception is raised when otherwise valid code attempts an illegal operation, such as adding a string to an integer.

backtrace

A backtrace through Starlark’s stack leading up to the error.

Type:

str

column

The column that the error occurred on (1-based)

Type:

int

filename

The name of the file that the error occurred in.

Type:

str

function_name

The name of the function that the error occurred in

Type:

str

line

The line number that the error occurred on (1-based)

Type:

int

exception starlark_go.ResolveError(error: str, error_type: str, errors: Tuple[ResolveErrorItem, ...])

Bases: StarlarkError

A Starlark resolution error.

This exception is raised by starlark_go.Starlark.eval() or starlark_go.Starlark.exec() when an undefined name is referenced.

errors

A list of locations where resolution errors occurred. A ResolveError may contain one or more locations.

Type:

List[ResolveErrorItem]

exception starlark_go.StarlarkError(error: str, error_type: str | None = None, *extra_args: Any)

Bases: Exception

Base class for Starlark errors.

All Starlark-specific errors that are raised by starlark_go.Starlark are derived from this class.

error

A description of the error.

Type:

str

error_type

The name of the Go type of the error.

Type:

Optional[str]

exception starlark_go.SyntaxError(error: str, error_type: str, msg: str, filename: str, line: int, column: int)

Bases: StarlarkError

A Starlark syntax error.

This exception is raised when syntatically invalid code is passed to starlark_go.Starlark.eval() or starlark_go.Starlark.exec().

column

The column that the error occurred on (1-based)

Type:

int

filename

The name of the file that the error occurred in (taken from the filename parameter to starlark_go.Starlark.eval() or starlark_go.Starlark.exec().)

Type:

str

line

The line number that the error occurred on (1-based)

Type:

int

msg

A description of the syntax error

Type:

str

class starlark_go.ResolveErrorItem(msg: str, line: int, column: int)

Bases: object

A location associated with a ResolveError.

column

The column where the problem occurred (1-based)

Type:

int

line

The line where the problem occurred (1-based)

Type:

int

msg

A description of the problem at the location.

Type:

str

class starlark_go.Starlark(*, globals=None, print=None)

Bases: object

Create a Starlark object. A Starlark object contains a set of global variables, which can be manipulated by executing Starlark code.

Parameters:

  • globals (Mapping[str, Any]) – Initial set of global variables. Keys must be strings. Values can be any type supported by set().

  • print (Callable[[str], Any]) – A function to call in place of Starlark’s print() function. If unspecified, Starlark’s print() function will be forwarded to Python’s built-in print().

eval(expr, *, filename=None, convert=True, print=None)

Evaluate a Starlark expression. The expression passed to eval must evaluate to a value. Function definitions, variable assignments, and control structures are not allowed by eval. To use those, please use exec().

Parameters:

  • expr (str) – A string containing a Starlark expression to evaluate

  • filename (Optional[str]) – An optional filename to use in exceptions, if evaluting the expression fails.

  • convert (bool) – If True, convert the result of the expression into a Python value. If False, return a string containing the representation of the expression in Starlark. Defaults to True.

  • print (Callable[[str], Any]) – A function to call in place of Starlark’s print() function. If unspecified, Starlark’s print() function will be forwarded to Python’s built-in print().

Raises:
Return type:

Any

exec(defs, *, filename=None, print=None)

Execute Starlark code. All legal Starlark constructs may be used with exec.

exec does not return a value. To evaluate the value of a Starlark expression, please use func:eval.

Parameters:

  • defs (str) – A string containing Starlark code to execute

  • filename (Optional[str]) – An optional filename to use in exceptions, if evaluting the expression fails.

  • print (Callable[[str], Any]) – A function to call in place of Starlark’s print() function. If unspecified, Starlark’s print() function will be forwarded to Python’s built-in print().

Raises:
get(name, default_value=Ellipsis)

Get the value of a Starlark global variable.

Conversion from most Starlark data types is supported:

For the aggregate types (dict, list, set, and tuple,) all keys and/or values must also be one of the supported types.

Attempting to get the value of any other Starlark type will raise a ConversionToPythonFailed.

Parameters:

  • name (str) – The name of the global variable.

  • default_value (Any) – A default value to return, if no global variable named name is defined.

Raises:
Return type:

Any

globals()

Get the names of the currently defined global variables.

Return type:

List[str]

pop(name, default_value=Ellipsis)

Remove a Starlark global variable, and return its value.

If a value of name does not exist, and no default_value has been specified, raise KeyError. Otherwise, return default_value.

Parameters:

  • name (str) – The name of the global variable.

  • default_value (Any) – A default value to return, if no global variable named name is defined.

Raises:
Return type:

Any

set(**kwargs)

Set the value of one or more Starlark global variables.

For each keyword parameter specified, one global variable is set.

Conversion from most basic Python types is supported:

For the aggregate types (dict, list, set, and tuple,) all keys and/or values must also be one of the supported types.

Attempting to set a value of any other Python type will raise a ConversionToStarlarkFailed.

Raises:

ConversionToStarlarkFailed – if a value is of an unsupported type for conversion.

print

A function to call in place of Starlark’s print() function. If unspecified, Starlark’s print() function will be forwarded to Python’s built-in print().

Type:

Callable[[str], Any]

starlark_go.configure_starlark(*, allow_set=None, allow_global_reassign=None, allow_recursion=None)

Change what features the Starlark interpreter allows. Unfortunately, this manipulates global variables, and affects all Starlark interpreters in your application. It is not possible to have one Starlark interpreter with allow_set=True and another with allow_set=False simultaneously.

All feature flags are initially False.

See the starlark-go documentation for more information.

Parameters:

  • allow_set (Optional[bool]) –

    If True, allow the creation of set objects in Starlark.

  • allow_global_reassign (Optional[bool]) – If True, allow reassignment to top-level names; also, allow if/for/while at top-level.

  • allow_recursion (Optional[bool]) – If True, allow while statements and recursive functions.