docs + examples

Author: sid-rl

README-SDK.md

@@ -30,6 +30,23 @@ The full API of this library can be found in [api.md](api.md).
 
 For a higher-level, Pythonic interface, check out the new [`RunloopSDK`](README-SDK.md) which layers an object-oriented API on top of the generated client (including synchronous and asynchronous variants).
 
+```python
+from runloop_api_client import RunloopSDK
+
+sdk = RunloopSDK()  # Uses RUNLOOP_API_KEY environment variable by default
+
+# Create a devbox and execute commands with a clean, object-oriented interface
+with sdk.devbox.create(name="my-devbox") as devbox:
+    result = devbox.cmd.exec("echo 'Hello from Runloop!'")
+    print(result.stdout())
+```
+
+**See the [SDK documentation](README-SDK.md) for complete examples and API reference.**
+
+### REST API Client
+
+Alternatively, you can use the generated REST API client directly:
+
 ```python
 import os
 from runloop_api_client import Runloop

README.md

@@ -0,0 +1,189 @@
+#!/usr/bin/env -S uv run python
+"""
+Async Runloop SDK Example - Concurrent Devbox Operations
+
+This example demonstrates the asynchronous capabilities of the Runloop SDK:
+- Creating and managing devboxes asynchronously
+- Concurrent command execution across multiple devboxes
+- Async file operations
+- Async command streaming
+"""
+
+import asyncio
+import os
+from runloop_api_client import AsyncRunloopSDK
+
+
+async def demonstrate_basic_async():
+    """Demonstrate basic async devbox operations."""
+    print("=== Basic Async Operations ===")
+    
+    sdk = AsyncRunloopSDK()
+    
+    # Create a devbox with async context manager
+    async with sdk.devbox.create(name="async-example-devbox") as devbox:
+        print(f"Created devbox: {devbox.id}")
+        
+        # Execute command asynchronously
+        result = await devbox.cmd.exec("echo 'Hello from async devbox!'")
+        output = await result.stdout()
+        print(f"Command output: {output.strip()}")
+        
+        # File operations
+        await devbox.file.write(
+            path="/home/user/async_test.txt",
+            contents="Hello from async operations!\n",
+        )
+        content = await devbox.file.read(path="/home/user/async_test.txt")
+        print(f"File content: {content.strip()}")
+        
+    print("Devbox automatically shutdown\n")
+
+
+async def demonstrate_concurrent_commands():
+    """Execute multiple commands concurrently on the same devbox."""
+    print("=== Concurrent Command Execution ===")
+    
+    sdk = AsyncRunloopSDK()
+    
+    async with sdk.devbox.create(name="concurrent-commands-devbox") as devbox:
+        print(f"Created devbox: {devbox.id}")
+        
+        # Execute multiple commands concurrently
+        async def run_command(cmd: str, label: str):
+            print(f"Starting: {label}")
+            result = await devbox.cmd.exec(cmd)
+            output = await result.stdout()
+            print(f"{label} completed: {output.strip()}")
+            return output
+        
+        # Run multiple commands in parallel
+        results = await asyncio.gather(
+            run_command("echo 'Task 1' && sleep 1", "Task 1"),
+            run_command("echo 'Task 2' && sleep 1", "Task 2"),
+            run_command("echo 'Task 3' && sleep 1", "Task 3"),
+        )
+        
+        print(f"All {len(results)} tasks completed\n")
+
+
+async def demonstrate_multiple_devboxes():
+    """Create and manage multiple devboxes concurrently."""
+    print("=== Managing Multiple Devboxes ===")
+    
+    sdk = AsyncRunloopSDK()
+    
+    async def create_and_use_devbox(name: str, number: int):
+        """Create a devbox, run a command, and return the result."""
+        async with sdk.devbox.create(name=name) as devbox:
+            print(f"Devbox {number} ({devbox.id}): Created")
+            
+            # Run a command
+            result = await devbox.cmd.exec(f"echo 'Hello from devbox {number}'")
+            output = await result.stdout()
+            print(f"Devbox {number}: {output.strip()}")
+            
+            return output
+    
+    # Create and use multiple devboxes concurrently
+    results = await asyncio.gather(
+        create_and_use_devbox("multi-devbox-1", 1),
+        create_and_use_devbox("multi-devbox-2", 2),
+        create_and_use_devbox("multi-devbox-3", 3),
+    )
+    
+    print(f"All {len(results)} devboxes completed and shutdown\n")
+
+
+async def demonstrate_async_streaming():
+    """Demonstrate real-time command output streaming with async callbacks."""
+    print("=== Async Command Streaming ===")
+    
+    sdk = AsyncRunloopSDK()
+    
+    async with sdk.devbox.create(name="streaming-devbox") as devbox:
+        print(f"Created devbox: {devbox.id}")
+        
+        # Async callback to capture output
+        output_lines = []
+        
+        async def capture_output(line: str):
+            print(f"[STREAM] {line.strip()}")
+            output_lines.append(line)
+        
+        # Execute command with streaming output
+        print("\nStreaming command output:")
+        await devbox.cmd.exec(
+            "for i in 1 2 3 4 5; do echo \"Line $i\"; sleep 0.2; done",
+            stdout=capture_output,
+        )
+        
+        print(f"\nCaptured {len(output_lines)} lines of output\n")
+
+
+async def demonstrate_async_execution():
+    """Demonstrate async execution management."""
+    print("=== Async Execution Management ===")
+    
+    sdk = AsyncRunloopSDK()
+    
+    async with sdk.devbox.create(name="async-exec-devbox") as devbox:
+        print(f"Created devbox: {devbox.id}")
+        
+        # Start an async execution
+        execution = await devbox.cmd.exec_async(
+            "echo 'Starting...'; sleep 2; echo 'Finished!'"
+        )
+        print(f"Started execution: {execution.execution_id}")
+        
+        # Poll execution state
+        state = await execution.get_state()
+        print(f"Initial status: {state.status}")
+        
+        # Wait for completion
+        print("Waiting for completion...")
+        result = await execution.result()
+        print(f"Exit code: {result.exit_code}")
+        output = await result.stdout()
+        print(f"Output:\n{output}")
+        
+        # Start another execution and kill it
+        print("\nStarting long-running process...")
+        long_execution = await devbox.cmd.exec_async("sleep 30")
+        print(f"Execution ID: {long_execution.execution_id}")
+        
+        # Wait a bit then kill it
+        await asyncio.sleep(1)
+        print("Killing execution...")
+        await long_execution.kill()
+        print("Execution killed\n")
+
+
+async def main():
+    """Run all async demonstrations."""
+    print("Initialized Async Runloop SDK\n")
+    
+    # Run demonstrations
+    await demonstrate_basic_async()
+    await demonstrate_concurrent_commands()
+    await demonstrate_multiple_devboxes()
+    await demonstrate_async_streaming()
+    await demonstrate_async_execution()
+    
+    print("All async demonstrations completed!")
+
+
+if __name__ == "__main__":
+    # Ensure API key is set
+    if not os.getenv("RUNLOOP_API_KEY"):
+        print("Error: RUNLOOP_API_KEY environment variable is not set")
+        print("Please set it to your Runloop API key:")
+        print("  export RUNLOOP_API_KEY=your-api-key")
+        exit(1)
+    
+    try:
+        asyncio.run(main())
+    except Exception as e:
+        print(f"\nError: {e}")
+        raise
+

examples/async_devbox.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env -S uv run python
+"""
+Basic Runloop SDK Example - Devbox Operations
+
+This example demonstrates the core functionality of the Runloop SDK:
+- Creating and managing devboxes
+- Executing commands synchronously and asynchronously
+- File operations (read, write, upload, download)
+- Devbox lifecycle management
+"""
+
+import os
+from pathlib import Path
+from runloop_api_client import RunloopSDK
+
+
+def main():
+    # Initialize the SDK (uses RUNLOOP_API_KEY environment variable by default)
+    sdk = RunloopSDK()
+    print("Initialized Runloop SDK")
+
+    # Create a devbox with automatic cleanup using context manager
+    print("\n=== Creating Devbox ===")
+    with sdk.devbox.create(name="basic-example-devbox") as devbox:
+        print(f"Created devbox: {devbox.id}")
+        
+        # Get devbox information
+        info = devbox.get_info()
+        print(f"Devbox status: {info.status}")
+        print(f"Devbox name: {info.name}")
+        
+        # Execute a simple command
+        print("\n=== Executing Commands ===")
+        result = devbox.cmd.exec("echo 'Hello from Runloop!'")
+        print(f"Command output: {result.stdout().strip()}")
+        print(f"Exit code: {result.exit_code}")
+        print(f"Success: {result.success}")
+        
+        # Execute a command that generates output
+        result = devbox.cmd.exec("ls -la /home/user")
+        print(f"\nDirectory listing:\n{result.stdout()}")
+        
+        # Execute a command with error
+        result = devbox.cmd.exec("ls /nonexistent")
+        if result.failed:
+            print(f"\nCommand failed with exit code {result.exit_code}")
+            print(f"Error output: {result.stderr()}")
+        
+        # File operations
+        print("\n=== File Operations ===")
+        
+        # Write a file
+        file_path = "/home/user/test.txt"
+        content = "Hello, Runloop!\nThis is a test file.\n"
+        devbox.file.write(path=file_path, contents=content)
+        print(f"Wrote file: {file_path}")
+        
+        # Read the file back
+        read_content = devbox.file.read(path=file_path)
+        print(f"Read file content:\n{read_content}")
+        
+        # Create a local file to upload
+        local_file = Path("temp_upload.txt")
+        local_file.write_text("This file will be uploaded to the devbox.\n")
+        
+        try:
+            # Upload a file
+            upload_path = "/home/user/uploaded.txt"
+            devbox.file.upload(path=upload_path, file=local_file)
+            print(f"\nUploaded file to: {upload_path}")
+            
+            # Verify the upload by reading the file
+            uploaded_content = devbox.file.read(path=upload_path)
+            print(f"Uploaded file content: {uploaded_content.strip()}")
+            
+            # Download a file
+            download_data = devbox.file.download(path=upload_path)
+            local_download = Path("temp_download.txt")
+            local_download.write_bytes(download_data)
+            print(f"Downloaded file to: {local_download}")
+            print(f"Downloaded content: {local_download.read_text().strip()}")
+        finally:
+            # Cleanup local files
+            local_file.unlink(missing_ok=True)
+            if Path("temp_download.txt").exists():
+                Path("temp_download.txt").unlink()
+        
+        # Asynchronous command execution
+        print("\n=== Asynchronous Command Execution ===")
+        
+        # Start a long-running command asynchronously
+        execution = devbox.cmd.exec_async("sleep 3 && echo 'Done sleeping!'")
+        print(f"Started async execution: {execution.execution_id}")
+        
+        # Check the execution state
+        state = execution.get_state()
+        print(f"Execution status: {state.status}")
+        
+        # Wait for completion and get the result
+        print("Waiting for execution to complete...")
+        result = execution.result()
+        print(f"Execution completed with exit code: {result.exit_code}")
+        print(f"Output: {result.stdout().strip()}")
+        
+        # Keep devbox alive (extends timeout)
+        print("\n=== Devbox Lifecycle ===")
+        devbox.keep_alive()
+        print("Extended devbox timeout")
+        
+    print("\n=== Devbox Cleanup ===")
+    print("Devbox automatically shutdown when exiting context manager")
+
+
+if __name__ == "__main__":
+    # Ensure API key is set
+    if not os.getenv("RUNLOOP_API_KEY"):
+        print("Error: RUNLOOP_API_KEY environment variable is not set")
+        print("Please set it to your Runloop API key:")
+        print("  export RUNLOOP_API_KEY=your-api-key")
+        exit(1)
+    
+    try:
+        main()
+    except Exception as e:
+        print(f"\nError: {e}")
+        raise
+