grasp-sdk 0.1.9__py3-none-any.whl → 0.2.0b1__py3-none-any.whl

examples/test_async_context.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""测试 Grasp 异步上下文管理器功能"""
+
+import asyncio
+import os
+from grasp_sdk import Grasp
+
+async def test_async_context_manager():
+    """测试异步上下文管理器功能"""
+    print("测试 Grasp 异步上下文管理器...")
+    
+    # 初始化 Grasp SDK
+    grasp = Grasp({'apiKey': 'test-key'})
+    
+    # 测试 launch_context 方法
+    print("\n1. 测试 launch_context 方法:")
+    context_manager = grasp.launch_context({
+        'browser': {
+            'type': 'chromium',
+            'headless': True,
+            'timeout': 30000
+        }
+    })
+    print(f"   ✓ launch_context 返回类型: {type(context_manager).__name__}")
+    print(f"   ✓ 是否为同一实例: {context_manager is grasp}")
+    
+    # 测试异步上下文管理器方法存在性
+    print("\n2. 测试异步上下文管理器方法:")
+    print(f"   ✓ 具有 __aenter__ 方法: {hasattr(grasp, '__aenter__')}")
+    print(f"   ✓ 具有 __aexit__ 方法: {hasattr(grasp, '__aexit__')}")
+    
+    # 测试错误情况
+    print("\n3. 测试错误处理:")
+    try:
+        # 尝试在没有设置 launch_options 的情况下使用上下文管理器
+        fresh_grasp = Grasp({'apiKey': 'test-key'})
+        async with fresh_grasp as session:
+            pass
+    except RuntimeError as e:
+        print(f"   ✓ 正确捕获错误: {e}")
+    
+    # 模拟使用异步上下文管理器的语法（不实际连接）
+    print("\n4. 异步上下文管理器语法示例:")
+    print("   代码示例:")
+    print("   async with grasp.launch_context({")
+    print("       'browser': {")
+    print("           'type': 'chromium',")
+    print("           'headless': True,")
+    print("           'timeout': 30000")
+    print("       }")
+    print("   }) as session:")
+    print("       # 使用 session 进行操作")
+    print("       browser = session.browser")
+    print("       terminal = session.terminal")
+    print("       files = session.files")
+    
+    print("\n✅ 异步上下文管理器功能测试完成!")
+    print("\n📝 使用说明:")
+    print("   - 使用 grasp.launch_context(options) 设置启动选项")
+    print("   - 然后使用 async with 语法自动管理会话生命周期")
+    print("   - 会话将在退出上下文时自动关闭")
+
+if __name__ == '__main__':
+    asyncio.run(test_async_context_manager())

examples/test_grasp_classes.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""测试 Grasp 类的功能"""
+
+import os
+from grasp_sdk import Grasp, GraspSession, GraspBrowser
+
+def test_grasp_classes():
+    """测试所有 Grasp 类的基本功能"""
+    print("🧪 测试 Grasp 类功能...")
+    
+    # 测试 Grasp 类初始化
+    print("\n1. 测试 Grasp 类初始化:")
+    
+    # 通过字典设置 apiKey
+    grasp1 = Grasp({'apiKey': 'test-key-from-dict'})
+    print(f"   ✓ 通过字典初始化: {grasp1.key == 'test-key-from-dict'}")
+    
+    # 通过环境变量设置 apiKey
+    os.environ['GRASP_KEY'] = 'test-key-from-env'
+    grasp2 = Grasp()
+    print(f"   ✓ 通过环境变量初始化: {grasp2.key == 'test-key-from-env'}")
+    
+    # 测试类的导入
+    print("\n2. 测试类的导入:")
+    print(f"   ✓ Grasp 类可用: {Grasp is not None}")
+    print(f"   ✓ GraspSession 类可用: {GraspSession is not None}")
+    print(f"   ✓ GraspBrowser 类可用: {GraspBrowser is not None}")
+    
+    # 测试方法可用性
+    print("\n3. 测试方法可用性:")
+    grasp = Grasp({'apiKey': 'test-key'})
+    
+    # 测试 Grasp 类方法
+    print(f"   ✓ Grasp.launch 方法可用: {hasattr(grasp, 'launch')}")
+    print(f"   ✓ Grasp.connect 方法可用: {hasattr(grasp, 'connect')}")
+    print(f"   ✓ Grasp.launch_browser 静态方法可用: {hasattr(Grasp, 'launch_browser')}")
+    
+    # 测试异步上下文管理器功能
+    print("\n4. 测试异步上下文管理器功能:")
+    try:
+        # 测试 launch_context 方法
+        context_manager = grasp.launch_context({
+            'browser': {
+                'type': 'chromium',
+                'headless': True,
+                'timeout': 30000
+            }
+        })
+        print(f"   ✓ launch_context 方法可用: {hasattr(grasp, 'launch_context')}")
+        print(f"   ✓ 返回自身实例: {context_manager is grasp}")
+        
+        # 测试异步上下文管理器方法
+        print(f"   ✓ __aenter__ 方法可用: {hasattr(grasp, '__aenter__')}")
+        print(f"   ✓ __aexit__ 方法可用: {hasattr(grasp, '__aexit__')}")
+        
+    except Exception as e:
+        print(f"   ❌ 异步上下文管理器测试失败: {e}")
+    
+    print("\n✅ 所有测试通过!")
+    print("\n📋 已实现的方法:")
+    print("   - Grasp.launch()")
+    print("   - Grasp.connect()")
+    print("   - Grasp.launch_browser()")
+    print("   - Grasp.launch_context() [新增]")
+    print("   - Grasp.__aenter__() [新增]")
+    print("   - Grasp.__aexit__() [新增]")
+    print("   - GraspSession.close()")
+    print("   - GraspBrowser.get_endpoint()")
+    print("   - GraspTerminal.create()")
+    print("\n⏭️  已跳过的方法 (已废弃):")
+    print("   - Grasp.shutdown()")
+    print("   - Grasp.createRunner()")
+    print("\n🎯 新功能:")
+    print("   - 支持 async with grasp.launch_context(options) as session 语法")
+    print("   - 自动管理会话生命周期")
+    print("   - 会话在退出上下文时自动关闭")
+
+if __name__ == '__main__':
+    test_grasp_classes()

examples/test_python_script.py

@@ -0,0 +1,160 @@
+"""Example demonstrating Python script execution support in Grasp SDK.
+
+This example shows how to use the enhanced run_script method to execute
+Python scripts alongside JavaScript in the E2B sandbox environment.
+"""
+
+import asyncio
+from grasp_sdk.services.sandbox import SandboxService
+from grasp_sdk.models import ISandboxConfig
+
+
+async def main():
+    """Main example function demonstrating Python script support."""
+    
+    # Configure sandbox service
+    config: ISandboxConfig = {
+        'key': 'your-api-key-here',  # Replace with your actual API key
+        'timeout': 30000,
+        'workspace': 'your-workspace-id',  # Replace with your workspace ID
+        'debug': True
+    }
+    
+    # Create sandbox service
+    sandbox = SandboxService(config)
+    
+    try:
+        # Create and start sandbox
+        await sandbox.create_sandbox('base')
+        print("✅ Sandbox created successfully")
+        
+        # Example 1: Basic Python script execution
+        print("\n🐍 Example 1: Basic Python script")
+        python_code = """
+print("Hello from Python in E2B sandbox!")
+print(f"Python version: {__import__('sys').version}")
+"""
+        
+        result = await sandbox.run_script(python_code, {'type': 'py'})
+        print(f"Output: {getattr(result, 'stdout', str(result))}")
+        
+        # Example 2: Python script with mathematical operations
+        print("\n🧮 Example 2: Python mathematical operations")
+        math_code = """
+import math
+
+# Calculate some mathematical operations
+numbers = [1, 2, 3, 4, 5]
+print(f"Numbers: {numbers}")
+print(f"Sum: {sum(numbers)}")
+print(f"Square root of 16: {math.sqrt(16)}")
+print(f"Pi: {math.pi:.4f}")
+"""
+        
+        result = await sandbox.run_script(math_code, {'type': 'py'})
+        print(f"Output: {getattr(result, 'stdout', str(result))}")
+        
+        # Example 3: Python script with environment variables
+        print("\n🌍 Example 3: Python script with environment variables")
+        env_code = """
+import os
+
+print(f"Custom variable: {os.environ.get('MY_CUSTOM_VAR', 'Not set')}")
+print(f"Python path: {os.environ.get('PYTHONPATH', 'Default')}")
+print(f"Current working directory: {os.getcwd()}")
+"""
+        
+        result = await sandbox.run_script(env_code, {
+            'type': 'py',
+            'envs': {
+                'MY_CUSTOM_VAR': 'Hello from environment!',
+                'PYTHONPATH': '/custom/python/path'
+            }
+        })
+        print(f"Output: {getattr(result, 'stdout', str(result))}")
+        
+        # Example 4: Python script with package installation
+        print("\n📦 Example 4: Python script with package installation")
+        package_code = """
+import requests
+import json
+
+# Make a simple HTTP request
+response = requests.get('https://httpbin.org/json')
+data = response.json()
+print(f"HTTP Status: {response.status_code}")
+print(f"Response data: {json.dumps(data, indent=2)}")
+"""
+        
+        result = await sandbox.run_script(package_code, {
+            'type': 'py',
+            'preCommand': 'pip install requests && '
+        })
+        print(f"Output: {getattr(result, 'stdout', str(result))}")
+        
+        # Example 5: Python script with custom working directory
+        print("\n📁 Example 5: Python script with custom working directory")
+        file_code = """
+import os
+
+# Create a test file
+with open('test_file.txt', 'w') as f:
+    f.write('Hello from Python file operation!')
+
+# Read the file back
+with open('test_file.txt', 'r') as f:
+    content = f.read()
+    print(f"File content: {content}")
+
+print(f"Current directory: {os.getcwd()}")
+print(f"Files in directory: {os.listdir('.')}")
+"""
+        
+        result = await sandbox.run_script(file_code, {
+            'type': 'py',
+            'cwd': '/home/user/python_workspace'
+        })
+        print(f"Output: {getattr(result, 'stdout', str(result))}")
+        
+        # Example 6: Compare with JavaScript execution
+        print("\n🔄 Example 6: JavaScript vs Python comparison")
+        
+        # JavaScript version
+        js_code = """
+const numbers = [1, 2, 3, 4, 5];
+const sum = numbers.reduce((a, b) => a + b, 0);
+console.log(`JavaScript - Numbers: ${numbers}`);
+console.log(`JavaScript - Sum: ${sum}`);
+console.log(`JavaScript - Node version: ${process.version}`);
+"""
+        
+        js_result = await sandbox.run_script(js_code, {'type': 'cjs'})
+        print(f"JavaScript Output: {getattr(js_result, 'stdout', str(js_result))}")
+        
+        # Python version
+        py_code = """
+numbers = [1, 2, 3, 4, 5]
+total = sum(numbers)
+print(f"Python - Numbers: {numbers}")
+print(f"Python - Sum: {total}")
+print(f"Python - Version: {__import__('sys').version.split()[0]}")
+"""
+        
+        py_result = await sandbox.run_script(py_code, {'type': 'py'})
+        print(f"Python Output: {getattr(py_result, 'stdout', str(py_result))}")
+        
+        print("\n✅ All examples completed successfully!")
+        
+    except Exception as error:
+        print(f"❌ Error: {error}")
+    
+    finally:
+        # Clean up sandbox
+        await sandbox.destroy()
+        print("\n🧹 Sandbox destroyed")
+
+
+if __name__ == "__main__":
+    # Run the example
+    print("🚀 Starting Python script execution examples...")
+    asyncio.run(main())

examples/test_removed_methods.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+测试已删除方法的验证脚本
+
+验证 create_terminal 和 create_filesystem 方法已被正确移除。
+"""
+
+import sys
+import os
+
+# 添加父目录到路径
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+def test_removed_methods():
+    """测试已删除的方法不再可用"""
+    print("🧪 测试已删除方法的验证")
+    print("=" * 30)
+    
+    try:
+        from grasp_sdk import Grasp, GraspSession, GraspBrowser
+        print("✅ 核心类导入成功")
+    except ImportError as e:
+        print(f"❌ 核心类导入失败: {e}")
+        return False
+    
+    # 测试 create_terminal 方法不存在（预期 ImportError）
+    try:
+        # 这行代码预期会失败，因为方法已被删除
+        from grasp_sdk import create_terminal  # type: ignore
+        print("❌ create_terminal 方法仍然存在（应该已被删除）")
+        return False
+    except ImportError:
+        print("✅ create_terminal 方法已成功删除")
+    
+    # 测试 create_filesystem 方法不存在（预期 ImportError）
+    try:
+        # 这行代码预期会失败，因为方法已被删除
+        from grasp_sdk import create_filesystem  # type: ignore
+        print("❌ create_filesystem 方法仍然存在（应该已被删除）")
+        return False
+    except ImportError:
+        print("✅ create_filesystem 方法已成功删除")
+    
+    # 验证 GraspSession 仍然提供 terminal 和 files 属性
+    print("\n📋 验证 GraspSession 的替代功能:")
+    print("   - session.terminal (替代 create_terminal)")
+    print("   - session.files (替代 create_filesystem)")
+    
+    # 检查 __all__ 列表
+    try:
+        import grasp_sdk
+        all_exports = grasp_sdk.__all__
+        
+        if 'create_terminal' in all_exports:
+            print("❌ create_terminal 仍在 __all__ 列表中")
+            return False
+        else:
+            print("✅ create_terminal 已从 __all__ 列表中移除")
+            
+        if 'create_filesystem' in all_exports:
+            print("❌ create_filesystem 仍在 __all__ 列表中")
+            return False
+        else:
+            print("✅ create_filesystem 已从 __all__ 列表中移除")
+            
+    except Exception as e:
+        print(f"⚠️  检查 __all__ 列表时出错: {e}")
+    
+    print("\n🎉 所有验证通过！create_terminal 和 create_filesystem 方法已成功移除")
+    print("\n💡 使用建议:")
+    print("   - 使用 session.terminal 替代 create_terminal(connection)")
+    print("   - 使用 session.files 替代 create_filesystem(connection)")
+    
+    return True
+
+if __name__ == "__main__":
+    success = test_removed_methods()
+    if not success:
+        sys.exit(1)
+    print("\n✅ 测试完成")

examples/test_terminal_updates.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+Test script to verify terminal service updates in Python SDK.
+
+This script tests the updated terminal service functionality,
+including the new kill() method and response.json() compatibility.
+"""
+
+import asyncio
+import sys
+import os
+from unittest.mock import Mock, AsyncMock, patch
+
+# Add the parent directory to the path to import grasp_sdk
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+from grasp_sdk.services.terminal import TerminalService, StreamableCommandResult
+from grasp_sdk.services.sandbox import SandboxService, CommandEventEmitter
+from grasp_sdk.services.browser import CDPConnection
+from grasp_sdk.models import ISandboxConfig
+
+
+class MockCommandEventEmitter(CommandEventEmitter):
+    """Mock command event emitter for testing."""
+    
+    def __init__(self):
+        super().__init__()
+        self.killed = False
+        self.stdout_data = "Test output\n"
+        self.stderr_data = "Test error\n"
+        
+    async def wait(self):
+        """Mock wait method."""
+        await asyncio.sleep(0.1)  # Simulate some processing time
+        return {
+            'exit_code': 0,
+            'stdout': self.stdout_data,
+            'stderr': self.stderr_data
+        }
+    
+    async def kill(self):
+        """Mock kill method."""
+        self.killed = True
+        print("Command killed successfully")
+
+
+async def test_streamable_command_result():
+    """Test StreamableCommandResult functionality."""
+    print("\n=== Testing StreamableCommandResult ===")
+    
+    # Create mock emitter and task
+    emitter = MockCommandEventEmitter()
+    task = asyncio.create_task(emitter.wait())
+    
+    # Create StreamableCommandResult
+    result = StreamableCommandResult(emitter, task)
+    
+    # Test stdout/stderr streams
+    print("✓ StreamableCommandResult created successfully")
+    
+    # Test response.json() method
+    response_data = await result.json()
+    print(f"✓ Response JSON: {response_data}")
+    
+    # Test end() method
+    end_result = await result.end()
+    print(f"✓ End result: {end_result}")
+    
+    # Test kill() method
+    await result.kill()
+    print(f"✓ Kill method executed, emitter killed: {emitter.killed}")
+    
+    print("✓ All StreamableCommandResult tests passed!")
+
+
+async def test_terminal_service():
+    """Test TerminalService functionality."""
+    print("\n=== Testing TerminalService ===")
+    
+    # Create mock sandbox and connection
+    sandbox_config: ISandboxConfig = {
+        'key': 'test-key',
+        'timeout': 30000,
+        'debug': True
+    }
+    
+    mock_sandbox = Mock(spec=SandboxService)
+    mock_sandbox.is_debug = True
+    mock_sandbox.run_command = AsyncMock()
+    
+    mock_connection = Mock(spec=CDPConnection)
+    mock_connection.ws_url = 'ws://localhost:8080'
+    
+    # Create terminal service
+    terminal = TerminalService(mock_sandbox, mock_connection)
+    print("✓ TerminalService created successfully")
+    
+    # Mock websockets.connect
+    with patch('grasp_sdk.services.terminal.websockets.connect') as mock_connect:
+        mock_ws = AsyncMock()
+        mock_ws.open = True
+        mock_connect.return_value.__aenter__ = AsyncMock(return_value=mock_ws)
+        mock_connect.return_value.__aexit__ = AsyncMock(return_value=None)
+        # For direct await usage
+        async def mock_connect_func(*args, **kwargs):
+            return mock_ws
+        mock_connect.side_effect = mock_connect_func
+        
+        # Mock emitter
+        mock_emitter = MockCommandEventEmitter()
+        mock_sandbox.run_command.return_value = mock_emitter
+        
+        # Test run_command
+        result = await terminal.run_command('echo "Hello World"', {'timeout_ms': 5000})
+        print("✓ run_command executed successfully")
+        
+        # Verify the command was called with correct options
+        mock_sandbox.run_command.assert_called_once()
+        call_args = mock_sandbox.run_command.call_args
+        command_arg = call_args[0][0]
+        options_arg = call_args[0][1]
+        
+        print(f"✓ Command: {command_arg}")
+        print(f"✓ Options: {options_arg}")
+        
+        # Verify inBackground option is set correctly
+        assert options_arg['inBackground'] == True, "inBackground option should be True"
+        assert options_arg['nohup'] == False, "Nohup option should be False"
+        print("✓ Command options verified")
+        
+        # Test result methods
+        response_data = await result.json()
+        print(f"✓ Response JSON: {response_data}")
+        
+        # Test kill method
+        await result.kill()
+        print("✓ Kill method executed successfully")
+    
+    # Test close method
+    terminal.close()
+    print("✓ Terminal service closed successfully")
+    
+    print("✓ All TerminalService tests passed!")
+
+
+async def test_command_options_compatibility():
+    """Test command options compatibility with TypeScript version."""
+    print("\n=== Testing Command Options Compatibility ===")
+    
+    from grasp_sdk.models import ICommandOptions
+    
+    # Test that ICommandOptions supports 'inBackground' parameter
+    options: ICommandOptions = {
+        'inBackground': True,
+        'timeout_ms': 5000,
+        'cwd': '/tmp',
+        'nohup': False
+    }
+    
+    print(f"✓ Command options created: {options}")
+    print("✓ 'inBackground' parameter is supported in ICommandOptions")
+    
+    # Test that we can access the inBackground option
+    background_value = options.get('inBackground', False)
+    assert background_value == True, "inBackground option should be accessible"
+    print("✓ inBackground option accessible and correct")
+    
+    print("✓ All command options compatibility tests passed!")
+
+
+async def main():
+    """Run all tests."""
+    print("Starting Terminal Service Update Tests...")
+    
+    try:
+        await test_streamable_command_result()
+        await test_terminal_service()
+        await test_command_options_compatibility()
+        
+        print("\n🎉 All tests passed! Terminal service updates are working correctly.")
+        print("\n📋 Summary of updates:")
+        print("   • Added kill() method to StreamableCommandResult")
+        print("   • Added response.json() compatibility method")
+        print("   • Maintained ICommandOptions to use 'inBackground' for Python compatibility")
+        print("   • Improved error handling and WebSocket management")
+        print("   • Synchronized timeout values with TypeScript version")
+        
+    except Exception as e:
+        print(f"\n❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())