starlark

Documentation

Overview

Package starlark provides Starlark execution context and builtins for template rendering.

Index

• func BuildConfigDict(name, materialized, uniqueKey, owner, schema string, tags []string, ...) starlark.Value
• func ConfigToStarlark(config map[string]any) (starlark.Value, error)
• func EnvToStarlark(env string) starlark.Value
• func GoToStarlark(v any) (starlark.Value, error)
• func Predeclared(config starlark.Value, env string, target *TargetInfo, this *ThisInfo) starlark.StringDict
• func ToGo(v starlark.Value) (any, error)
• type ContextOption
  • func WithMacroProvider(provider MacroProvider) ContextOption
  • func WithMacros(macros starlark.StringDict) ContextOption
• type EvalError
  • func (e *EvalError) Error() string
• type EvalResult
• type EvalTask
• type ExecuteContext
• type ExecutionContext
  • func NewContext(config starlark.Value, env string, target *TargetInfo, this *ThisInfo, ...) *ExecutionContext
  • func NewExecutionContext(config starlark.Value, env string, target *TargetInfo, this *ThisInfo) *ExecutionContext
  • func (ctx *ExecutionContext) AddMacros(macros starlark.StringDict) error
  • func (ctx *ExecutionContext) EvalExpr(expr string, filename string, line int) (starlark.Value, error)
  • func (ctx *ExecutionContext) EvalExprString(expr string, filename string, line int) (string, error)
  • func (ctx *ExecutionContext) EvalExprStringWithLocals(expr string, filename string, line int, locals starlark.StringDict) (string, error)
  • func (ctx *ExecutionContext) EvalExprWithLocals(expr string, filename string, line int, locals starlark.StringDict) (starlark.Value, error)
  • func (ctx *ExecutionContext) Globals() starlark.StringDict
• type MacroProvider
• type ParallelExecutor
  • func NewParallelExecutor(maxConcurrency int, globals starlark.StringDict) *ParallelExecutor
  • func (e *ParallelExecutor) Execute(tasks []EvalTask) []EvalResult
• type TargetInfo
  • func TargetInfoFromConfig(t *core.TargetConfig) *TargetInfo
  • func (t *TargetInfo) ToStarlark() starlark.Value
• type ThisInfo
  • func (t *ThisInfo) ToStarlark() starlark.Value
• type ThreadPool
  • func NewThreadPool(maxSize int) *ThreadPool
  • func (p *ThreadPool) Get(name string) *starlark.Thread
  • func (p *ThreadPool) Put(thread *starlark.Thread)
  • func (p *ThreadPool) Size() int

Functions

func BuildConfigDict

func BuildConfigDict(name, materialized, uniqueKey, owner, schema string, tags []string, meta map[string]any) starlark.Value

BuildConfigDict creates a config dict from FrontmatterConfig-like values. This is a convenience function that builds the map from individual fields.

func ConfigToStarlark

func ConfigToStarlark(config map[string]any) (starlark.Value, error)

ConfigToStarlark converts frontmatter config map to a Starlark dict. The config dict is accessible as "config" global in templates.

func EnvToStarlark

func EnvToStarlark(env string) starlark.Value

EnvToStarlark converts environment string to Starlark value. The env string is accessible as "env" global in templates.

func GoToStarlark

func GoToStarlark(v any) (starlark.Value, error)

GoToStarlark converts a Go value to a Starlark value. Supported types: string, int, int64, float64, bool, []string, []any, map[string]any

func Predeclared

func Predeclared(config starlark.Value, env string, target *TargetInfo, this *ThisInfo) starlark.StringDict

Predeclared returns all predeclared/builtin globals for template execution. This includes: config, env, target, this Note: Macros are added separately via the macro loader.

func ToGo

func ToGo(v starlark.Value) (any, error)

ToGo converts a Starlark value back to a Go value. Returns: string, int64, float64, bool, []any, map[string]any, or nil

Types

type ContextOption

type ContextOption func(*ExecutionContext)

ContextOption is a functional option for configuring ExecutionContext.

func WithMacroProvider

func WithMacroProvider(provider MacroProvider) ContextOption

WithMacroProvider sets macros from a MacroProvider. This is the preferred way to inject macros loaded from .star files.

func WithMacros

func WithMacros(macros starlark.StringDict) ContextOption

WithMacros sets the macros for the context.

type EvalError

type EvalError struct {
	File    string
	Line    int
	Expr    string
	Message string
}

EvalError represents an error during Starlark expression evaluation.

func (*EvalError) Error

func (e *EvalError) Error() string

type EvalResult

type EvalResult struct {
	Name  string
	Value starlark.Value
	Error error
}

EvalResult represents the result of an evaluation task.

type EvalTask

type EvalTask struct {
	Name string // Identifier for this task (used for error reporting)
	Expr string // Starlark expression to evaluate
}

EvalTask represents a single evaluation task.

type ExecuteContext

type ExecuteContext struct {
	Thread  *starlark.Thread
	Globals starlark.StringDict
}

ExecuteContext represents the execution context for a single template rendering.

type ExecutionContext

type ExecutionContext struct {
	// Config dict containing parsed YAML frontmatter
	// Accessible as: config["materialized"], config["owner"], etc.
	Config starlark.Value

	// Env is the current environment string
	// Values: "prod", "dev", "staging", etc.
	Env string

	// Target contains adapter/database specifics
	// Accessible as: target.type, target.schema, target.database
	Target *TargetInfo

	// This contains current model info
	// Accessible as: this.name, this.schema
	This *ThisInfo

	// Macros contains loaded macro namespaces
	// Each key is a namespace (e.g., "datetime") with a struct of functions
	Macros starlark.StringDict
	// contains filtered or unexported fields
}

ExecutionContext provides all globals and state for Starlark template execution. Note: No ref() function - dependencies are extracted by lineage parser from SQL AST.

func NewContext

func NewContext(config starlark.Value, env string, target *TargetInfo, this *ThisInfo, opts ...ContextOption) *ExecutionContext

NewContext creates a new execution context with functional options. This is an alternative constructor that uses the options pattern.

func NewExecutionContext

func NewExecutionContext(config starlark.Value, env string, target *TargetInfo, this *ThisInfo) *ExecutionContext

NewExecutionContext creates a new execution context with the given parameters.

func (*ExecutionContext) AddMacros

func (ctx *ExecutionContext) AddMacros(macros starlark.StringDict) error

AddMacros adds macro namespaces to the context. Returns error if a macro name conflicts with a builtin.

func (*ExecutionContext) EvalExpr

func (ctx *ExecutionContext) EvalExpr(expr string, filename string, line int) (starlark.Value, error)

EvalExpr evaluates a single Starlark expression and returns the result. This is used for {{ expr }} template expressions.

func (*ExecutionContext) EvalExprString

func (ctx *ExecutionContext) EvalExprString(expr string, filename string, line int) (string, error)

EvalExprString evaluates a Starlark expression and returns the string result. This is the typical use case for template expressions.

func (*ExecutionContext) EvalExprStringWithLocals

func (ctx *ExecutionContext) EvalExprStringWithLocals(expr string, filename string, line int, locals starlark.StringDict) (string, error)

EvalExprStringWithLocals evaluates a Starlark expression with local variables and returns the string result.

func (*ExecutionContext) EvalExprWithLocals

func (ctx *ExecutionContext) EvalExprWithLocals(expr string, filename string, line int, locals starlark.StringDict) (starlark.Value, error)

EvalExprWithLocals evaluates a Starlark expression with additional local variables. This is used for expressions inside loops where loop variables need to be in scope.

func (*ExecutionContext) Globals

func (ctx *ExecutionContext) Globals() starlark.StringDict

Globals returns the combined globals dictionary for Starlark execution.

type MacroProvider

type MacroProvider interface {
	// ToStarlarkDict returns the macros as a Starlark StringDict.
	ToStarlarkDict() starlark.StringDict
}

MacroProvider provides macros as a Starlark dictionary. This interface allows the starlark package to be decoupled from the macro package. Implementations (like macro.Registry) are wired in internal/engine.

type ParallelExecutor

type ParallelExecutor struct {
	// contains filtered or unexported fields
}

ParallelExecutor executes multiple template renders in parallel.

func NewParallelExecutor

func NewParallelExecutor(maxConcurrency int, globals starlark.StringDict) *ParallelExecutor

NewParallelExecutor creates a new parallel executor with shared globals.

func (*ParallelExecutor) Execute

func (e *ParallelExecutor) Execute(tasks []EvalTask) []EvalResult

Execute runs multiple evaluations in parallel and collects results.

type TargetInfo

type TargetInfo struct {
	Type     string // "duckdb", "postgres", "snowflake"
	Schema   string // Default schema
	Database string // Database name
}

TargetInfo contains database adapter/target information. Exposed as the "target" global in Starlark execution.

func TargetInfoFromConfig

func TargetInfoFromConfig(t *core.TargetConfig) *TargetInfo

TargetInfoFromConfig converts a core.TargetConfig to a TargetInfo for template rendering. This extracts only the fields that should be exposed to templates (not credentials).

func (*TargetInfo) ToStarlark

func (t *TargetInfo) ToStarlark() starlark.Value

ToStarlark converts TargetInfo to a Starlark struct value.

type ThisInfo

type ThisInfo struct {
	Name   string // Current model name
	Schema string // Current model schema
}

ThisInfo contains current model information. Exposed as the "this" global in Starlark execution.

func (*ThisInfo) ToStarlark

func (t *ThisInfo) ToStarlark() starlark.Value

ToStarlark converts ThisInfo to a Starlark struct value.

type ThreadPool

type ThreadPool struct {
	// contains filtered or unexported fields
}

ThreadPool manages a pool of Starlark threads for parallel execution. This is useful for rendering multiple templates concurrently.

func NewThreadPool

func NewThreadPool(maxSize int) *ThreadPool

NewThreadPool creates a new thread pool with the specified maximum size.

func (*ThreadPool) Get

func (p *ThreadPool) Get(name string) *starlark.Thread

Get retrieves a thread from the pool or creates a new one. The thread name is used for error reporting.

func (*ThreadPool) Put

func (p *ThreadPool) Put(thread *starlark.Thread)

Put returns a thread to the pool for reuse. If the pool is full, the thread is discarded.

func (*ThreadPool) Size

func (p *ThreadPool) Size() int

Size returns the current number of threads in the pool.