monty

package module
v0.0.15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 15 Imported by: 0

README

gomonty

gomonty is an experimental fork of ewhauser/gomonty providing Go bindings to Monty. The Go package keeps the compatible package name monty, while the Rust boundary is mapped to Monty's current subprocess architecture through pinned Cargo git dependencies.

Documentation: https://pkg.go.dev/github.com/regularkevvv/gomonty

Status

  • Experimental.
  • Go module path: github.com/regularkevvv/gomonty
  • Upstream runtime: Monty v0.0.19 (e347739909877f4fb03877e23dd092286fc7e659)
  • Go bindings are cgo-free and use purego with an explicitly prepared shared library and version-matched worker executable
  • Rust FFI crate: crates/monty-go-ffi
  • Protocol worker crate: crates/gomonty-worker
  • Upstream Monty source: pinned in the root Cargo.toml
  • Native executables are not stored in Git or in Go module ZIPs
  • Reviewable release hashes: internal/runtimebundle/manifests/current.json
  • Generated header: checked into internal/ffi/include/monty_go_ffi.h
  • Linux GNU/glibc versus musl is detected from the running system before an asset is selected; ambiguous systems fail closed instead of guessing

Installing the Go module does not execute or fetch native code. Before first use, the application owner explicitly chooses either a verified GitHub release download or a local build from the reviewed, digest-pinned Rust source. Normal calls such as monty.New never build or access the network.

Monty code executes in a child process managed by Monty's worker pool. This provides crash isolation, process replacement, parent-side timeout enforcement, and serializable session recovery. It is not an OS security sandbox: filesystem, network, and other confinement still require a separate policy and sandboxing layer.

Repository Layout

  • *.go, vfs/, internal/ffi/: copied Go bindings adapted to the root module layout
  • go/README.md: consumer-facing Go API notes and examples carried over from the source repo
  • examples/: standalone example module for local consumption examples
  • crates/monty-go-ffi/: Rust C ABI adapter over monty-pool
  • crates/gomonty-worker/: small version-matched Monty protocol child
  • cmd/gomonty/: explicit prepare download and prepare build command
  • internal/runtimebundle/: manifest, verification, cache, and release tooling
  • scripts/build-go-ffi.sh <target-triple>: builds one target's shared library and worker for repository development and release automation

Prepare the Native Runtime

Install the source-only module and preparation command at the same version:

go get github.com/regularkevvv/gomonty@vX.Y.Z
go install github.com/regularkevvv/gomonty/cmd/gomonty@vX.Y.Z

Then choose one explicit preparation mode:

# Download the exact target asset from the versioned GitHub release.
gomonty prepare download

# Or compile the digest-pinned Rust source with your local toolchain.
gomonty prepare build

The same operation is available from Go:

prepared, err := monty.Prepare(ctx, monty.PrepareOptions{
	Mode: monty.PrepareDownload, // or monty.PrepareBuild
})

prepare download requires HTTPS and verifies the archive SHA-256 before extracting it. It then verifies the size and SHA-256 of both the library and worker. prepare build verifies the complete native source digest before running the build script, enforces the manifest-pinned Rust and Cargo versions and target standard library, then records the locally built files' hashes. This mode deliberately trusts the caller's local Python, linker, and SDK; local builds are not required to reproduce CI output byte-for-byte.

Published GNU/Linux downloads require glibc 2.35 or newer. They are built and executed on both amd64 and arm64 Ubuntu 22.04 runners, and release assembly rejects either native file when its imported GLIBC symbol version exceeds that declared floor. Musl downloads do not use glibc. Users on an older GNU system can choose prepare build to compile against their host instead.

Both modes use a cross-process lock and atomic staging. Before every Dlopen or worker initialization, the loader rechecks the receipt and hashes of both files. Missing, changed, extra, symlinked, or mismatched files fail closed with ErrRuntimeNotPrepared or ErrRuntimeIntegrity. The GOMONTY_CACHE_DIR environment variable selects an alternate cache root without disabling checks.

The verification boundary protects against accidental corruption, wrong release assets, and unreviewed binary substitution in distribution. It is not code signing and does not defend against a privileged local attacker able to modify the application process or cache during use. Monty's subprocess boundary is also not an OS sandbox.

Build preparation additionally requires Rust and Cargo 1.95.0, the manifest's Rust target, and Python on PATH (or PYO3_PYTHON). PrepareBuild overrides a caller-supplied RUSTUP_TOOLCHAIN, verifies the actual compiler versions, and fails with the exact rustup target add command when the target standard library is absent. Linux chooses GNU/glibc or musl by inspecting the running system's ELF interpreter; users do not need a special Go build tag. The standard CARGO_TARGET_DIR environment variable is respected when callers want to reuse or isolate Cargo's compilation cache:

gomonty prepare build
go test ./...

Consumer Example

After explicit preparation, import and use the library normally:

package main

import (
	"context"
	"fmt"
	"log"

	monty "github.com/regularkevvv/gomonty"
)

func main() {
	runner, err := monty.New("40 + 2", monty.CompileOptions{
		ScriptName: "example.py",
	})
	if err != nil {
		log.Fatal(err)
	}

	value, err := runner.Run(context.Background(), monty.RunOptions{})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(value.Raw())
}

The same example lives in examples/cmd/example. To run it from this repository checkout:

go run ./cmd/gomonty prepare build --source .
cd examples
CGO_ENABLED=0 go run ./cmd/example

Benchmarks

The Go benchmark suite mirrors the current upstream Monty benchmark cases so the two projects exercise the same scripts and expected outputs. The shared kitchen-sink workload is copied into testdata/bench_kitchen_sink.py.

With a native runtime prepared, run the local Go-only benchmarks with:

CGO_ENABLED=0 go test -run '^$' -bench BenchmarkMonty -benchmem

This covers the parse-once/repeated-run benchmark cases plus BenchmarkMontyEndToEnd for parse-and-run in the loop.

There are also Go-specific benchmark suites for wrapper overhead:

CGO_ENABLED=0 go test -run '^$' -bench BenchmarkMontyCallbacks -benchmem
CGO_ENABLED=0 go test -run '^$' -bench BenchmarkMontyDecompose -benchmem

These add:

  • callback-heavy runs with repeated external function and OS handler calls
  • low-level decomposition benchmarks for compile-only, dump/load, start-to-first-progress, name lookup, call resume, and pending resume paths

To capture CPU and allocation profiles for the representative hot paths, run:

scripts/profile-benchmarks.sh

By default the script writes profiles and pprof -top summaries to /tmp/gomonty-bench-profiles for:

  • BenchmarkMontyEndToEnd
  • BenchmarkMonty/list_append_int
  • BenchmarkMontyCallbacks/external_loop

To compare gomonty against a local upstream Monty checkout on the same host, run:

python3 scripts/compare-benchmarks.py --upstream ../monty

The comparison script:

  • runs the Go benchmark suite and aggregates the median ns/op across three runs
  • runs the upstream Criterion __monty benchmarks
  • sets PYO3_PYTHON for the upstream run if the upstream checkout still expects a local .venv/bin/python3
  • prints a Markdown table suitable for pasting back into this README

The previous sample table measured the retired in-process v0.0.9 binding and is intentionally not retained: subprocess startup, checkout reuse, and protocol round trips make those numbers inapplicable to the v0.0.19 architecture. Run the comparison script on the target host before publishing new results.

Fuzzing

The repo also includes Go fuzz targets for:

  • FuzzValueJSON: pure-Go value wire-format decoding and normalization
  • FuzzCompileAndRun: arbitrary source strings compiled and executed with tight resource limits
  • FuzzLoadRunner: arbitrary bytes fed through LoadRunner, including valid dumped-runner seeds

Run a short fuzzing pass with:

CGO_ENABLED=0 go test -run '^$' -fuzz FuzzValueJSON -fuzztime=10s .
CGO_ENABLED=0 go test -run '^$' -fuzz FuzzCompileAndRun -fuzztime=10s .
CGO_ENABLED=0 go test -run '^$' -fuzz FuzzLoadRunner -fuzztime=10s .

The native runner fuzzers require a prepared native runtime and run with CGO_ENABLED=0. FuzzValueJSON remains pure Go.

Upstream Overrides

The default build uses pinned git dependencies on https://github.com/pydantic/monty.git. For local development against a sibling checkout, you can temporarily override them with a Cargo patch:

[patch."https://github.com/pydantic/monty.git"]
monty = { path = "../monty/crates/monty" }
monty-pool = { path = "../monty/crates/monty-pool" }
monty-proto = { path = "../monty/crates/monty-proto" }
monty-types = { path = "../monty/crates/monty-types" }
monty-type-checking = { path = "../monty/crates/monty-type-checking" }

See RELEASING.md for bumping the upstream pin and for the exact-byte native runtime release flow.

Documentation

Overview

Package monty exposes cgo-free Go bindings for the Monty Python interpreter.

The package provides compiled runner and REPL APIs, typed value conversion, host callback dispatch, and low-level pause/resume snapshots. Native code is prepared explicitly with Prepare or the gomonty command, verified before every load, and then loaded with purego. Normal execution never downloads or builds code automatically.

For Go-owned filesystem and environment callbacks, use the companion vfs package.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrRuntimeNotPrepared means no verified runtime exists in the local cache.
	ErrRuntimeNotPrepared = runtimebundle.ErrNotPrepared
	// ErrRuntimeIntegrity means native source, release bytes, a build receipt,
	// or cached runtime bytes failed verification.
	ErrRuntimeIntegrity = runtimebundle.ErrIntegrity
	// ErrRuntimeUnsupported means the current platform has no runtime asset.
	ErrRuntimeUnsupported = runtimebundle.ErrUnsupported
	// ErrRuntimeBuildPrerequisite means PrepareBuild could not prove that the
	// manifest-pinned Rust compiler and target are available locally.
	ErrRuntimeBuildPrerequisite = runtimebundle.ErrBuildPrerequisite
)
View Source 
var (
	// ErrClosed reports that a handle-backed object no longer owns a native handle.
	ErrClosed = errors.New("monty handle is closed")
	// ErrConcurrentUse reports that the same handle-backed object is already being used.
	ErrConcurrentUse = errors.New("monty handle is already in use")
)

Functions

func IsRuntimeUnavailable 

func IsRuntimeUnavailable(err error) bool

IsRuntimeUnavailable reports errors caused by a missing, corrupt, or unsupported native runtime.

func LoadReplSnapshot 

func LoadReplSnapshot(data []byte) (Progress, *Repl, error)

LoadReplSnapshot restores a serialized REPL snapshot and also returns its owning REPL. The REPL remains single-flight until the snapshot completes or is abandoned.

Types

type AssertMessageAnnotations 

type AssertMessageAnnotations uint32

AssertMessageAnnotations is Monty's per-operand UTF-8 byte cap for enhanced assertion messages. A value of zero disables annotations and restores CPython's empty message for a bare failing assert.

CompileOptions and ReplOptions use a pointer so nil retains Monty's default (currently 120 bytes), while a pointer to zero explicitly disables the feature.

type BuiltinFunction 

type BuiltinFunction struct {
	Name string `json:"name"`
}

BuiltinFunction identifies an interpreter-native Python builtin.

type Call 

type Call struct {
	FunctionName string
	Args         []Value
	Kwargs       Dict
	CallID       uint32
	IsMethodCall bool
}

Call describes an external function or method invocation from Monty.

type CompileOptions 

type CompileOptions struct {
	ScriptName               string
	Inputs                   []string
	TypeCheck                bool
	TypeCheckStubs           string
	AssertMessageAnnotations *AssertMessageAnnotations
}

CompileOptions configures runner compilation.

type Complete 

type Complete struct {
	Output     Value
	ScriptName string
	IsRepl     bool
}

Complete is a finished execution result.

type Cycle 

type Cycle struct {
	ID          uint64 `json:"id"`
	Placeholder string `json:"placeholder"`
}

Cycle identifies a repeated object within one converted result. ID is opaque and meaningful only for equality inside that result.

type Dataclass 

type Dataclass struct {
	Name       string                   `json:"name"`
	TypeID     uint64                   `json:"type_id"`
	FieldNames []string                 `json:"field_names"`
	Attrs      Dict                     `json:"attrs"`
	Frozen     bool                     `json:"frozen"`
	Methods    map[string]MethodHandler `json:"-"`
}

Dataclass is the explicit host-side dataclass value shape.

Methods are host-only metadata and are intentionally omitted from the wire format so Rust never stores Go function pointers or opaque Go values.

type Date 

type Date struct {
	Year  int32 `json:"year"`
	Month uint8 `json:"month"`
	Day   uint8 `json:"day"`
}

Date represents a Python datetime.date value.

type DateTime 

type DateTime struct {
	Year          int32   `json:"year"`
	Month         uint8   `json:"month"`
	Day           uint8   `json:"day"`
	Hour          uint8   `json:"hour"`
	Minute        uint8   `json:"minute"`
	Second        uint8   `json:"second"`
	Microsecond   uint32  `json:"microsecond"`
	OffsetSeconds *int32  `json:"offset_seconds,omitempty"`
	TimezoneName  *string `json:"timezone_name,omitempty"`
}

DateTime represents a Python datetime.datetime value.

type Dict 

type Dict []Pair

Dict preserves insertion order and non-string keys.

type Exception 

type Exception struct {
	Type string  `json:"exc_type"`
	Arg  *string `json:"arg,omitempty"`
}

Exception is both a first-class Monty value and the explicit exception shape returned by host callbacks.

func (Exception) Error 

func (e Exception) Error() string

Error formats the exception as `Type: message`.

func (Exception) FromError 

func (e Exception) FromError(err error) Exception

FromError converts an arbitrary Go error into an explicit exception shape.

type ExternalFunction 

type ExternalFunction func(context.Context, Call) (Result, error)

ExternalFunction handles a host external function callback.

type FeedOptions 

type FeedOptions struct {
	Inputs        map[string]Value
	Functions     map[string]ExternalFunction
	OS            OSHandler
	Print         PrintCallback
	SkipTypeCheck bool
}

FeedOptions configures the high-level REPL helper loop.

type FeedStartOptions 

type FeedStartOptions struct {
	Inputs        map[string]Value
	SkipTypeCheck bool
}

FeedStartOptions configures low-level REPL snippet execution.

type FileHandle 

type FileHandle struct {
	Path     Path   `json:"path"`
	Mode     string `json:"mode"`
	Position uint64 `json:"position"`
}

FileHandle is Monty's serializable virtual file state. It never contains a host file descriptor or host path.

type Frame 

type Frame struct {
	Filename     string  `json:"filename"`
	Line         uint32  `json:"line"`
	Column       uint32  `json:"column"`
	EndLine      uint32  `json:"end_line"`
	EndColumn    uint32  `json:"end_column"`
	FunctionName *string `json:"function_name,omitempty"`
	SourceLine   *string `json:"source_line,omitempty"`
}

Frame is a structured traceback frame returned by runtime and syntax errors.

type FrozenSet 

type FrozenSet []Value

FrozenSet is the explicit frozenset shape used by the bindings.

type Function 

type Function struct {
	Name      string  `json:"name"`
	Docstring *string `json:"docstring,omitempty"`
}

Function is the explicit external-function value used during name lookup.

type FutureSnapshot 

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

FutureSnapshot is a paused future-resolution state.

func (*FutureSnapshot) Dump 

func (s *FutureSnapshot) Dump() ([]byte, error)

Dump serializes the current future snapshot.

func (*FutureSnapshot) PendingCallIDs 

func (s *FutureSnapshot) PendingCallIDs() []uint32

PendingCallIDs returns the unresolved call IDs for the future snapshot.

func (*FutureSnapshot) ResumeResults 

func (s *FutureSnapshot) ResumeResults(ctx context.Context, results map[uint32]Result) (Progress, error)

ResumeResults resumes a future snapshot with zero or more resolved call IDs.

func (*FutureSnapshot) WorkerPID 

func (s *FutureSnapshot) WorkerPID() (int, bool)

WorkerPID returns the local worker process ID currently owning this paused execution. The value is diagnostic and may change after restore/recovery.

type HTTPDoer 

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPDoer is the minimal download transport used by PrepareDownload.

type MethodHandler 

type MethodHandler = ExternalFunction

MethodHandler handles a host dataclass method callback.

type NameLookupSnapshot 

type NameLookupSnapshot struct {
	VariableName string
	// contains filtered or unexported fields
}

NameLookupSnapshot is a paused unresolved-name lookup.

func (*NameLookupSnapshot) Dump 

func (s *NameLookupSnapshot) Dump() ([]byte, error)

Dump serializes the current name-lookup snapshot.

func (*NameLookupSnapshot) ResumeUndefined 

func (s *NameLookupSnapshot) ResumeUndefined(ctx context.Context) (Progress, error)

ResumeUndefined resumes a name lookup as undefined.

func (*NameLookupSnapshot) ResumeValue 

func (s *NameLookupSnapshot) ResumeValue(ctx context.Context, value Value) (Progress, error)

ResumeValue resumes a name lookup with a resolved value.

func (*NameLookupSnapshot) WorkerPID 

func (s *NameLookupSnapshot) WorkerPID() (int, bool)

WorkerPID returns the local worker process ID currently owning this paused execution. The value is diagnostic and may change after restore/recovery.

type NamedTuple 

type NamedTuple struct {
	TypeName   string   `json:"type_name"`
	FieldNames []string `json:"field_names"`
	Values     []Value  `json:"values"`
}

NamedTuple carries the explicit named-tuple wire shape.

type OSCall 

type OSCall struct {
	Function OSFunction
	Args     []Value
	Kwargs   Dict
	CallID   uint32
}

OSCall describes an OS-level callback requested by Monty.

type OSFunction 

type OSFunction string

OSFunction names a host OS callback that Monty requested. 

const (
	OSPathExists      OSFunction = "Path.exists"
	OSPathIsFile      OSFunction = "Path.is_file"
	OSPathIsDir       OSFunction = "Path.is_dir"
	OSPathIsSymlink   OSFunction = "Path.is_symlink"
	OSPathReadText    OSFunction = "Path.read_text"
	OSPathReadBytes   OSFunction = "Path.read_bytes"
	OSPathWriteText   OSFunction = "Path.write_text"
	OSPathAppendText  OSFunction = "Path.append_text"
	OSPathWriteBytes  OSFunction = "Path.write_bytes"
	OSPathAppendBytes OSFunction = "Path.append_bytes"
	OSPathMkdir       OSFunction = "Path.mkdir"
	OSPathUnlink      OSFunction = "Path.unlink"
	OSPathRmdir       OSFunction = "Path.rmdir"
	OSPathIterdir     OSFunction = "Path.iterdir"
	OSPathStat        OSFunction = "Path.stat"
	OSPathRename      OSFunction = "Path.rename"
	OSPathResolve     OSFunction = "Path.resolve"
	OSPathAbsolute    OSFunction = "Path.absolute"
	OSGetenv          OSFunction = "os.getenv"
	OSGetEnviron      OSFunction = "os.environ"
	OSOpen            OSFunction = "open"
	OSDateToday       OSFunction = "date.today"
	OSDateTimeNow     OSFunction = "datetime.now"
)

type OSHandler 

type OSHandler func(context.Context, OSCall) (Result, error)

OSHandler handles a host OS callback.

type Pair 

type Pair struct {
	Key   Value `json:"key"`
	Value Value `json:"value"`
}

Pair preserves insertion order and non-string keys for dict-like values.

type Path 

type Path string

Path is an explicit Monty path value.

type PrepareMode 

type PrepareMode string

PrepareMode selects how the native runtime is explicitly acquired. 

const (
	// PrepareDownload downloads the exact release asset named in the committed
	// manifest and verifies the archive, shared library, and worker hashes.
	PrepareDownload PrepareMode = "download"
	// PrepareBuild builds the reviewed Rust source locally and accepts the
	// output only after recording hashes that the loader will recheck.
	PrepareBuild PrepareMode = "build"
)

type PrepareOptions 

type PrepareOptions struct {
	Mode PrepareMode

	// SourceDir selects the GoMonty source tree for PrepareBuild. When empty,
	// the source tree containing this package is used, including from a Go
	// module cache.
	SourceDir string

	// ReleaseBaseURL is an optional HTTPS mirror for PrepareDownload. The
	// committed file and archive hashes remain authoritative.
	ReleaseBaseURL string

	// HTTPClient optionally supplies transport policy for PrepareDownload.
	// Redirects and TLS behavior are the caller's responsibility when set.
	HTTPClient HTTPDoer
}

PrepareOptions configures an explicit native-runtime preparation. Normal execution never performs either operation automatically.

type PreparedRuntime 

type PreparedRuntime struct {
	RuntimeVersion string      `json:"runtime_version"`
	Target         string      `json:"target"`
	Mode           PrepareMode `json:"mode"`
	RustToolchain  string      `json:"rust_toolchain"`
}

PreparedRuntime reports the verified installation selected for this process.

func Prepare 

func Prepare(ctx context.Context, options PrepareOptions) (PreparedRuntime, error)

Prepare explicitly acquires, verifies, and atomically caches the current native runtime. It does not load the library or execute the worker.

func Prepared 

func Prepared() (PreparedRuntime, error)

Prepared verifies the cached native runtime without downloading, building, loading, or starting anything.

type PrintCallback 

type PrintCallback func(stream string, text string)

PrintCallback receives aggregated stdout text emitted during each execution step.

func WriterPrintCallback 

func WriterPrintCallback(w io.Writer) PrintCallback

WriterPrintCallback writes captured stdout to an io.Writer.

type Progress 

type Progress interface {
	// contains filtered or unexported methods
}

Progress is the low-level pause/resume execution interface.

func LoadSnapshot 

func LoadSnapshot(data []byte) (Progress, error)

LoadSnapshot restores a serialized non-REPL or REPL snapshot without an owner REPL.

type Repl 

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

Repl is a stateful Monty REPL session.

func LoadRepl 

func LoadRepl(data []byte) (*Repl, error)

LoadRepl restores an idle REPL session previously serialized by Repl.Dump.

func NewRepl 

func NewRepl(opts ReplOptions) (*Repl, error)

NewRepl constructs an empty REPL session.

func (*Repl) Close 

func (r *Repl) Close() error

Close releases an idle REPL session and returns its worker to the internal pool. A REPL with an in-flight feed must be abandoned through its snapshot.

func (*Repl) Dump 

func (r *Repl) Dump() ([]byte, error)

Dump serializes the REPL session.

func (*Repl) FeedRun 

func (r *Repl) FeedRun(ctx context.Context, code string, opts FeedOptions) (Value, error)

FeedRun executes a REPL snippet through the high-level host callback loop.

func (*Repl) FeedStart 

func (r *Repl) FeedStart(ctx context.Context, code string, opts FeedStartOptions) (Progress, error)

FeedStart begins low-level REPL snippet execution.

func (*Repl) WorkerPID 

func (r *Repl) WorkerPID() (int, bool)

WorkerPID returns the current local Monty worker process ID. It is intended for diagnostics and crash-isolation tests; callers must not treat it as a stable session identifier.

type ReplOptions 

type ReplOptions struct {
	ScriptName               string
	Limits                   *ResourceLimits
	TypeCheck                bool
	TypeCheckStubs           string
	AssertMessageAnnotations *AssertMessageAnnotations
}

ReplOptions configures REPL construction.

type ResourceLimits 

type ResourceLimits struct {
	// MaxAllocations is retained for source compatibility. Monty v0.0.19 no
	// longer exposes an allocation-count limit, so this field is not enforced.
	// Deprecated: use MaxMemory and MaxDuration.
	MaxAllocations    int
	MaxDuration       time.Duration
	MaxMemory         int
	GCInterval        int
	MaxRecursionDepth int
}

ResourceLimits controls Monty execution limits.

A zero field value leaves that limit unset.

type Result 

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

Result is the explicit host callback result union.

The zero value is treated as `Return(None())`, which keeps simple handlers ergonomic while preserving an explicit pending/exception path.

func Pending 

func Pending(waiter Waiter) Result

Pending constructs a callback result backed by a waiter.

func Raise 

func Raise(exception Exception) Result

Raise constructs a callback result that raises an explicit exception.

func Return 

func Return(value Value) Result

Return constructs a successful callback result.

func (Result) IsPending 

func (r Result) IsPending() bool

IsPending reports whether the result is pending.

func (Result) Raised 

func (r Result) Raised() (*Exception, bool)

Raised returns the explicit exception payload for an exception result.

func (Result) Value 

func (r Result) Value() Value

Value returns the success value for a return result.

func (Result) Waiter 

func (r Result) Waiter() Waiter

Waiter returns the waiter attached to a pending result.

type RunOptions 

type RunOptions struct {
	Inputs    map[string]Value
	Functions map[string]ExternalFunction
	OS        OSHandler
	Print     PrintCallback
	Limits    *ResourceLimits
}

RunOptions configures the high-level runner helper loop.

type Runner 

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

Runner is the compiled runner entrypoint for Monty code.

func LoadRunner 

func LoadRunner(data []byte) (*Runner, error)

LoadRunner restores a serialized runner.

func New 

func New(code string, opts CompileOptions) (*Runner, error)

New compiles Monty code into a reusable runner.

func (*Runner) Close 

func (r *Runner) Close() error

Close releases the native runner handle. It is safe to call more than once.

func (*Runner) Dump 

func (r *Runner) Dump() ([]byte, error)

Dump serializes the runner.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context, opts RunOptions) (Value, error)

Run executes the runner through the high-level host callback loop.

Example 
package main

import (
	"context"
	"fmt"

	monty "github.com/regularkevvv/gomonty"
)

func main() {
	runner, err := monty.New("40 + 2", monty.CompileOptions{
		ScriptName: "example.py",
	})
	if err != nil {
		panic(err)
	}

	value, err := runner.Run(context.Background(), monty.RunOptions{})
	if err != nil {
		panic(err)
	}

	fmt.Println(value.Raw())
}

Output:
42

func (*Runner) Start 

func (r *Runner) Start(ctx context.Context, opts StartOptions) (Progress, error)

Start begins low-level runner execution.

func (*Runner) TypeCheck 

func (r *Runner) TypeCheck(prefix string) error

TypeCheck runs static type checking on the compiled runner.

type RuntimeError 

type RuntimeError struct {
	Frames []Frame
	// contains filtered or unexported fields
}

RuntimeError is raised for runtime failures and exposes traceback frames.

func (*RuntimeError) Error 

func (e *RuntimeError) Error() string

func (*RuntimeError) TracebackString 

func (e *RuntimeError) TracebackString() string

func (*RuntimeError) Unwrap 

func (e *RuntimeError) Unwrap() error

type Set 

type Set []Value

Set is the explicit set shape used by the bindings.

type Snapshot 

type Snapshot struct {
	FunctionName string
	Args         []Value
	Kwargs       Dict
	CallID       uint32
	IsOSFunction bool
	IsMethodCall bool
	// contains filtered or unexported fields
}

Snapshot is a paused external function, method call, or OS call.

func (*Snapshot) Dump 

func (s *Snapshot) Dump() ([]byte, error)

Dump serializes the current snapshot.

func (*Snapshot) ResumeException 

func (s *Snapshot) ResumeException(ctx context.Context, exception Exception) (Progress, error)

ResumeException resumes a function or OS snapshot by raising an exception.

func (*Snapshot) ResumePending 

func (s *Snapshot) ResumePending(ctx context.Context) (Progress, error)

ResumePending resumes a function or OS snapshot with a pending future.

func (*Snapshot) ResumeReturn 

func (s *Snapshot) ResumeReturn(ctx context.Context, value Value) (Progress, error)

ResumeReturn resumes a function or OS snapshot with a return value.

func (*Snapshot) WorkerPID 

func (s *Snapshot) WorkerPID() (int, bool)

WorkerPID returns the local worker process ID currently owning this paused execution. The value is diagnostic and may change after restore/recovery.

type StartOptions 

type StartOptions struct {
	Inputs map[string]Value
	Limits *ResourceLimits
}

StartOptions configures low-level runner execution.

type StatResult 

type StatResult struct {
	Mode  int64
	Ino   int64
	Dev   int64
	Nlink int64
	UID   int64
	GID   int64
	Size  int64
	Atime float64
	Mtime float64
	Ctime float64
}

StatResult is the explicit host helper for `os.stat_result`-compatible values.

type SyntaxError 

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

SyntaxError is raised for parse or compile failures.

func (*SyntaxError) Error 

func (e *SyntaxError) Error() string

func (*SyntaxError) TracebackString 

func (e *SyntaxError) TracebackString() string

func (*SyntaxError) Unwrap 

func (e *SyntaxError) Unwrap() error

type TimeDelta 

type TimeDelta struct {
	Days         int32 `json:"days"`
	Seconds      int32 `json:"seconds"`
	Microseconds int32 `json:"microseconds"`
}

TimeDelta represents a Python datetime.timedelta value.

type TimeZone 

type TimeZone struct {
	OffsetSeconds int32   `json:"offset_seconds"`
	Name          *string `json:"name,omitempty"`
}

TimeZone represents a Python datetime.timezone fixed-offset value.

type Tuple 

type Tuple []Value

Tuple is the explicit tuple shape used by the bindings.

type Type 

type Type struct {
	Name     string `json:"name"`
	Instance bool   `json:"instance,omitempty"`
}

Type is a Python type object returned by Monty. Instance is true for a sandbox-defined class; those values are output-only.

type TypingError 

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

TypingError is raised for static type-check failures and can re-render the diagnostics using the formatter strings supported by Rust.

func (*TypingError) Display 

func (e *TypingError) Display(format string, color bool) string

Display renders the typing diagnostics using one of Rust's formatter names: `full`, `concise`, `azure`, `json`, `jsonlines`, `rdjson`, `pylint`, `gitlab`, or `github`.

func (*TypingError) Error 

func (e *TypingError) Error() string

func (*TypingError) TracebackString 

func (e *TypingError) TracebackString() string

func (*TypingError) Unwrap 

func (e *TypingError) Unwrap() error

type Value 

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

Value is the public tagged union used by the Go bindings.

Primitive Go values round-trip directly where safe: `nil`, `bool`, signed integers, `float64`, `string`, and `[]byte`. Non-native Monty shapes remain explicit through helper structs such as Dict, Tuple, NamedTuple, Path, Dataclass, Function, and Exception.

func BigInt 

func BigInt(value *big.Int) Value

BigInt returns an arbitrary-precision integer value.

func Bool 

func Bool(value bool) Value

Bool returns a bool value.

func BuiltinFunctionValue 

func BuiltinFunctionValue(value BuiltinFunction) Value

BuiltinFunctionValue returns an interpreter-native builtin function value.

func Bytes 

func Bytes(value []byte) Value

Bytes returns a bytes value.

func CycleRefValue 

func CycleRefValue(value Cycle) Value

CycleRefValue returns an output-only cycle reference with its opaque identity.

func CycleValue 

func CycleValue(value string) Value

CycleValue returns an output-only cycle placeholder.

func DataclassValue 

func DataclassValue(value Dataclass) Value

DataclassValue returns a dataclass value.

func DateTimeValue 

func DateTimeValue(dt DateTime) Value

DateTimeValue returns a datetime value.

func DateValue 

func DateValue(date Date) Value

DateValue returns a date value.

func DictValue 

func DictValue(items Dict) Value

DictValue returns a dict value.

func Ellipsis 

func Ellipsis() Value

Ellipsis returns the Python Ellipsis value.

func ExceptionValue 

func ExceptionValue(exception Exception) Value

ExceptionValue returns an exception value.

func FileHandleValue 

func FileHandleValue(value FileHandle) Value

FileHandleValue returns serializable virtual file state.

func Float 

func Float(value float64) Value

Float returns a float value.

func FrozenSetValue 

func FrozenSetValue(items FrozenSet) Value

FrozenSetValue returns a frozenset value.

func FunctionValue 

func FunctionValue(function Function) Value

FunctionValue returns an external-function value.

func Int 

func Int(value int64) Value

Int returns a signed integer value.

func List 

func List(items ...Value) Value

List returns a list value.

func MustValueOf 

func MustValueOf(value any) Value

MustValueOf converts a Go value and panics if conversion fails.

func NamedTupleValue 

func NamedTupleValue(value NamedTuple) Value

NamedTupleValue returns a named-tuple value.

func None 

func None() Value

None returns the Python None value.

func PathValue 

func PathValue(path Path) Value

PathValue returns a path value.

func ReprValue 

func ReprValue(value string) Value

ReprValue returns an output-only repr placeholder.

func SetValue 

func SetValue(items Set) Value

SetValue returns a set value.

func String 

func String(value string) Value

String returns a string value.

func TimeDeltaValue 

func TimeDeltaValue(td TimeDelta) Value

TimeDeltaValue returns a timedelta value.

func TimeZoneValue 

func TimeZoneValue(tz TimeZone) Value

TimeZoneValue returns a timezone value.

func TupleValue 

func TupleValue(items ...Value) Value

TupleValue returns a tuple value.

func TypeValue 

func TypeValue(value Type) Value

TypeValue returns a Python type object. Sandbox-defined instance types are output-only and will be rejected if supplied back as interpreter input.

func ValueOf 

func ValueOf(value any) (Value, error)

ValueOf converts a supported Go value into a Monty Value.

func (Value) BuiltinFunction 

func (v Value) BuiltinFunction() (BuiltinFunction, bool)

BuiltinFunction returns the builtin-function payload if present.

func (Value) Cycle 

func (v Value) Cycle() (Cycle, bool)

Cycle returns the cycle-reference payload if present.

func (Value) Dataclass 

func (v Value) Dataclass() (Dataclass, bool)

Dataclass returns the dataclass payload if present.

func (Value) Date 

func (v Value) Date() (Date, bool)

Date returns the date payload if present.

func (Value) DateTime 

func (v Value) DateTime() (DateTime, bool)

DateTime returns the datetime payload if present.

func (Value) Exception 

func (v Value) Exception() (Exception, bool)

Exception returns the exception payload if present.

func (Value) FileHandle 

func (v Value) FileHandle() (FileHandle, bool)

FileHandle returns the virtual file payload if present.

func (Value) Function 

func (v Value) Function() (Function, bool)

Function returns the function payload if present.

func (Value) Kind 

func (v Value) Kind() ValueKind

Kind reports the value variant.

func (Value) MarshalJSON 

func (v Value) MarshalJSON() ([]byte, error)

func (Value) Raw 

func (v Value) Raw() any

Raw exposes the underlying variant payload.

func (Value) StatResult 

func (v Value) StatResult() (StatResult, bool)

StatResult returns a stat-result payload when the value is a compatible named tuple.

func (Value) String 

func (v Value) String() string

func (Value) TimeDelta 

func (v Value) TimeDelta() (TimeDelta, bool)

TimeDelta returns the timedelta payload if present.

func (Value) TimeZone 

func (v Value) TimeZone() (TimeZone, bool)

TimeZone returns the timezone payload if present.

func (Value) Type 

func (v Value) Type() (Type, bool)

Type returns the Python type payload if present.

func (*Value) UnmarshalJSON 

func (v *Value) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the stable Rust/Go wire schema for values.

type ValueKind 

type ValueKind string

ValueKind identifies the Monty value variant held by a Value.

type Waiter 

type Waiter interface {
	Wait(context.Context) Result
}

Waiter represents a pending external result that will be resolved later.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gomonty command
Command gomonty manages explicit setup tasks for the GoMonty library.
 Command gomonty manages explicit setup tasks for the GoMonty library.
internal
cmd/runtime-release command
ffi
runtimebundle
Package vfs adapts Go-defined filesystems and environments into Monty OS handlers.
 Package vfs adapts Go-defined filesystems and environments into Monty OS handlers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.