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, **kwargs)¶: Added in version 2025.2.2.

Changed in version 2025.2.3: Added support for keyword arguments.

call_with(options, name, /, *args, **kwargs)¶: Like call(), but takes an EvalOptions bundle carrying resource limits and cooperative cancellation, and returns an EvalResult. Because options are explicit, **kwargs is passed through unchanged to the Starlark callee — there are no reserved keyword names.

Loaders¶

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

Parsing and Evaluation¶

class starlark.EvalOptions(*, check_cancelled: Callable[[], bool] | None = None, max_callstack_size: int | None = None)¶

–

Bundle of per-evaluation options passed to eval_with() and FrozenModule.call_with(). All fields are keyword-only in the constructor and read-only afterwards. Instances are safe to share across evaluations.

check_cancelled¶: Optional zero-argument callable invoked periodically during evaluation (roughly every 1000 bytecode instructions). A truthy return aborts evaluation with StarlarkError; a raised Python exception propagates to the caller. The callback must not access the module passed to eval_with(): the module is locked during evaluation and re-entry will deadlock. Cancellation is scoped to a single eval_with() / FrozenModule.call_with() call; nested eval_with() calls (e.g. from a FileLoader) need their own callback.

max_callstack_size¶: Optional positive integer cap on Starlark call stack depth.

class starlark.EvalResult¶

Rich result of an evaluation returned by eval_with() and FrozenModule.call_with(). Currently wraps only the return value; future post-eval readouts (tick counts, profile output, coverage) will land as additional read-only fields.

value¶: The value returned by the evaluation, after Object conversion.

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) → object¶

–

Returns:: the value returned by the evaluation, after Object conversion.

If you need to pass evaluator options (cooperative cancellation, resource limits), use eval_with() instead.

starlark.eval_with(options: EvalOptions, module: Module, ast: AstModule, globals: Globals, /, file_loader: FileLoader | None = None) → EvalResult¶

–

Like eval(), but takes an EvalOptions bundle carrying resource limits and cooperative cancellation, and returns an EvalResult wrapping the evaluation’s return value.

Parameters:: options – An EvalOptions bundle. See EvalOptions for the semantics of each field.
Returns:: An EvalResult whose value is the evaluation’s return, after Object conversion.