Skip to content

solvi.experimental.compile.sandbox

Code a model wrote, held to pure functions: an ast allowlist, a subprocess with limits under a trusted driver, and a restricted load into this process.

A sandbox for code a model wrote: only pure functions over facts.

from solvi.experimental.compile.sandbox import check, load, run
check(source)                                   # [] when allowed, else the reasons it is refused
ns = load(source)                               # the module's namespace, in this process (refuses what check refuses)
out = run(source, "mypkg.driver:main", payload) # the module run in a subprocess by a trusted driver → its JSON
outs = run_many(sources, "mypkg.driver:main", payload)   # many modules, one subprocess → a result per module

check and load are the stable solvi.core.versions._sandbox's since 1.1 (a catalog version's module is loaded the same way): see there for what they refuse. run executes the module in a fresh python -I subprocess: an empty environment, a scratch working directory, limits on memory (RLIMIT_AS; RLIMIT_DATA on macOS), CPU time and wall-clock time, the same restricted builtins. The driver — your code, never the model's — is imported before the module runs; it gets the module's namespace, the payload and the signal module (for a per-item alarm) and returns JSON. A module that does not load, a crash, a run over its limits come back as {"load_error": ...} or {"crash": ...}; a failure of the sandbox itself (the interpreter, the driver, a limit) as {"sandbox_error": ...} — never as the module's.

run_many runs many modules in one subprocess (the interpreter starts once), each with its own limits on CPU and wall time, and gives each its own result; a module that ends the process (a CPU limit, memory, a crash) is reported as {"crash": ...} and the modules after it run in a fresh subprocess. The modules of one batch share the process: a module that changes an allowed standard-library module (math.pi = 3) changes it for the modules after it — use run for one you do not trust that far.

What it does not do: the limits hold in run and run_many only; once loaded into your process a module is held by the checks alone.

Refused

Refused(reasons)

Bases: ValueError

The module breaks the sandbox's rules; .reasons lists each one with its line.

SandboxWarning

Bases: UserWarning

The sandbox ran without one of its limits (the platform refused it): the module's run is not held by it.

check

check(source: str, allowed=()) -> list[str]

The reasons the sandbox refuses this module, each with its line ([] — allowed). allowed: more modules it may import, beyond ALLOWED (top-level names; never a forbidden one). See the module docs.

load

load(source: str, extra: dict | None = None, allowed=()) -> dict

Execute an allowed module in this process → its namespace. Raises Refused with the reasons when check refuses it. extra: names put into the namespace before it runs (trusted helpers such as Fail). allowed: more modules it may import, as for check.

safe_builtins

safe_builtins(allowed=())

The builtins a sandboxed module sees: the forbidden names removed, __import__ admitting ALLOWED (and allowed) only.

source_name

source_name(source: str) -> str

The file name a module is compiled under: <solvi-sandbox-<sha256 prefix>>, the same for the same text.

set_limits

set_limits(mem: int, cpu: int | None, platform: str | None = None) -> list

Set the child's limits: memory mem bytes, CPU time cpu seconds → notes on what could not be set. Memory is RLIMIT_AS (the address space) on Linux; on macOS RLIMIT_DATA, because there RLIMIT_AS below the address space the interpreter has already reserved raises ValueError("current limit exceeds maximum limit") — every limit under tens of gigabytes would. A memory limit the platform refuses is skipped and noted (the run goes on: not the module's fault); the CPU limit is required (cpu=None: not set here — run_many sets one per module).

run

run(source: str, driver: str, payload, *, mem_mb: int = 1024, cpu_s: int = 300, wall_s: int = 600, path=(), allowed=()) -> dict

Run the module in a subprocess under driver ("package.module:function": trusted code, importable in the child from solvi's own folder or the folders in path; it gets (namespace, payload, signal) and returns JSON) → the driver's result, {"load_error": reason} when the module is refused or does not load, {"crash": reason} (a crash, a limit, no result), or {"sandbox_error": reason} when the sandbox itself failed — the interpreter did not start, the driver did not import, a required limit could not be set: not the module's failure. A memory limit the platform refuses is skipped with a SandboxWarning (see set_limits). The driver module's SANDBOX_EXTRA dict, if any, is put into the namespace. allowed: more modules the module may import, beyond ALLOWED (as for check).

run_many

run_many(sources, driver: str, payload, *, mem_mb: int = 1024, cpu_s: int = 300, wall_s: int = 600, path=(), allowed=()) -> list

run for many modules in one subprocess → a result per module, in order, each what run would give for it: the driver's result, {"load_error"}, {"crash"} (the driver raised, or the module ended the process) or {"sandbox_error"}. Every module is loaded into its own namespace and gets cpu_s seconds of CPU and wall_s seconds of wall time from its start (the driver's per-item alarm as in run); mem_mb holds the whole process. A module that ends the process or runs over wall_s is a crash, and the modules after it run in a fresh subprocess. The modules of a batch share the process (see the module docs).