grasp-sdk 0.1.8__tar.gz → 0.2.0a1__tar.gz

{grasp_sdk-0.1.8/grasp_sdk.egg-info → grasp_sdk-0.2.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grasp_sdk
-Version: 0.1.8
+Version: 0.2.0a1
 Summary: Python SDK for Grasp E2B - Browser automation and sandbox management
 Home-page: https://github.com/grasp-team/grasp-e2b
 Author: Grasp Team
@@ -27,6 +27,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: typing-extensions>=4.8.0
+Requires-Dist: websockets>=12.0
 Requires-Dist: e2b>=1.5.0
 Requires-Dist: e2b-code-interpreter>=1.5.0
 Provides-Extra: dev
@@ -37,8 +38,6 @@ Requires-Dist: flake8>=6.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Provides-Extra: browser
 Requires-Dist: playwright>=1.40.0; extra == "browser"
-Provides-Extra: websocket
-Requires-Dist: websockets>=12.0; extra == "websocket"
 Provides-Extra: validation
 Requires-Dist: pydantic>=2.5.0; extra == "validation"
 Dynamic: author

grasp_sdk-0.2.0a1/examples/example_async_context.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Grasp 异步上下文管理器使用示例"""
+
+import asyncio
+import os
+from grasp_sdk import Grasp
+
+async def example_with_context_manager():
+    """使用异步上下文管理器的完整示例"""
+    print("🚀 Grasp 异步上下文管理器使用示例")
+    
+    # 初始化 Grasp SDK
+    grasp = Grasp({
+        'apiKey': os.environ.get('GRASP_KEY', 'your-api-key-here')
+    })
+    
+    try:
+        # 使用异步上下文管理器启动会话
+        print("\n📱 启动浏览器会话...")
+        async with grasp.launch_context({
+            'browser': {
+                'type': 'chromium',
+                'headless': True,
+                'timeout': 30000
+            }
+        }) as session:
+            print(f"✅ 会话已启动: {type(session).__name__}")
+            
+            # 访问浏览器
+            print(f"🌐 浏览器端点: {session.browser.get_endpoint()}")
+            
+            # 创建终端
+            print("💻 创建终端...")
+            terminal = session.terminal.create()
+            print(f"✅ 终端已创建: {type(terminal).__name__}")
+            
+            # 访问文件系统
+            print(f"📁 文件系统可用: {type(session.files).__name__}")
+            
+            print("\n🔄 在这里可以进行各种操作...")
+            print("   - 浏览器自动化")
+            print("   - 终端命令执行")
+            print("   - 文件系统操作")
+            
+            # 模拟一些工作
+            await asyncio.sleep(0.1)
+            
+        # 会话会在这里自动关闭
+        print("\n🔒 会话已自动关闭")
+        
+    except Exception as e:
+        print(f"❌ 错误: {e}")
+        print("💡 提示: 请确保设置了有效的 GRASP_KEY 环境变量")
+
+async def example_multiple_sessions():
+    """演示多个会话的使用"""
+    print("\n\n🔄 多会话使用示例")
+    
+    grasp = Grasp({
+        'apiKey': os.environ.get('GRASP_KEY', 'your-api-key-here')
+    })
+    
+    try:
+        # 第一个会话
+        print("\n📱 启动第一个会话...")
+        async with grasp.launch_context({
+            'browser': {'type': 'chromium', 'headless': True}
+        }) as session1:
+            print("✅ 第一个会话已启动")
+            await asyncio.sleep(0.1)
+        
+        print("🔒 第一个会话已关闭")
+        
+        # 第二个会话
+        print("\n📱 启动第二个会话...")
+        async with grasp.launch_context({
+            'browser': {'type': 'chromium', 'headless': False}
+        }) as session2:
+            print("✅ 第二个会话已启动")
+            await asyncio.sleep(0.1)
+        
+        print("🔒 第二个会话已关闭")
+        
+    except Exception as e:
+        print(f"❌ 错误: {e}")
+
+async def example_error_handling():
+    """演示错误处理"""
+    print("\n\n⚠️  错误处理示例")
+    
+    grasp = Grasp({'apiKey': 'test-key'})
+    
+    # 尝试重复使用同一个实例
+    try:
+        grasp.launch_context({'browser': {'type': 'chromium'}})
+        
+        async with grasp as session1:
+            print("第一个会话启动")
+            # 尝试在已有会话时启动新会话
+            async with grasp.launch_context({'browser': {'type': 'firefox'}}) as session2:
+                print("这不应该被执行")
+                
+    except RuntimeError as e:
+        print(f"✅ 正确捕获错误: {e}")
+    except Exception as e:
+        print(f"其他错误: {e}")
+
+async def main():
+    """主函数"""
+    await example_with_context_manager()
+    await example_multiple_sessions()
+    await example_error_handling()
+    
+    print("\n\n📚 总结:")
+    print("✅ 异步上下文管理器已成功实现")
+    print("✅ 支持 async with grasp.launch_context(options) as session 语法")
+    print("✅ 自动管理会话生命周期")
+    print("✅ 提供适当的错误处理")
+    print("\n🎉 所有功能测试完成!")
+
+if __name__ == '__main__':
+    asyncio.run(main())

grasp_sdk-0.2.0a1/examples/example_binary_file_support.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating binary file support in Grasp SDK.
+
+This example shows how to:
+1. Read files with different encoding options (utf8, base64, binary)
+2. Write binary content to files
+3. Handle different file types automatically
+"""
+
+import asyncio
+import base64
+from grasp_sdk import Grasp
+
+
+async def main():
+    """Demonstrate binary file support."""
+    
+    # Initialize Grasp
+    grasp = Grasp()
+    
+    try:
+        # Launch browser session
+        session = await grasp.launch({
+            'browser': {
+                'type': 'chromium',
+                'headless': True
+            }
+        })
+        
+        print("✅ Browser session launched successfully")
+        
+        # Get filesystem service
+        fs = session.files
+        
+        # Example 1: Write and read text file with different encodings
+        print("\n📝 Example 1: Text file with different encodings")
+        
+        text_content = "Hello, World! 你好世界! 🌍"
+        await fs.write_file("/tmp/test.txt", text_content)
+        
+        # Read as UTF-8 (default for text files)
+        content_utf8 = await fs.read_file("/tmp/test.txt", {'encoding': 'utf8'})
+        print(f"UTF-8: {content_utf8}")
+        
+        # Read as base64
+        content_base64 = await fs.read_file("/tmp/test.txt", {'encoding': 'base64'})
+        print(f"Base64: {content_base64}")
+        
+        # Read as binary
+        content_binary = await fs.read_file("/tmp/test.txt", {'encoding': 'binary'})
+        print(f"Binary: {content_binary}")
+        
+        # Example 2: Write and read binary content
+        print("\n🔢 Example 2: Binary content")
+        
+        # Create some binary data (a simple PNG-like header)
+        binary_data = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01'
+        
+        # Write binary data
+        await fs.write_file("/tmp/test.png", binary_data)
+        print("✅ Binary data written to /tmp/test.png")
+        
+        # Read binary file (will auto-detect as binary based on extension)
+        content_auto = await fs.read_file("/tmp/test.png")
+        print(f"Auto-detected binary: {type(content_auto)} - {len(content_auto)} bytes")
+        
+        # Read explicitly as base64
+        content_b64 = await fs.read_file("/tmp/test.png", {'encoding': 'base64'})
+        print(f"Base64 encoded: {content_b64}")
+        
+        # Example 3: Working with base64 encoded data
+        print("\n📋 Example 3: Base64 workflow")
+        
+        # Encode some data to base64
+        original_data = b"This is some binary data with special chars: \x00\x01\x02\xFF"
+        b64_encoded = base64.b64encode(original_data).decode('utf-8')
+        
+        # Write the base64 string as text
+        await fs.write_file("/tmp/encoded.txt", b64_encoded)
+        
+        # Read it back and decode
+        read_b64 = await fs.read_file("/tmp/encoded.txt", {'encoding': 'utf8'})
+        decoded_data = base64.b64decode(read_b64)
+        
+        print(f"Original: {original_data}")
+        print(f"Encoded: {b64_encoded}")
+        print(f"Decoded: {decoded_data}")
+        print(f"Match: {original_data == decoded_data}")
+        
+        # Example 4: File type detection
+        print("\n🔍 Example 4: File type detection")
+        
+        test_files = [
+            ("/tmp/text.txt", "Plain text content"),
+            ("/tmp/image.jpg", b"\xFF\xD8\xFF\xE0"),  # JPEG header
+            ("/tmp/document.pdf", b"%PDF-1.4"),      # PDF header
+            ("/tmp/archive.zip", b"PK\x03\x04"),     # ZIP header
+        ]
+        
+        for filepath, content in test_files:
+            await fs.write_file(filepath, content)
+            
+            # Read without specifying encoding (auto-detect)
+            result = await fs.read_file(filepath)
+            
+            if isinstance(result, str):
+                print(f"{filepath}: Detected as text - {result[:50]}...")
+            else:
+                print(f"{filepath}: Detected as binary - {len(result)} bytes")
+        
+        print("\n✅ All examples completed successfully!")
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+    
+    finally:
+        # Clean up
+        try:
+            await session.close()
+            print("🧹 Cleanup completed")
+        except Exception as e:
+            print(f"⚠️ Cleanup error: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

grasp_sdk-0.2.0a1/examples/example_grasp_usage.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Example usage of the new Grasp classes."""
+
+import asyncio
+import os
+from grasp_sdk import Grasp, GraspSession, launch_browser
+
+
+async def example_grasp_usage():
+    """Example demonstrating how to use the new Grasp classes."""
+    print("=== Grasp SDK Python Implementation Example ===")
+    
+    # Initialize Grasp SDK
+    grasp = Grasp({
+        'apiKey': os.environ.get('GRASP_KEY', 'your-api-key-here')
+    })
+    
+    print(f"Initialized Grasp SDK with API key: {grasp.key[:8]}...")
+    
+    # Example 1: Launch a new browser session
+    print("\n1. Launching a new browser session...")
+    try:
+        session = await grasp.launch({
+            'browser': {
+                'type': 'chromium',
+                'headless': True,
+                'timeout': 30000
+            }
+        })
+        print(f"✓ Session launched with ID: {session.id}")
+        
+        # Access browser endpoint
+        browser_endpoint = session.browser.get_endpoint()
+        print(f"✓ Browser WebSocket endpoint: {browser_endpoint}")
+        
+        # Create terminal
+        terminal = session.terminal.create()
+        print("✓ Terminal service created")
+        
+        # Access file system
+        print(f"✓ File system service available: {type(session.files).__name__}")
+        
+        # Close session
+        await session.close()
+        print("✓ Session closed successfully")
+        
+    except Exception as e:
+        print(f"❌ Error launching session: {e}")
+        print("Note: This requires a valid API key and network access")
+    
+    # Example 2: Using static method
+    print("\n2. Using static launch_browser method...")
+    try:
+        connection = await launch_browser({
+            'type': 'chromium',
+            'headless': True
+        })
+        print(f"✓ Browser launched with connection: {connection.ws_url}")
+        
+    except Exception as e:
+        print(f"❌ Error with static method: {e}")
+        print("Note: This requires a valid API key and network access")
+    
+    # Example 3: Connect to existing session
+    print("\n3. Connecting to existing session...")
+    try:
+        # This would connect to an existing session ID
+        # session = await grasp.connect('existing-session-id')
+        print("✓ Connection method available (requires existing session ID)")
+        
+    except Exception as e:
+        print(f"❌ Error connecting: {e}")
+    
+    print("\n=== Example completed ===")
+    print("\nFor full functionality, ensure you have:")
+    print("- Valid GRASP_KEY environment variable")
+    print("- Network access to Grasp services")
+    print("- Proper sandbox configuration")
+
+
+if __name__ == '__main__':
+    asyncio.run(example_grasp_usage())

grasp_sdk-0.2.0a1/examples/example_readfile_usage.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+Example usage of the readFile functionality in Grasp Python SDK.
+
+This example demonstrates:
+1. How to create a filesystem service
+2. How to write files to sandbox
+3. How to read files from sandbox
+4. Error handling for file operations
+"""
+
+import asyncio
+import os
+from grasp_sdk import Grasp
+
+
+async def main():
+    """Main example function."""
+    print("📚 Grasp SDK readFile Example")
+    print("==============================")
+    
+    session = None
+    try:
+        # Launch browser and get session
+        print("\n🚀 Step 1: Launching browser...")
+        grasp = Grasp()
+        session = await grasp.launch({
+            'browser': {
+                'headless': True,
+                'debug': False  # Set to True for more detailed logs
+            },
+            'keepAliveMS': 30000,
+            'timeout': 60000
+        })
+        print(f"✅ Browser launched! Session ID: {session.id}")
+        
+        # Get filesystem service from session
+        print("\n📁 Step 2: Getting filesystem service...")
+        filesystem = session.files
+        print("✅ Filesystem service ready!")
+        
+        # Example 1: Write and read a text file
+        print("\n📝 Example 1: Text file operations")
+        print("-" * 40)
+        
+        text_file_path = "/home/user/example.txt"
+        text_content = """Hello from Grasp SDK!
+
+This is an example text file.
+It contains multiple lines and unicode: 你好世界 🌍
+
+Timestamp: $(date)
+"""
+        
+        print(f"Writing content to {text_file_path}...")
+        await filesystem.write_file(text_file_path, text_content)
+        print("✅ File written successfully!")
+        
+        print(f"Reading content from {text_file_path}...")
+        read_content = await filesystem.read_file(text_file_path)
+        print("✅ File read successfully!")
+        print(f"📄 Content preview (first 100 chars): {repr(read_content[:100])}...")
+        
+        # Example 2: Read a configuration file
+        print("\n⚙️  Example 2: Configuration file")
+        print("-" * 40)
+        
+        config_path = "/home/user/config.json"
+        config_content = '''{
+  "app_name": "My Grasp App",
+  "version": "1.0.0",
+  "settings": {
+    "debug": true,
+    "max_connections": 100,
+    "allowed_origins": ["localhost", "*.example.com"]
+  }
+}'''
+        
+        await filesystem.write_file(config_path, config_content)
+        config_data = await filesystem.read_file(config_path)
+        
+        # Parse JSON
+        import json
+        parsed_config = json.loads(config_data)
+        print(f"✅ Config loaded: {parsed_config['app_name']} v{parsed_config['version']}")
+        
+        # Example 3: Error handling
+        print("\n🚨 Example 3: Error handling")
+        print("-" * 40)
+        
+        try:
+            await filesystem.read_file("/home/user/nonexistent.txt")
+            print("❌ This should not happen!")
+        except Exception as e:
+            print(f"✅ Correctly caught error: {type(e).__name__}: {e}")
+        
+        # Example 4: Binary file handling (simulated)
+        print("\n🖼️  Example 4: Binary file handling")
+        print("-" * 40)
+        
+        # Create a fake binary file (in real usage, this might be an image)
+        binary_path = "/home/user/data.bin"
+        binary_content = "This simulates binary data\x00\x01\x02\xFF"
+        
+        await filesystem.write_file(binary_path, binary_content)
+        binary_data = await filesystem.read_file(binary_path)
+        
+        print(f"✅ Binary file handled (length: {len(binary_data)} chars)")
+        print(f"📊 Data preview: {repr(binary_data[:50])}...")
+        
+        print("\n🎉 All examples completed successfully!")
+        
+    except Exception as e:
+        print(f"\n❌ Example failed: {e}")
+        import traceback
+        traceback.print_exc()
+        
+    finally:
+        if session:
+            print("\n🧹 Cleaning up...")
+            await session.close()
+            print("✅ Cleanup completed!")
+
+
+if __name__ == "__main__":
+    print("Starting Grasp SDK readFile example...")
+    
+    # Check environment
+    if not os.getenv('GRASP_KEY'):
+        print("\n⚠️  Warning: GRASP_KEY environment variable not set.")
+        print("   Please set your Grasp API key to run this example:")
+        print("   export GRASP_KEY='your-api-key-here'")
+        print("\n   You can get your API key from: https://grasp.dev/dashboard")
+        exit(1)
+    
+    asyncio.run(main())

grasp_sdk-0.2.0a1/examples/grasp_terminal.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Grasp Terminal Example
+
+This example demonstrates how to use the Grasp Terminal service
+to run commands and manage files in a sandbox environment.
+
+Equivalent to the TypeScript version in examples/grasp-terminal.ts
+"""
+
+import asyncio
+import os
+import sys
+from typing import Dict, Any
+from dotenv import load_dotenv
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from grasp_sdk import Grasp
+
+# 加载环境变量
+load_dotenv("../.env.grasp")
+
+async def main():
+    """Main function demonstrating terminal service usage."""
+    print("🚀 Starting Grasp Terminal example...")
+    
+    try:
+        grasp = Grasp()
+        session = await grasp.launch({
+            'browser': {
+                # 'type': 'chrome-stable',
+                # 'headless': False,
+                # 'adblock': True,
+                # 'debug': True,
+            },
+            'keepAliveMS': 10000,
+            'timeout': 3600000,  # 容器最长运行1小时（最大值可以为一天 86400000）
+        })
+
+        connection = session.browser.connection
+        print(f"✅ Browser launched! Connection ID: {connection.id}")
+        
+        # Create terminal connection
+        print("📡 Creating terminal connection...")
+        terminal = session.terminal.create()
+        
+        print("✅ Terminal connected!")
+        
+        # Test FFmpeg availability (equivalent to TypeScript version)
+        print("🔍 Checking FFmpeg availability...")
+        command = await terminal.run_command('ffmpeg')
+        result = await command.json()
+        print(f"FFmpeg version check result: {result}")
+        
+        # Create and write a test JavaScript file
+        print("📝 Writing test JavaScript file...")
+        code = """
+(async function() {
+  for(let i = 0; i < 10; i++) {
+    console.log(i);
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+})();
+"""
+        await session.files.write_file('test.js', code)
+        print("✅ File 'test.js' written successfully!")
+        
+        # Run the Node.js script
+        print("🚀 Running Node.js script...")
+        command2 = await terminal.run_command('node test.js')
+        
+        # Handle streaming output (Python equivalent of TypeScript pipe)
+        print("📊 Streaming output:")
+        
+        # Set up stdout streaming
+        # Set up event handlers for real-time output (much simpler!)
+        def handle_stdout(data):
+            print(f"STDOUT: {data}", end='')
+        
+        def handle_stderr(data):
+            print(f"STDERR: {data}", end='', file=sys.stderr)
+        
+        # Register event handlers - now it works just like Node.js!
+        command2.on('stdout', handle_stdout)
+        command2.on('stderr', handle_stderr)
+        
+        # Wait for command completion
+        await command2.end()
+        
+        # Close terminal connection
+        # print("🔌 Closing terminal connection...")
+        # terminal.close()
+        
+        # Close the session
+        print("🛑 Closing session...")
+        await session.close()
+        
+        print("✅ Example completed successfully!")
+        
+    except Exception as error:
+        print(f"❌ Error occurred: {error}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == '__main__':
+    # Run the async main function
+    asyncio.run(main())

grasp_sdk-0.1.8/example_usage.py → grasp_sdk-0.2.0a1/examples/grasp_usage.py

@@ -11,7 +11,15 @@ from pathlib import Path
 from playwright.async_api import async_playwright
 from dotenv import load_dotenv
 
-from grasp_sdk import GraspServer
+import sys
+from pathlib import Path
+
+from websockets import connect
+
+# 添加父目录到 Python 路径，以便导入 grasp_sdk
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from grasp_sdk import Grasp, GraspServer
 from grasp_sdk.models import IBrowserConfig, ISandboxConfig
 
 # 加载环境变量
@@ -31,24 +39,26 @@ async def main():
 
     print("🚀 正在启动浏览器...")
 
-    async with GraspServer({
-            # 'key': api_key,
-            # 'type': 'chrome-stable',
-            # 'headless': False,
-            # 'adblock': True,
-            # 'debug': True,
+    async with Grasp().launch_context({
+            'browser': {
+                # 'type': 'chrome-stable',
+                # 'headless': False,
+                # 'adblock': True,
+            },
+            'debug': True,
             'timeout': 3600000,  # 容器最长运行1小时（最大值可以为一天 86400000）
-        }) as connection:
-    
+        }) as session:
+
         try:
+            connection = session.browser.connection
             print(f"连接信息: {connection}")
-            print(f"WebSocket URL: {connection['ws_url']}")
-            print(f"HTTP URL: {connection['http_url']}")
+            print(f"WebSocket URL: {connection.ws_url}")
+            print(f"HTTP URL: {connection.http_url}")
             
             # 使用 Playwright 连接到 CDP
             async with async_playwright() as p:
                 browser = await p.chromium.connect_over_cdp(
-                    connection['ws_url'],
+                    session.browser.get_endpoint(),
                     timeout=150000
                 )