grasp-sdk 0.1.8__py3-none-any.whl → 0.2.0a1__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_get_replay_screenshots.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""测试 get_replay_screenshots 功能的示例脚本
+
+这个脚本演示如何使用 get_replay_screenshots 函数获取截图目录路径。
+"""
+
+import asyncio
+import os
+from grasp_sdk import launch_browser, get_replay_screenshots
+
+
+async def test_get_replay_screenshots():
+    """测试 get_replay_screenshots 功能"""
+    print("🚀 启动浏览器服务...")
+    
+    try:
+        # 启动浏览器并获取连接信息
+        connection = await launch_browser({
+            'headless': True,
+            'type': 'chromium'
+        })
+        
+        print(f"✅ 浏览器启动成功!")
+        print(f"连接 ID: {connection.id}")
+        print(f"WebSocket URL: {connection.ws_url or connection.ws_url}")
+        print(f"HTTP URL: {connection.http_url}")
+        
+        # 获取截图目录路径
+        print("\n📸 获取截图目录路径...")
+        screenshots_dir = await get_replay_screenshots(connection)
+        
+        print(f"✅ 截图目录路径: {screenshots_dir}")
+        
+        # 检查目录是否存在
+        if os.path.exists(screenshots_dir):
+            print(f"📁 目录已存在")
+            
+            # 列出目录中的文件
+            files = os.listdir(screenshots_dir)
+            if files:
+                print(f"📋 目录中有 {len(files)} 个文件:")
+                for file in files[:5]:  # 只显示前5个文件
+                    print(f"  - {file}")
+                if len(files) > 5:
+                    print(f"  ... 还有 {len(files) - 5} 个文件")
+            else:
+                print("📂 目录为空")
+        else:
+            print(f"⚠️  目录不存在，将在首次使用时创建")
+        
+        # 测试错误处理
+        print("\n🧪 测试错误处理...")
+        
+        # 测试缺少 id 字段的情况
+        try:
+            invalid_connection = {
+                'ws_url': connection.ws_url,
+                'http_url': connection.http_url
+                # 缺少 'id' 字段
+            }
+            await get_replay_screenshots(invalid_connection)
+        except ValueError as e:
+            print(f"✅ 正确捕获 ValueError: {e}")
+        
+        # 测试无效 ID 的情况
+        try:
+            invalid_connection = {
+                'id': 'invalid-id-123',
+                'ws_url': connection.ws_url,
+                'http_url': connection.http_url
+            }
+            await get_replay_screenshots(invalid_connection)
+        except KeyError as e:
+            print(f"✅ 正确捕获 KeyError: {e}")
+        
+        print("\n🎉 所有测试完成!")
+        
+    except Exception as e:
+        print(f"❌ 测试失败: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    # 检查环境变量
+    if not os.getenv('GRASP_KEY'):
+        print("⚠️  警告: 未设置 GRASP_KEY 环境变量")
+        print("请设置: export GRASP_KEY=your_api_key")
+    
+    # 运行测试
+    asyncio.run(test_get_replay_screenshots())

examples/test_grasp_classes.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""测试 Grasp 类的功能"""
+
+import os
+from grasp_sdk import Grasp, GraspSession, GraspBrowser, GraspTerminal
+
+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(f"   ✓ GraspTerminal 类可用: {GraspTerminal 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, GraspTerminal
+        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_shutdown_deprecation.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""
+测试 shutdown 方法的废弃警告
+"""
+
+import warnings
+import sys
+import os
+
+# 添加项目路径
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from grasp_sdk import shutdown
+
+def test_shutdown_deprecation():
+    """测试 shutdown 方法是否正确发出废弃警告"""
+    print("🧪 测试 shutdown 方法的废弃警告...")
+    
+    # 设置警告过滤器显示所有警告
+    warnings.filterwarnings("always")
+    
+    # 捕获警告
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        
+        print("📞 调用 shutdown(None)...")
+        
+        # 调用废弃的 shutdown 方法
+        try:
+            shutdown(None)
+            print("✅ shutdown 方法调用完成")
+        except SystemExit:
+            print("⚠️  shutdown 方法触发了系统退出")
+        except Exception as e:
+            print(f"⚠️  shutdown 方法调用出现异常: {e}")
+        
+        # 检查是否有废弃警告
+        print(f"\n📊 捕获到 {len(w)} 个警告")
+        deprecation_warnings = [warning for warning in w if issubclass(warning.category, DeprecationWarning)]
+        
+        if deprecation_warnings:
+            print(f"✅ 检测到 {len(deprecation_warnings)} 个废弃警告:")
+            for warning in deprecation_warnings:
+                print(f"   - {warning.message}")
+                print(f"     文件: {warning.filename}:{warning.lineno}")
+        else:
+            print("❌ 未检测到废弃警告")
+            if w:
+                print("其他警告:")
+                for warning in w:
+                    print(f"   - {warning.category.__name__}: {warning.message}")
+    
+    print("\n📋 废弃方法迁移指南:")
+    print("   旧方式: shutdown(connection)")
+    print("   新方式: await session.close()")
+    print("\n💡 建议:")
+    print("   - 使用 grasp.launch() 获取 session")
+    print("   - 使用 await session.close() 关闭会话")
+    print("   - 避免直接使用 shutdown() 方法")
+
+if __name__ == '__main__':
+    test_shutdown_deprecation()