dspy.PythonInterpreter
Deno Installation
PythonInterpreter uses Deno and Pyodide to run Python in a local WASM sandbox. The recommended installation keeps Deno in the same Python environment as DSPy:
The deno extra installs the official Deno Python distribution (>=2.4.5,<3.0.0). DSPy prefers that managed binary when it is installed, so Python dependency locking also locks the Deno runtime. The extra provides binaries for macOS x86-64/arm64, glibc Linux x86-64/arm64, and Windows x86-64 and adds approximately 40–50 MiB to the environment.
On other platforms, install a compatible Deno 2.x release (>=2.0.0,<3.0.0) using the Deno installation instructions. DSPy falls back to the deno executable on PATH. An explicit deno_command passed to PythonInterpreter takes precedence over both options.
DSPy disables ambient deno.json, lockfile, package.json, and local node_modules discovery for its default runner. A package.json in the current directory or an ancestor therefore cannot redirect the sandbox’s pinned Pyodide dependency. No DENO_NO_PACKAGE_JSON environment variable is required.
Startup
Pyodide normally compiles each module of its standard library every time it starts. The first time a PythonInterpreter starts on a machine, DSPy byte-compiles Pyodide’s standard library once into $DSPY_CACHEDIR/sandbox (~/.dspy_cache/sandbox by default), and every later interpreter starts from it, in about a quarter of the time. If that cache can’t be written, interpreters start from Pyodide’s own standard library.
Where writing files is unwelcome, turn the cache off with PythonInterpreter(sandbox_cache=False), or for every interpreter, including those Flex and RLM make, with the environment variable DSPY_SANDBOX_CACHE=0. DSPy then writes nothing to $DSPY_CACHEDIR/sandbox, and Pyodide starts from its own standard library. Sandboxes that import dspy still need its bundle (below): each process builds its own in a temporary directory, removed when it exits.
provide_dspy() lets sandboxed code import dspy, with the host’s dspy source and Pyodide builds of its dependencies. dspy.Flex and dspy.RLM call it on the interpreters they create. Such an interpreter starts from a snapshot of one that has already imported dspy, which DSPy records once per dspy source, so it starts faster than a plain one. To start interpreters before they are needed, see InterpreterPool.
Execution Instructions
PythonInterpreter.execution_instructions describes stable constraints of its Pyodide execution environment. It is class metadata, so code-generating modules can inspect it without starting Deno or allocating an interpreter. RLM includes these instructions in its action prompt, which adapters render in the model’s system prompt.
Custom interpreter factories may expose their own execution_instructions string. This metadata is optional; a factory without it remains valid and uses RLM’s generic action prompt.
dspy.PythonInterpreter(deno_command: list[str] | None = None, enable_read_paths: list[PathLike | str] | None = None, enable_write_paths: list[PathLike | str] | None = None, enable_env_vars: list[str] | None = None, enable_network_access: list[str] | None = None, sync_files: bool = True, tools: dict[str, Callable[..., str]] | None = None, output_fields: list[dict] | None = None, callbacks: list[BaseCallback] | None = None, sandbox_cache: bool | None = None, sandbox_packages: Sequence[str] = ('pillow',))
Local interpreter for secure Python execution using Deno and Pyodide.
Implements the Interpreter protocol for secure code execution in a WASM-based sandbox. Code runs in an isolated Pyodide environment with no access to the host filesystem, network, or environment by default.
Prerequisites
Install the managed Deno runtime with pip install "dspy[deno]", or install a compatible Deno 2.x release system-wide.
Examples:
# Basic execution
with PythonInterpreter() as interp:
result = interp("print(1 + 2)") # Returns "3"
# With host-side tools
def my_tool(question: str) -> str:
return "answer"
with PythonInterpreter(tools={"my_tool": my_tool}) as interp:
result = interp("print(my_tool(question='test'))")
Parameters:
| Name | Type | Description | Default |
deno_command | list[str] | None | command list to launch Deno. | None |
enable_read_paths | list[PathLike | str] | None | Files or directories to allow reading from in the sandbox. | None |
enable_write_paths | list[PathLike | str] | None | Files or directories to allow writing to in the sandbox. All write paths will also be able to be read from for mounting. | None |
enable_env_vars | list[str] | None | Environment variable names to allow in the sandbox. | None |
enable_network_access | list[str] | None | Domains or IPs to allow network access in the sandbox. | None |
sync_files | bool | If set, syncs changes within the sandbox back to original files after execution. | True |
tools | dict[str, Callable[..., str]] | None | Dictionary mapping tool names to callable functions. Each function should accept keyword arguments and return a string. Tools are callable directly from sandbox code by name. | None |
output_fields | list[dict] | None | List of output field definitions for typed SUBMIT signature. Each dict should have ‘name’ and optionally ‘type’ keys. | None |
callbacks | list[BaseCallback] | None | Optional instance-level callback handlers. | None |
sandbox_cache | bool | None | Whether the interpreter may write DSPy’s sandbox cache in $DSPY_CACHEDIR/sandbox: a byte-compiled copy of Pyodide’s standard library, which interpreters start from about four times faster. With False nothing is written there, and Pyodide starts from its own standard library. A sandbox that imports dspy (provide_dspy) then gets its bundle built in a temporary directory. Defaults to the DSPY_SANDBOX_CACHE environment variable, where 0 turns it off. | None |
sandbox_packages | Sequence[str] | Packages Pyodide ships (by the names in its package list) that a sandbox with dspy (provide_dspy, as in dspy.RLM and dspy.Flex) gets, with what they need, so its code can import them. The default, Pillow, is what dspy.Image.to_pil() needs. () leaves it out, for a smaller bundle that starts a little faster; images still pass through the sandbox, and to_pil() raises ImportError. Each package makes the sandbox start a little slower. | ('pillow',) |
Source code in dspy/primitives/python_interpreter.py
| def __init__(
self,
deno_command: list[str] | None = None,
enable_read_paths: list[PathLike | str] | None = None,
enable_write_paths: list[PathLike | str] | None = None,
enable_env_vars: list[str] | None = None,
enable_network_access: list[str] | None = None,
sync_files: bool = True,
tools: dict[str, Callable[..., str]] | None = None,
output_fields: list[dict] | None = None,
callbacks: list[BaseCallback] | None = None,
sandbox_cache: bool | None = None,
sandbox_packages: Sequence[str] = ("pillow",),
) -> None:
"""
Args:
deno_command: command list to launch Deno.
enable_read_paths: Files or directories to allow reading from in the sandbox.
enable_write_paths: Files or directories to allow writing to in the sandbox.
All write paths will also be able to be read from for mounting.
enable_env_vars: Environment variable names to allow in the sandbox.
enable_network_access: Domains or IPs to allow network access in the sandbox.
sync_files: If set, syncs changes within the sandbox back to original files after execution.
tools: Dictionary mapping tool names to callable functions.
Each function should accept keyword arguments and return a string.
Tools are callable directly from sandbox code by name.
output_fields: List of output field definitions for typed SUBMIT signature.
Each dict should have 'name' and optionally 'type' keys.
callbacks: Optional instance-level callback handlers.
sandbox_cache: Whether the interpreter may write DSPy's sandbox cache in ``$DSPY_CACHEDIR/sandbox``: a
byte-compiled copy of Pyodide's standard library, which interpreters start from about four times
faster. With ``False`` nothing is written there, and Pyodide starts from its own standard library.
A sandbox that imports dspy (``provide_dspy``) then gets its bundle built in a temporary directory.
Defaults to the ``DSPY_SANDBOX_CACHE`` environment variable, where ``0`` turns it off.
sandbox_packages: Packages Pyodide ships (by the names in its package list) that a sandbox with dspy
(``provide_dspy``, as in ``dspy.RLM`` and ``dspy.Flex``) gets, with what they need, so its code can
import them. The default, Pillow, is what ``dspy.Image.to_pil()`` needs. ``()`` leaves it out, for
a smaller bundle that starts a little faster; images still pass through the sandbox, and
``to_pil()`` raises ``ImportError``. Each package makes the sandbox start a little slower.
"""
if isinstance(deno_command, dict):
raise TypeError("deno_command must be a list of strings, not a dict")
self.enable_read_paths = enable_read_paths or []
self.enable_write_paths = enable_write_paths or []
mounts = {}
for path in [*self.enable_read_paths, *self.enable_write_paths]:
if path:
virtual_path = os.path.basename(os.fspath(path))
host_path = _canonicalize_path(path)
if virtual_path in mounts and mounts[virtual_path] != host_path:
raise CodeInterpreterError("Mounted files must have unique basenames inside the sandbox.")
mounts[virtual_path] = host_path
self.enable_env_vars = enable_env_vars or []
self.enable_network_access = enable_network_access or []
self.sync_files = sync_files
self.tools = dict(tools) if tools else {}
self.output_fields = output_fields
self.callbacks = list(callbacks or [])
self.sandbox_cache = sandbox_cache_env_enabled() if sandbox_cache is None else sandbox_cache
if isinstance(sandbox_packages, str):
raise TypeError(f"sandbox_packages must be a list of package names, like [{sandbox_packages!r}]")
self.sandbox_packages = tuple(sandbox_packages)
self._tools_registered = False
# TODO later on add enable_run (--allow-run) by proxying subprocess.run through Deno.run() to fix 'emscripten does not support processes' error
self._uses_default_deno_command = not deno_command
if deno_command:
self.deno_command = list(deno_command)
else:
deno_executable = _find_deno_executable()
args = [
deno_executable,
"run",
"--no-config",
"--no-lock",
"--node-modules-dir=false",
]
# Also allow reading Deno's cache directory so Pyodide can load its files
deno_dir = self._get_deno_dir(deno_executable)
# The runtime: the runner, Deno's cache, and the archives Pyodide starts from.
protected = [
_canonicalize_path(self._get_runner_path()),
*([_canonicalize_path(deno_dir)] if deno_dir else []),
_canonicalize_path(bundle_root()),
]
if any(_paths_overlap(_canonicalize_path(path), item) for path in self.enable_write_paths for item in protected):
raise CodeInterpreterError("Write paths cannot overlap PythonInterpreter runtime files.")
raw_read_paths = [
self._get_runner_path(),
*([deno_dir] if deno_dir else []),
*self.enable_read_paths,
*self.enable_write_paths,
]
allowed_read_paths = [_canonicalize_path(p) for p in raw_read_paths]
args.append(f"--allow-read={','.join(allowed_read_paths)}")
self._env_arg = ""
if self.enable_env_vars:
user_vars = [str(v).strip() for v in self.enable_env_vars]
args.append("--allow-env=" + ",".join(user_vars))
self._env_arg = ",".join(user_vars)
if self.enable_network_access:
args.append(f"--allow-net={','.join(str(x) for x in self.enable_network_access)}")
if self.enable_write_paths:
args.append(f"--allow-write={','.join(_canonicalize_path(x) for x in self.enable_write_paths)}")
self._deno_run = args[:5]
self._deno_dir = _canonicalize_path(deno_dir) if deno_dir else None
self._runner = _canonicalize_path(self._get_runner_path())
args.append(_canonicalize_path(self._get_runner_path()))
# For runner.js to load in env vars and revoke cache access after startup
args.append(self._env_arg)
if deno_dir:
args.append(f"--dspy-deno-dir={_canonicalize_path(deno_dir)}")
self.deno_command = args
self.deno_process = None
self._mounted_files = False
self._last_diagnostic: str | None = None
self._owner_thread: int | None = None
self._handling_tool_call = False
self._pending_large_vars = {}
self._session_ended = False
|
Methods:
__call__(code: str, variables: dict[str, Any] | None = None) -> Any
Source code in dspy/primitives/python_interpreter.py
| def __call__(
self,
code: str,
variables: dict[str, Any] | None = None,
) -> Any:
return self.execute(code, variables)
|
execute(code: str, variables: dict[str, Any] | None = None) -> Any
Source code in dspy/primitives/python_interpreter.py
| @with_callbacks
def execute(
self,
code: str,
variables: dict[str, Any] | None = None,
) -> Any:
if self._handling_tool_call:
raise CodeInterpreterError("PythonInterpreter cannot execute recursively from one of its tools.")
self._check_session_active()
self._check_thread_ownership()
variables = variables or {}
code = self._inject_variables(code, variables)
self._ensure_deno_process()
self._mount_files()
self._register_tools()
for name, value in self._pending_large_vars.items():
self._inject_large_var(name, value)
# Send the code as JSON-RPC request
execute_request_id = self._next_request_id()
input_data = _jsonrpc_request("execute", {"code": code}, execute_request_id)
self._write_message(input_data, "during execution")
# Read and handle messages until we get the final output.
# Loop is needed because tool calls require back-and-forth communication.
skipped = 0
while skipped <= self._MAX_SKIP_LINES:
output_line = self._read_response_line("during execution")
msg = self._parse_response_line(output_line, "during execution")
if msg is None:
skipped += 1
continue
# Handle incoming requests (tool calls from sandbox)
if "method" in msg:
if msg["method"] == "tool_call":
self._handle_tool_call(msg)
continue
if self._handle_out_of_band_message(msg, "during execution"):
skipped += 1
continue
# Handle success response
if "result" in msg:
if msg.get("id") != execute_request_id:
self._raise_terminal_error(
f"Response ID mismatch: expected {execute_request_id}, got {msg.get('id')}"
)
result = msg["result"]
if not isinstance(result, dict):
self._raise_terminal_error(f"Malformed execution result: {msg}")
self._sync_files()
# Check for SUBMIT (encoded as success with "final" field)
if "final" in result:
return FinalOutput(result["final"])
return result.get("output", None)
# Handle error response
if "error" in msg:
if msg.get("id") != execute_request_id:
self._raise_terminal_error(
f"Response ID mismatch: expected {execute_request_id}, got {msg.get('id')}"
)
error = msg["error"]
if not isinstance(error, dict):
self._raise_terminal_error(f"Malformed execution error: {msg}")
error_code = error.get("code", JSONRPC_APP_ERRORS["Unknown"])
error_message = error.get("message", "Unknown error")
error_data = error.get("data", {})
if not isinstance(error_data, dict):
self._raise_terminal_error(f"Malformed execution error data: {msg}")
error_type = error_data.get("type", "Error")
if error_code == JSONRPC_APP_ERRORS["SyntaxError"]:
raise SyntaxError(f"Invalid Python syntax. message: {error_message}")
if error_code in JSONRPC_APP_ERRORS.values():
raise CodeExecutionError(f"{error_type}: {error_data.get('args') or error_message}")
self._raise_terminal_error(f"{error_type}: {error_data.get('args') or error_message}")
# Unexpected message format - neither a recognized method nor a response
self._raise_terminal_error(f"Unexpected message format from sandbox: {msg}")
self._raise_terminal_error(f"Too many skipped lines ({skipped}) during execution")
|
provide_dspy() -> None
Make import dspy work in the sandbox, with the host’s dspy and Pyodide builds of its dependencies.
The first call for a dspy source tree fetches the dependencies, byte-compiles the bundle, and records the memory of a sandbox that has imported it (see dspy.primitives.sandbox_bundle). The sandbox restores that snapshot when it starts, so dspy is already imported. Without one, it installs the bundle and imports dspy on first use. Call before the interpreter starts; a second call does nothing. With sandbox_cache=False the bundle is built in a temporary directory of the process instead of the cache, and no snapshot is recorded.
Source code in dspy/primitives/python_interpreter.py
| def provide_dspy(self) -> None:
"""Make ``import dspy`` work in the sandbox, with the host's dspy and Pyodide builds of its dependencies.
The first call for a dspy source tree fetches the dependencies, byte-compiles the bundle, and records the
memory of a sandbox that has imported it (see ``dspy.primitives.sandbox_bundle``). The sandbox restores that
snapshot when it starts, so dspy is already imported. Without one, it installs the bundle and imports dspy on
first use. Call before the interpreter starts; a second call does nothing. With ``sandbox_cache=False`` the
bundle is built in a temporary directory of the process instead of the cache, and no snapshot is recorded.
"""
from dspy.primitives.sandbox_bundle import (
SandboxBundleError,
prepare_bundle,
prepare_snapshot,
prepare_stdlib,
scratch_root,
)
if any(arg.startswith("--dspy-bundle=") for arg in self.deno_command):
return
if self.deno_process is not None:
raise SandboxBundleError("provide_dspy() must be called before the interpreter starts.")
if not self._uses_default_deno_command:
raise SandboxBundleError("provide_dspy() needs the default deno_command.")
root = None
if not self.sandbox_cache: # nothing in the cache: a bundle of this process's own
root = scratch_root()
if any(_paths_overlap(_canonicalize_path(path), _canonicalize_path(root)) for path in self.enable_write_paths):
raise CodeInterpreterError("Write paths cannot overlap PythonInterpreter runtime files.")
bundle = _canonicalize_path(prepare_bundle(self._deno_run, self._deno_dir, self._runner, root, self.sandbox_packages))
self._allow_read(bundle)
self.deno_command.append(f"--dspy-bundle={bundle}")
if root is not None: # no snapshot, without the cache: each sandbox imports dspy itself
return
try:
stdlib = _canonicalize_path(prepare_stdlib(self._deno_run, self._deno_dir, self._runner))
snapshot = prepare_snapshot(self._deno_run, self._deno_dir, self._runner, bundle, stdlib)
except SandboxBundleError as e:
logger.debug("The sandbox imports dspy itself: %s", e)
return
snapshot = _canonicalize_path(snapshot)
self._allow_read(snapshot)
self.deno_command.append(f"--dspy-snapshot={snapshot}")
|
shutdown() -> None
Source code in dspy/primitives/python_interpreter.py
| @with_callbacks
def shutdown(self) -> None:
session_was_active = not self._session_ended
self._session_ended = True
if self.deno_process and self.deno_process.poll() is None:
if session_was_active:
self.deno_process.stdin.write(_jsonrpc_notification("shutdown") + "\n")
self.deno_process.stdin.flush()
self.deno_process.stdin.close()
else:
self.deno_process.terminate()
self.deno_process.wait()
self.deno_process = None
self._owner_thread = None
|
start() -> None
Initialize the Deno/Pyodide sandbox.
This pre-warms the sandbox by starting the Deno subprocess. Can be called explicitly for pooling, or will be called lazily on first execute().
Idempotent while the session is active. A stopped or shut-down session cannot be restarted because its Python state cannot be reconstructed.
Source code in dspy/primitives/python_interpreter.py
| @with_callbacks
def start(self) -> None:
"""Initialize the Deno/Pyodide sandbox.
This pre-warms the sandbox by starting the Deno subprocess.
Can be called explicitly for pooling, or will be called lazily
on first execute().
Idempotent while the session is active. A stopped or shut-down session
cannot be restarted because its Python state cannot be reconstructed.
"""
if self.deno_process is None:
self._check_session_active()
self._spawn_process()
else:
self._ensure_deno_process()
|