un-inception/clients/python/EXAMPLES_STRUCTURE.md

Python SDK Examples Structure

Overview

This document describes the structure and organization of Python SDK examples for both synchronous and asynchronous code execution patterns.

Directory Structure

clients/python/
├── EXAMPLES.md                          # Comprehensive examples guide
├── EXAMPLES_STRUCTURE.md               # This file - structural overview
├── scripts/
│   └── validate-examples.sh            # Validation script for all examples
├── sync/
│   ├── src/
│   │   └── un.py                       # Synchronous SDK
│   └── examples/
│       ├── hello_world.py              # Raw code snippet
│       ├── hello_world_client.py       # SDK wrapper example
│       ├── fibonacci.py                # Raw code snippet
│       ├── fibonacci_client.py         # SDK wrapper example
│       ├── http_request.py             # Network I/O example
│       ├── json_processing.py          # Data processing example
│       └── file_operations.py          # File I/O example
└── async/
    ├── src/
    │   └── un_async.py                 # Asynchronous SDK
    └── examples/
        ├── hello_world_async.py        # Basic async example
        ├── fibonacci_async.py          # Concurrent computation
        ├── concurrent_requests.py      # Parallel HTTP requests
        ├── stream_processing.py        # Async generator patterns
        ├── async_job_polling.py        # Job management
        ├── concurrent_execution.py     # Multi-language concurrency
        └── sync_blocking_usage.py      # Mixed sync/async patterns

Synchronous Examples

Location

clients/python/sync/examples/

Types

Basic Examples (2 files)

• hello_world.py: Simple print statement (raw code to execute)
• hello_world_client.py: SDK wrapper that executes hello_world logic

Computational Examples (2 files)

• fibonacci.py: Recursive fibonacci (raw code)
• fibonacci_client.py: SDK wrapper executing fibonacci calculation

Data Processing Examples (3 files)

• http_request.py: HTTP requests using requests library
• json_processing.py: JSON parsing and manipulation
• file_operations.py: Temporary file creation and I/O

Pattern

# All sync examples follow this pattern:
from un import execute_code

def main():
    code = "..."  # Python code to execute
    result = execute_code("python", code, public_key, secret_key)
    print(result.get("stdout"))

if __name__ == "__main__":
    main()

Asynchronous Examples

Location

clients/python/async/examples/

Types

Basic Examples (1 file)

• hello_world_async.py: Simple async execution with await

Concurrent Computation (1 file)

• fibonacci_async.py: Multiple concurrent fibonacci calculations

Network Examples (1 file)

• concurrent_requests.py: Parallel HTTP requests to different endpoints

Stream Processing (1 file)

• stream_processing.py: Async generator patterns for data streaming

Job Management (2 files)

• async_job_polling.py: Fire-and-forget job submission and polling
• concurrent_execution.py: Multi-language code execution

Hybrid Patterns (1 file)

• sync_blocking_usage.py: Mixing async and blocking function calls

Pattern

# All async examples follow this pattern:
import asyncio
from un_async import execute_code

async def main():
    code = "..."
    result = await execute_code("python", code, public_key, secret_key)
    print(result.get("stdout"))

if __name__ == "__main__":
    asyncio.run(main())

File Coverage

Sync Examples (7 files)

1. hello_world.py - Basic output
2. hello_world_client.py - SDK wrapper pattern
3. fibonacci.py - CPU computation
4. fibonacci_client.py - CPU computation via SDK
5. http_request.py - Network I/O
6. json_processing.py - Data transformation
7. file_operations.py - File I/O

Coverage: Basic I/O, CPU-bound, Network, Data structures, File systems

Async Examples (7 files)

1. hello_world_async.py - Basic async pattern
2. fibonacci_async.py - Concurrent computation
3. concurrent_requests.py - Parallel network I/O
4. stream_processing.py - Async generators
5. async_job_polling.py - Job lifecycle management
6. concurrent_execution.py - Multi-language parallelism
7. sync_blocking_usage.py - Hybrid sync/async patterns

Coverage: Async patterns, Concurrency, Job management, Polyglot execution, Hybrid patterns

Code Patterns Demonstrated

1. Basic Execution

• hello_world_client.py (sync)
• hello_world_async.py (async)

2. Error Handling

All examples include:

try:
    result = execute_code(...)
except CredentialsError as e:
    # Handle missing credentials
except Exception as e:
    # Handle other errors

3. Credential Resolution

All examples show how to use environment variables:

public_key = os.environ.get("UNSANDBOX_PUBLIC_KEY")
secret_key = os.environ.get("UNSANDBOX_SECRET_KEY")

4. Result Processing

All examples demonstrate:

if result.get("status") == "completed":
    print(result.get("stdout"))
else:
    print(f"Error: {result.get('error')}")

5. Concurrency (Async only)

Examples show asyncio.gather() pattern:

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

6. Job Management (Async only)

Examples demonstrate:

job_id = await execute_async(...)
status = await get_job(job_id)
result = await wait_for_job(job_id)

Feature Coverage

Sync Examples

• Execute code synchronously ✓
• Handle credentials ✓
• Process stdout/stderr ✓
• Error handling ✓
• Network requests ✓
• Data processing ✓
• File I/O ✓
• CPU-bound operations ✓

Async Examples

• Execute code asynchronously ✓
• Concurrent execution ✓
• asyncio.gather() patterns ✓
• Job submission (fire-and-forget) ✓
• Job polling with backoff ✓
• Multiple languages ✓
• Hybrid sync/async contexts ✓
• Stream processing ✓

Validation

Script

scripts/validate-examples.sh - Comprehensive validation script

Checks Performed

• File existence ✓
• Readable permissions ✓
• Python syntax validation ✓
• Content verification (contains expected patterns) ✓
• Optional: Execution tests (with credentials)

Running Validation

# Basic validation (no credentials needed)
bash scripts/validate-examples.sh

# With execution tests (requires credentials)
UNSANDBOX_PUBLIC_KEY=... UNSANDBOX_SECRET_KEY=... \
bash scripts/validate-examples.sh --run

Expected Output Examples

Sync Examples Output

Executing code synchronously...
Result status: completed
Output: Hello from unsandbox!

Async Examples Output

Executing code asynchronously...
Result status: completed
Output: Hello from async unsandbox!

Concurrent Examples 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!

Usage Examples

Running Individual Examples

Sync examples:

export UNSANDBOX_PUBLIC_KEY="key"
export UNSANDBOX_SECRET_KEY="secret"
python3 sync/examples/hello_world_client.py
python3 sync/examples/http_request.py

Async examples:

export UNSANDBOX_PUBLIC_KEY="key"
export UNSANDBOX_SECRET_KEY="secret"
python3 async/examples/hello_world_async.py
python3 async/examples/fibonacci_async.py

Batch Running

All sync examples:

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

All async examples:

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

Documentation

Main Documentation

• EXAMPLES.md - Comprehensive guide with usage instructions
• EXAMPLES_STRUCTURE.md - This file, structural overview

Docstrings

Each example file includes:

• Module docstring with description
• Usage instructions
• Expected output
• Feature highlights

Requirements

Python Version

• Python 3.7+

Dependencies (Built-in)

• asyncio (async examples)
• os, sys (all examples)

SDK Dependencies

• requests (sync SDK)
• aiohttp (async SDK)

Pre-installed in Sandbox

• numpy, scipy, pandas
• matplotlib, seaborn, plotly
• requests, beautifulsoup4
• And 20+ other packages (see CLAUDE.md)

Extensibility

Adding New Sync Examples

1. Create sync/examples/feature_name.py
2. Import from un module
3. Follow established error handling pattern
4. Add docstring with expected output
5. Update EXAMPLES.md
6. Run validation: bash scripts/validate-examples.sh

Adding New Async Examples

1. Create async/examples/feature_name.py
2. Import from un_async module
3. Use async/await syntax
4. Follow established error handling pattern
5. Add docstring with expected output
6. Update EXAMPLES.md
7. Run validation: bash scripts/validate-examples.sh

Related Documentation

• /home/fox/git/un-inception/CLAUDE.md - Project instructions
• /home/fox/git/un-inception/clients/python/README.md - SDK documentation
• /home/fox/git/un-inception/docs/ - Architecture and design docs

Testing

All examples are designed to be:

• Testable - Deterministic output for validation
• Runnable - Complete with error handling
• Self-documented - Clear docstrings and comments
• Extensible - Can be used as templates for other examples

Summary

Total Examples: 14 files

• Sync Examples: 7 files covering 4 categories
• Async Examples: 7 files covering 6 categories
• Documentation: 2 comprehensive guides
• Validation: 1 automated script

Coverage: All major use cases from simple I/O to complex concurrent operations with proper error handling and credential management.