un-inception/clients/python/QUICK_START.md

Python SDK - Quick Start Guide

Setup (30 seconds)

# Set your API credentials
export UNSANDBOX_PUBLIC_KEY="your-public-key"
export UNSANDBOX_SECRET_KEY="your-secret-key"

Synchronous Usage

Simple Execution

python3 sync/examples/hello_world_client.py

Run Your Own Code

from un import execute_code

result = execute_code("python", 'print("Hello")')
print(result.get("stdout"))  # Output: Hello

Available Languages

Python, JavaScript, Go, Rust, Java, C, C++, Ruby, PHP, Bash, and 40+ more

Examples by Category

Category	File	What It Does
Basic	hello_world_client.py	Simple print statement
CPU	fibonacci_client.py	Recursive computation
Network	http_request.py	HTTP requests
Data	json_processing.py	JSON parsing
Files	file_operations.py	Temp file I/O

Asynchronous Usage

Simple Async Execution

python3 async/examples/hello_world_async.py

Run Concurrent Tasks

import asyncio
from un_async import execute_code

async def main():
    tasks = [
        execute_code("python", 'print(1)'),
        execute_code("python", 'print(2)'),
        execute_code("python", 'print(3)'),
    ]
    results = await asyncio.gather(*tasks)
    return results

asyncio.run(main())

Async Examples by Category

Category	File	What It Does
Basic	hello_world_async.py	Async execution
Concurrent CPU	fibonacci_async.py	Parallel computation
Concurrent Network	concurrent_requests.py	Parallel HTTP
Streams	stream_processing.py	Async generators
Jobs	async_job_polling.py	Job management
Multi-language	concurrent_execution.py	Mixed language execution
Hybrid	sync_blocking_usage.py	Sync + async mixing

Common Tasks

Task 1: Execute Python Code

from un import execute_code

result = execute_code("python", """
numbers = [1, 2, 3, 4, 5]
print(f"Sum: {sum(numbers)}")
""")
print(result.get("stdout"))

Task 2: Execute JavaScript Code

from un import execute_code

result = execute_code("javascript", """
const nums = [1, 2, 3, 4, 5];
console.log(`Sum: ${nums.reduce((a, b) => a + b, 0)}`);
""")
print(result.get("stdout"))

Task 3: Run Multiple Jobs Concurrently

import asyncio
from un_async import execute_code

async def run_jobs():
    jobs = [
        execute_code("python", "print('Job 1')"),
        execute_code("javascript", "console.log('Job 2')"),
        execute_code("bash", "echo 'Job 3'"),
    ]
    return await asyncio.gather(*jobs)

asyncio.run(run_jobs())

Task 4: Poll Job Status

from un import execute_async, wait_for_job

# Start job
job_id = execute_async("python", "print('running')")

# Wait for completion
result = wait_for_job(job_id)
print(result.get("stdout"))

Task 5: Make HTTP Request (from Sandbox)

from un import execute_code

code = """
import requests
response = requests.get('https://httpbin.org/ip')
print(response.json())
"""
result = execute_code("python", code)
print(result.get("stdout"))

Error Handling

from un import execute_code, CredentialsError

try:
    result = execute_code("python", "print('hello')")

    if result.get("status") == "completed":
        print(f"Success: {result.get('stdout')}")
    elif result.get("status") == "failed":
        print(f"Failed: {result.get('error')}")
    elif result.get("status") == "timeout":
        print("Execution timed out")

except CredentialsError:
    print("Invalid credentials")
except Exception as e:
    print(f"Error: {e}")

Credential Options

Option 1: Environment Variables (Recommended)

export UNSANDBOX_PUBLIC_KEY="key"
export UNSANDBOX_SECRET_KEY="secret"
python3 script.py

Option 2: Function Arguments

from un import execute_code

result = execute_code(
    "python",
    "print('hello')",
    public_key="key",
    secret_key="secret"
)

Option 3: Config File

Create ~/.unsandbox/accounts.csv:

public_key,secret_key

Validation

Check all examples work:

bash scripts/validate-examples.sh

With credentials (executes examples):

UNSANDBOX_PUBLIC_KEY=... UNSANDBOX_SECRET_KEY=... \
bash scripts/validate-examples.sh --run

File Structure

clients/python/
├── sync/
│   ├── src/un.py              (Sync SDK)
│   └── examples/              (7 sync examples)
├── async/
│   ├── src/un_async.py        (Async SDK)
│   └── examples/              (7 async examples)
├── EXAMPLES.md                (Full documentation)
└── scripts/validate-examples.sh (Validation)

Performance Tips

For Multiple Executions

• Use async examples for concurrency
• Use asyncio.gather() to run tasks in parallel
• Don't create new session for each request

For Long-Running Tasks

• Use execute_async() + wait_for_job() pattern
• Poll periodically rather than spinning
• Timeout after reasonable time

For API Key Limits

• Check rate limit headers in responses
• Implement backoff for retries
• Use concurrency limits from account tier

Next Steps

1. Review Examples: Check EXAMPLES.md for detailed docs
2. Run Validation: bash scripts/validate-examples.sh
3. Try Sync Examples: Start with hello_world_client.py
4. Try Async Examples: Then try hello_world_async.py
5. Build Your App: Use patterns from examples

Documentation

• EXAMPLES.md - Full guide with all examples explained
• EXAMPLES_STRUCTURE.md - Project structure overview
• README.md - SDK API reference
• QUICK_START.md - This file

Support

For issues:

1. Check credentials are set correctly
2. Verify network connectivity
3. Review error messages
4. Check EXAMPLES.md for similar cases
5. Try running validation script

Key Takeaways

• Sync: Use from un import execute_code
• Async: Use from un_async import execute_code with await
• Concurrency: Use asyncio.gather(*tasks)
• Jobs: Use execute_async() + wait_for_job()
• Languages: 50+ languages supported
• Error Handling: Always check result.get("status")

---

Ready? Run your first example:

python3 sync/examples/hello_world_client.py