Crate interpretthis 

Sandboxed Python AST interpreter with host tool injection and resource limits.

Evaluates rustpython_parser ASTs — not an embedded CPython. There is no filesystem, network, or process access unless the host registers tools that provide them.

Quick start

use std::collections::HashMap;

use interpretthis::{
    Interpreter, InterpreterConfig, InterpreterDeps, KwargsExt, ToolDefinition, Tools, Value,
};

let tools = Tools::new().with(
    "double",
    ToolDefinition::from_fn(|kwargs| async move {
        let n = kwargs.require_int("n")?;
        Ok(Value::Int(n * 2))
    }),
);
let interp = Interpreter::new(
    InterpreterDeps { tools },
    InterpreterConfig::default(),
);
let resp = interp
    .execute(
        "result = double(n=x)\nprint(result)",
        &Tools::new(),
        HashMap::from([("x".to_string(), Value::Int(42))]),
    )
    .await;
assert!(resp.is_ok());

Registered tools on InterpreterDeps and the per-call tools argument are merged; on a name clash the per-call tool wins.

Contracts worth knowing

• Tool errors surface as InterpreterError::Tool. Uncaught, they fail the host execute call; inside user Python they become a generic Exception and can be caught by bare except / except Exception.
• State export (Interpreter::export_state) is a versioned byte blob (4-byte little-endian STATE_FORMAT_VERSION + JSON body). Mismatched versions fail with InterpreterError::StateFormatSuperseded. Lazy tool proxies are omitted. Signing is a host concern.
• Language surface is intentional, not accidental. Divergences and the stdlib allowlist live in the repo’s CONFORMANCE.md; the security boundary is described in THREAT_MODEL.md.
• Integers use a hybrid representation: values that fit in i64 stay compact; larger results promote automatically (CPython-like arbitrary precision). Extremely large powers/shifts are resource-capped.
• ExceptionGroup / except* (PEP 654 leaf split) are available; nested group APIs are still incomplete — see CONFORMANCE.
• async/await is not supported; host code should await around Interpreter::execute instead.

Re-exports

pub use config::InterpreterConfig;

pub use error::InterpreterError;

pub use interpreter::Interpreter;

pub use interpreter::InterpreterDeps;

pub use interpreter::InterpreterResponse;

pub use tools::KwargsExt;

pub use tools::ToolDefinition;

pub use tools::ToolError;

pub use tools::ToolHandler;

pub use tools::Tools;

pub use value::ExceptionValue;

pub use value::Value;

pub use value::ValueKey;

pub use value::shared_list;

Modules

config

error

interpreter

tools

Host tool injection surface for the interpreter.

value

Constants

STATE_FORMAT_VERSION

Wire-format version embedded in every exported state blob.