un-inception/clients/python/EXAMPLES.md

Python SDK Examples

This directory contains comprehensive examples for both synchronous and asynchronous usage of the unsandbox Python SDK.

Setup

Before running examples, set your API credentials:

export UNSANDBOX_PUBLIC_KEY="your-public-key"
export UNSANDBOX_SECRET_KEY="your-secret-key"

Alternatively, save credentials to ~/.unsandbox/accounts.csv:

public_key,secret_key

Synchronous Examples (sync/examples/)

Synchronous examples use the standard requests library for blocking I/O operations.

Basic Examples

hello_world.py

Simple code snippet that prints "Hello from unsandbox!"

# This is raw code to execute, not a SDK client example
python3 -c "print('Hello from unsandbox!')"

hello_world_client.py

SDK client example showing synchronous code execution.

python3 hello_world_client.py
# Expected output:
# Executing code synchronously...
# Result status: completed
# Output: Hello from unsandbox!

Computational Examples

fibonacci.py

Simple recursive fibonacci implementation (raw code snippet).

# This is raw code, run via SDK

fibonacci_client.py

SDK client that executes fibonacci calculation in sandbox.

python3 fibonacci_client.py
# Expected output:
# Calculating fibonacci(10)...
# Result status: completed
# Output: fib(10) = 55

Data Processing Examples

http_request.py

Demonstrates HTTP requests from sandboxed environment using requests library.

python3 http_request.py
# Expected output:
# Executing HTTP request in sandbox...
# === STDOUT ===
# Status Code: 200
# Response: {"origin": "..."}

Features:

• Uses requests library (pre-installed)
• Error handling for network failures
• JSON response parsing

json_processing.py

Shows JSON parsing and manipulation operations.

python3 json_processing.py
# Expected output:
# Executing JSON processing in sandbox...
# === STDOUT ===
# Original JSON: {"name": "Alice", "age": 30, ...}
# Parsed successfully!
# Name: Alice
# Age: 30
# Skills: Python, JavaScript

Features:

• JSON parsing with error handling
• Data manipulation and modification
• Re-serialization with formatting

file_operations.py

Demonstrates temporary file creation and manipulation.

python3 file_operations.py
# Expected output:
# Executing file operations in sandbox...
# === STDOUT ===
# File created at: /tmp/example.txt
# File exists: True
# File size: 84 bytes
# File contents:
# Line 1: Hello from the sandbox
# ...

Features:

• File writing with context managers
• File reading and parsing
• File system operations
• Proper error handling

Asynchronous Examples (async/examples/)

Asynchronous examples use asyncio and aiohttp for concurrent operations.

Basic Examples

hello_world_async.py

SDK client example showing asynchronous code execution.

python3 hello_world_async.py
# Expected output:
# Executing code asynchronously...
# Result status: completed
# Output: Hello from async unsandbox!

Concurrent Computation

fibonacci_async.py

Runs multiple fibonacci calculations concurrently.

python3 fibonacci_async.py
# Expected output:
# Starting 3 concurrent fibonacci calculations...
# [fib-10] Result: fib(10) = 55
# [fib-15] Result: fib(15) = 610
# [fib-12] Result: fib(12) = 144
# All calculations completed!

Features:

• Multiple concurrent executions using asyncio.gather()
• Parallel CPU-bound operations
• Result aggregation

Network Examples

concurrent_requests.py

Executes multiple HTTP requests concurrently.

python3 concurrent_requests.py
# Expected output:
# Starting 3 concurrent HTTP requests...
# [request-1] Status: 200, Response: {...}
# [request-2] Status: 200, Response: {...}
# [request-3] Status: 200, Response: {...}
# All requests completed successfully!

Features:

• Parallel network requests
• URL handling and error recovery
• Response processing
• Timeout handling

Stream Processing

stream_processing.py

Demonstrates async generator patterns for data stream handling.

python3 stream_processing.py
# Expected output:
# Processing stream of data...
# [stream-task-1] Processed 10 items, sum: 45
# [stream-task-2] Processed 10 items, sum: 145
# [stream-task-3] Processed 10 items, sum: 245
# Stream processing completed!

Features:

• Async generator patterns
• Parallel stream processing
• Data aggregation

Job Management Examples

async_job_polling.py

Shows how to manage async jobs with polling and cancellation.

python3 async_job_polling.py
# Expected output:
# 1. Starting async job...
#    Job ID: job_...
# 2. Checking job status...
#    Status: ...
# 3. Waiting for job completion...
#    Final status: completed
#    Output: Job result
# 4. Listing all jobs...
#    Total jobs: ...

Features:

• Fire-and-forget job submission
• Status polling with backoff
• Job cancellation
• Job listing

concurrent_execution.py

Runs multiple different code snippets concurrently across languages.

python3 concurrent_execution.py
# Expected output:
# Running 4 concurrent code executions...
# [python_hello] Result: Hello from Python
# [js_hello] Result: Hello from JavaScript
# [bash_hello] Result: Hello from Bash
# [python_math] Result: pi = 3.1416
# === Execution Summary ===
# python_hello: OK
# js_hello: OK
# bash_hello: OK
# python_math: OK

Features:

• Multi-language execution
• Concurrent task coordination
• Result aggregation

sync_blocking_usage.py

Shows how to use async SDK in both async and blocking contexts.

python3 sync_blocking_usage.py
# Expected output:
# === Async Approach ===
# Output: Hello from async
#
# === Sync Functions (in async context) ===
# Detected language for script.py: python
# Output: Executing python code
#
# === Mixed Sync/Async ===
# get_languages is available for fetching supported languages
# Output: Hello from mixed

Features:

• Async/await patterns
• Synchronous helper functions
• Mixed sync/async contexts
• Language detection

Common Patterns

Error Handling

All examples include proper error handling:

try:
    result = execute_code("python", code, public_key, secret_key)
    if result.get("status") == "completed":
        print(result.get("stdout"))
    else:
        print(f"Failed: {result.get('error')}")
except CredentialsError as e:
    print(f"Credentials error: {e}")
except Exception as e:
    print(f"Error: {e}")

Credential Resolution

Examples use the SDK's credential resolution system:

1. Environment variables (UNSANDBOX_PUBLIC_KEY, UNSANDBOX_SECRET_KEY)
2. ~/.unsandbox/accounts.csv
3. ./accounts.csv

Concurrent Execution

For async examples, use asyncio.gather() for parallel operations:

async def main():
    tasks = [
        execute_code("python", code1, pk, sk),
        execute_code("javascript", code2, pk, sk),
    ]
    results = await asyncio.gather(*tasks)

Running Validation

Examples are designed to be validated by automated test scripts:

# Run all sync examples
for f in sync/examples/*_client.py; do
    python3 "$f" || echo "Failed: $f"
done

# Run all async examples
for f in async/examples/*.py; do
    python3 "$f" || echo "Failed: $f"
done

Pre-installed Packages

All examples can use these pre-installed packages:

Python:

• requests (HTTP requests)
• json (data parsing)
• asyncio (async operations)
• aiohttp (async HTTP)
• numpy, scipy, pandas, matplotlib
• Beautiful Soup, requests, Pillow
• cryptography, pytest, and 20+ others

Network Modes

Examples default to public endpoints, but note:

• zerotrust: No internet access (default)
• semitrusted: Internet via egress proxy (httpbin.org examples)

Request semitrusted mode when needed for your use case.

Troubleshooting

Module Import Errors

Ensure SDK path is set correctly:

sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))

Timeout Errors

Increase timeout for long-running operations:

result = wait_for_job(job_id, public_key, secret_key)  # Waits indefinitely with backoff

Credentials Not Found

Set environment variables:

export UNSANDBOX_PUBLIC_KEY="key"
export UNSANDBOX_SECRET_KEY="secret"

Or create ~/.unsandbox/accounts.csv:

mkdir -p ~/.unsandbox
echo "key,secret" > ~/.unsandbox/accounts.csv
chmod 600 ~/.unsandbox/accounts.csv

Related Documentation

• SDK API Reference
• Architecture Overview
• Language Support