Reference¶

Object conversion¶

To convert values between starlark and Python, JSON is currently being used as an intermediate format, which defines the scope of what is convertible. This, however, is subject to change.

References to Source Locations¶

class starlark.ResolvedFileSpan¶

file¶: A str.

span¶: A ResolvedSpan.

__str__()¶: Return str(self).

class starlark.ResolvedPos¶

line¶: A int.

column¶: A int.

class starlark.ResolvedSpan¶

begin¶: A ResolvedPos.

end¶: A ResolvedPos.

Diagnostics¶

exception starlark.StarlarkError¶

class starlark.EvalSeverity¶

Error¶

Warning¶

Advice¶

Disabled¶

class starlark.Lint¶

__str__()¶: Return str(self).

resolved_location¶: A ResolvedFileSpan.

short_name¶: A str.

severity¶: A EvalSeverity.

problem¶: A str.

original¶: A str.

class starlark.Error¶

span: ResolvedFileSpan | None

__str__()¶: Return str(self).

Dialect¶

class starlark.DialectTypes¶

DISABLE¶

PARSE_ONLY¶

ENABLE¶

class starlark.Dialect¶

static standard() → Dialect¶: –

static extended() → Dialect¶: –

enable_def¶: A bool.

enable_lambda¶: A bool.

enable_load¶: A bool.

enable_keyword_only_arguments¶: A bool.

enable_positional_only_arguments¶: A bool.

Added in version 2025.2.6.

enable_types¶: A value of type DialectTypes.

enable_load_reexport¶: A bool.

enable_top_level_stmt¶: A bool.

enable_f_strings¶: A bool.

Note

These attributes are only writable (not readable) for the moment.

Type checking¶

class starlark.Interface¶: Opaque for now.

AST¶

class starlark.AstLoad¶

module_id¶

symbols¶

class starlark.AstModule¶

See parse() to create objects of this type, and eval() to evaluate them.

lint() → list[Lint]¶: –

loads() → list[AstLoad]¶: –

typecheck(globals: Globals, loads: dict[str, Interface]) → tuple[list[Error], Interface, tuple[Never, ...]]¶: –

Values¶

class starlark.OpaquePythonObject(obj)¶: An ‘opaque’ Python object that can be passed to Starlark. It cannot be interacted with from the Starlark side. Upon conversion from Starlark to Python, the original wrapped object reappears.

Added in version 2025.2.5.

Decimal¶

This package preserves Python Decimal values without precision loss. Decimals passed from Python stay as precise decimal values in Starlark and round-trip back to Python as Decimal objects.

>>> import decimal
>>> import starlark as sl

>>> glb = sl.Globals.extended_by([sl.LibraryExtension.RustDecimal])
>>> mod = sl.Module()

>>> # Pass Python decimals to Starlark
>>> mod["amount"] = decimal.Decimal("100.25")

>>> program = """
... # Create decimals in Starlark with RustDecimal()
... result = amount * 2 + RustDecimal('0.75')
... # Control precision with scale() and round_dp()
... pi = RustDecimal("3.14159")
... pi.scale()        # Returns 5 (number of decimal places)
... pi.round_dp(2)    # Returns RustDecimal("3.14")
... result
... """

>>> ast = sl.parse("prog.star", program)
>>> val = sl.eval(mod, ast, glb)
>>> assert val == decimal.Decimal("201.25")

Implementation notes:

Starlark RustDecimal operations use rust_decimal semantics (28 decimal places maximum, Banker’s rounding)
Python Decimal operations use Python semantics (configurable via context)
Conversion preserves exact values without precision loss
Python’s decimal.getcontext() is not consulted during conversion
Use round_dp(n) to explicitly control decimal places before or after conversion

Globals¶

class starlark.LibraryExtension¶

StructType¶

RecordType¶

EnumType¶

Map¶

Filter¶

Partial¶

ExperimentalRegex¶

Debug¶

Print¶

Pprint¶

Breakpoint¶

Json¶

Typing¶

Internal¶

CallStack¶

RustDecimal¶

class starlark.Globals¶

static standard() → Globals¶: –

static extended_by(extensions: list[LibraryExtension]) → Globals¶: –

Modules¶

class starlark.Module¶

–

__getitem__(key, /)¶: Return self[key].

__setitem__(key, value, /)¶: Set self[key] to value.

add_callable(name: str, callable: Callable) → None¶: –

freeze() → FrozenModule¶: –

class starlark.FrozenModule¶

call(name, *args, check_cancelled=None, **kwargs)¶: Accepts the same check_cancelled keyword argument as eval(). That name is reserved here and cannot be passed as a Starlark keyword argument to the called function.

Added in version 2025.2.2.

Changed in version 2025.2.3: Added support for keyword arguments.

Loaders¶

class starlark.FileLoader(load_func: Callable[[str], FrozenModule])¶: –

Parsing and Evaluation¶

starlark.parse(filename: str, content: str, dialect: Dialect | None = None) → AstModule¶

–

Parse Starlark source code as a string and return an AST.

starlark.eval(module: Module, ast: AstModule, globals: Globals, file_loader: FileLoader | None = None, *, check_cancelled: Callable[[], bool] | None = None) → object¶

–

Parameters:: check_cancelled – An optional zero-argument callable invoked periodically (roughly every 1000 bytecode instructions). If it returns a truthy value, evaluation aborts and StarlarkError is raised. If it raises a Python exception, evaluation aborts and that exception propagates to the caller. The callback must not access module: the module is locked during evaluation and re-entry will deadlock. Cancellation is scoped to this eval() call; nested eval() calls (e.g. from a FileLoader) need their own callback.
Returns:: the value returned by the evaluation, after Object conversion.