ouros

Python bindings for the Ouros sandboxed Python interpreter.

Installation

pip install ouros

Usage

Basic Expression Evaluation

import ouros

# Simple code with no inputs
m = ouros.Sandbox('1 + 2')
print(m.run())
#> 3

Using Input Variables

import ouros

# Create with code that uses input variables
m = ouros.Sandbox('x * y', inputs=['x', 'y'])

# Run multiple times with different inputs
print(m.run(inputs={'x': 2, 'y': 3}))
#> 6
print(m.run(inputs={'x': 10, 'y': 5}))
#> 50

Resource Limits

import ouros

m = ouros.Sandbox('x + y', inputs=['x', 'y'])

# With resource limits
limits = ouros.ResourceLimits(max_duration_secs=1.0)
result = m.run(inputs={'x': 1, 'y': 2}, limits=limits)
assert result == 3

External Functions

import ouros

# Code that calls an external function
m = ouros.Sandbox('double(x)', inputs=['x'], external_functions=['double'])

# Provide the external function implementation at runtime
result = m.run(inputs={'x': 5}, external_functions={'double': lambda x: x * 2})
print(result)
#> 10

Iterative Execution with External Functions

Use start() and resume() to handle external function calls iteratively, giving you control over each call:

import ouros

code = """
data = fetch(url)
len(data)
"""

m = ouros.Sandbox(code, inputs=['url'], external_functions=['fetch'])

# Start execution - pauses when fetch() is called
result = m.start(inputs={'url': 'https://example.com'})

print(type(result))
#> <class 'ouros.Snapshot'>
print(result.function_name)  # fetch
#> fetch
print(result.args)
#> ('https://example.com',)

# Perform the actual fetch, then resume with the result
result = result.resume(return_value='hello world')

print(type(result))
#> <class 'ouros.Complete'>
print(result.output)
#> 11

Serialization

Both Sandbox and Snapshot can be serialized to bytes and restored later. This allows caching parsed code or suspending execution across process boundaries:

import ouros

# Serialize parsed code to avoid re-parsing
m = ouros.Sandbox('x + 1', inputs=['x'])
data = m.dump()

# Later, restore and run
m2 = ouros.Sandbox.load(data)
print(m2.run(inputs={'x': 41}))
#> 42

Execution state can also be serialized mid-flight:

import ouros

m = ouros.Sandbox('fetch(url)', inputs=['url'], external_functions=['fetch'])
progress = m.start(inputs={'url': 'https://example.com'})

# Serialize the execution state
state = progress.dump()

# Later, restore and resume (e.g., in a different process)
progress2 = ouros.Snapshot.load(state)
result = progress2.resume(return_value='response data')
print(result.output)
#> response data