grasp-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

{grasp_sdk-0.1.0/grasp_sdk.egg-info → grasp_sdk-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grasp_sdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for Grasp E2B - Browser automation and sandbox management
 Home-page: https://github.com/grasp-team/grasp-e2b
 Author: Grasp Team
@@ -73,35 +73,90 @@ pip install -e ".[dev]"
 
 ## 🔧 Quick Start
 
+### Using GraspServer Context Manager (Recommended)
+
 ```python
 import asyncio
+import os
+from pathlib import Path
+from playwright.async_api import async_playwright
+from dotenv import load_dotenv
+
 from grasp_sdk import GraspServer
+from grasp_sdk.models import IBrowserConfig, ISandboxConfig
+
+# 加载环境变量
+load_dotenv("../.env.grasp")
 
 async def main():
-    # Initialize Grasp server
-    server = GraspServer({
-        "key": api_key,
-        "timeout": 30000,
-    })
+    """主函数：演示 Grasp SDK 的基本用法"""
     
-    try:
-        # Start sandbox
-        await server.start()
-        
-        # Execute command
-        result = await server.execute_command("echo 'Hello from Python!'")
-        print(f"Output: {result.stdout}")
-        
-        # Browser automation
-        browser_task = await server.create_browser_task()
-        await browser_task.navigate("https://example.com")
-        screenshot = await browser_task.screenshot("example.png")
+    # 检查是否有 API key
+    api_key = os.getenv('GRASP_KEY')
+    if not api_key:
+        print("⚠️ 警告：未设置 GRASP_KEY 环境变量")
+        print("请设置 GRASP_KEY 环境变量或在 .env 文件中配置")
+        print("示例：export GRASP_KEY=your_api_key_here")
+        return
+
+    print("🚀 正在启动浏览器...")
+
+    async with GraspServer({
+            # 'key': api_key,
+            # 'type': 'chrome-stable',
+            # 'headless': False,
+            # 'adblock': True,
+            # 'debug': True,
+            'timeout': 3600000,  # 容器最长运行1小时（最大值可以为一天 86400000）
+        }) as connection:
+    
+        try:
+            print(f"连接信息: {connection}")
+            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'],
+                    timeout=150000
+                )
+                
+                # 创建第一个页面并访问网站
+                page1 = await browser.new_page()
+                await page1.goto('https://getgrasp.ai/', wait_until='domcontentloaded')
+                await page1.screenshot(path='grasp-ai.png')
+                await page1.close()
+                
+                # 获取或创建上下文
+                contexts = browser.contexts
+                context = contexts[0] if contexts else await browser.new_context()
+                
+                # 创建第二个页面
+                page2 = await context.new_page()
+                
+                # 将 HTML 字符串渲染到页面中
+                await page2.set_content('<h1>Hello Grasp</h1>', wait_until='networkidle')
+                
+                # 截图演示
+                await page2.screenshot(path='hello-world.png', full_page=True)
+                
+                # 清理资源
+                await page2.close()
+                await context.close()
+                await browser.close()
+                
+            print('✅ 任务完成。')
+            
+        except Exception as e:
+            print(f"❌ 执行过程中出现错误: {str(e)}")
+            raise
         
-    finally:
-        # Clean up
-        await server.close()
+        finally:
+            # 注意：使用 GraspServer 上下文管理器时，资源会自动清理
+            print("程序结束，资源将自动清理")
 
-if __name__ == "__main__":
+if __name__ == '__main__':
     asyncio.run(main())
 ```
 
@@ -145,13 +200,32 @@ GRASP_TEMPLATE=python
 
 ## 🧪 Development
 
+### Quick Setup
+
 ```bash
-# Install development dependencies
+# Install development dependencies automatically
+python install_dev_deps.py
+
+# Or manually install
 pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Simple tests (no pytest required)
+python test_connect_simple.py
+
+# Full test suite (requires pytest)
+pytest tests/
+
+# Run specific test file
+pytest tests/test_connect.py -v
+```
 
-# Run tests
-pytest
+### Code Quality
 
+```bash
 # Format code
 black .
 isort .
@@ -163,22 +237,54 @@ mypy .
 flake8 .
 ```
 
+### Examples
+
+```bash
+# Run Connect usage examples
+python example_connect.py
+```
+
 ## 📚 API Reference
 
+### GraspServer (Recommended)
+
+Async context manager for automatic sandbox resource management and browser automation.
+
+```python
+class GraspServer:
+    def __init__(self, options: Optional[Dict[str, Any]] = None)
+    async def __aenter__(self) -> Dict[str, Any]  # Returns connection info
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None
+```
+
+**Usage:**
+```python
+async with GraspServer(options) as connection:
+    # connection contains: {'id', 'ws_url', 'http_url'}
+    # Automatic cleanup on exit
+```
+
+**Options:**
+- `key`: Your Grasp API key (loaded from environment if not provided)
+- `type`: Browser type ('chromium' or 'chrome-stable')
+- `headless`: Run in headless mode (default: True)
+- `adblock`: Enable adblock (default: False)
+- `debug`: Enable debug mode (default: False)
+- `timeout`: Container maximum runtime in milliseconds (default: 30000, max: 86400000)
+
 ### GraspServer
 
 Main class for interacting with E2B sandboxes and browser automation.
 
 ```python
 class GraspServer:
-    def __init__(self, config: ISandboxConfig = None)
-    async def start(self) -> None
-    async def close(self) -> None
-    async def execute_command(self, command: str, options: ICommandOptions = None) -> CommandResult
-    async def execute_script(self, script_path: str, options: IScriptOptions = None) -> CommandResult
-    async def create_browser_task(self, config: IBrowserConfig = None) -> BrowserTask
-    def get_sandbox_status(self) -> SandboxStatus
-    def get_sandbox_id(self) -> str
+    def __init__(self, sandbox_config: Optional[Dict[str, Any]] = None)
+    async def create_browser_task(self, browser_type: str = 'chromium', config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
+    async def cleanup(self) -> None
+    def get_status(self) -> Optional[SandboxStatus]
+    def get_sandbox_id(self) -> Optional[str]
+    @property
+    def sandbox(self) -> Optional[SandboxService]
 ```
 
 ## 🤝 Compatibility

grasp_sdk-0.1.2/README.md

@@ -0,0 +1,260 @@
+# Grasp SDK - Python Implementation
+
+🐍 Python implementation of Grasp SDK for E2B platform providing secure command execution and browser automation in isolated cloud environments.
+
+## 🚀 Features
+
+- **Secure Execution**: Run commands and scripts in isolated E2B sandboxes
+- **Browser Automation**: Control Chromium browsers with Playwright integration
+- **Async/Await Support**: Full async/await support for modern Python development
+- **Type Safety**: Complete type hints with Pydantic models
+- **WebSocket Communication**: Real-time communication with sandbox environments
+- **Multi-language Support**: Compatible with Node.js/TypeScript version
+
+## 📦 Installation
+
+```bash
+# Install from PyPI (when published)
+pip install grasp-sdk
+
+# Install from source
+pip install -e .
+
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+## 🔧 Quick Start
+
+### Using GraspServer Context Manager (Recommended)
+
+```python
+import asyncio
+import os
+from pathlib import Path
+from playwright.async_api import async_playwright
+from dotenv import load_dotenv
+
+from grasp_sdk import GraspServer
+from grasp_sdk.models import IBrowserConfig, ISandboxConfig
+
+# 加载环境变量
+load_dotenv("../.env.grasp")
+
+async def main():
+    """主函数：演示 Grasp SDK 的基本用法"""
+    
+    # 检查是否有 API key
+    api_key = os.getenv('GRASP_KEY')
+    if not api_key:
+        print("⚠️ 警告：未设置 GRASP_KEY 环境变量")
+        print("请设置 GRASP_KEY 环境变量或在 .env 文件中配置")
+        print("示例：export GRASP_KEY=your_api_key_here")
+        return
+
+    print("🚀 正在启动浏览器...")
+
+    async with GraspServer({
+            # 'key': api_key,
+            # 'type': 'chrome-stable',
+            # 'headless': False,
+            # 'adblock': True,
+            # 'debug': True,
+            'timeout': 3600000,  # 容器最长运行1小时（最大值可以为一天 86400000）
+        }) as connection:
+    
+        try:
+            print(f"连接信息: {connection}")
+            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'],
+                    timeout=150000
+                )
+                
+                # 创建第一个页面并访问网站
+                page1 = await browser.new_page()
+                await page1.goto('https://getgrasp.ai/', wait_until='domcontentloaded')
+                await page1.screenshot(path='grasp-ai.png')
+                await page1.close()
+                
+                # 获取或创建上下文
+                contexts = browser.contexts
+                context = contexts[0] if contexts else await browser.new_context()
+                
+                # 创建第二个页面
+                page2 = await context.new_page()
+                
+                # 将 HTML 字符串渲染到页面中
+                await page2.set_content('<h1>Hello Grasp</h1>', wait_until='networkidle')
+                
+                # 截图演示
+                await page2.screenshot(path='hello-world.png', full_page=True)
+                
+                # 清理资源
+                await page2.close()
+                await context.close()
+                await browser.close()
+                
+            print('✅ 任务完成。')
+            
+        except Exception as e:
+            print(f"❌ 执行过程中出现错误: {str(e)}")
+            raise
+        
+        finally:
+            # 注意：使用 GraspServer 上下文管理器时，资源会自动清理
+            print("程序结束，资源将自动清理")
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## 🏗️ Architecture
+
+The Python implementation mirrors the Node.js/TypeScript version:
+
+```
+py-src/
+├── __init__.py              # Main package exports
+├── grasp_server.py          # Main GraspServer class
+├── services/                # Core services
+│   ├── __init__.py
+│   ├── sandbox_service.py   # E2B sandbox management
+│   └── browser_service.py   # Browser automation
+├── types/                   # Type definitions
+│   └── __init__.py
+├── utils/                   # Utilities
+│   ├── __init__.py
+│   ├── config.py           # Configuration management
+│   ├── logger.py           # Logging utilities
+│   └── auth.py             # Authentication
+├── cli/                     # Command line interface
+│   ├── __init__.py
+│   └── main.py
+└── tests/                   # Test suite
+    └── ...
+```
+
+## 🔑 Environment Variables
+
+```bash
+# Required
+E2B_API_KEY=your_e2b_api_key_here
+
+# Optional
+GRASP_LOG_LEVEL=info
+GRASP_TIMEOUT=30000
+GRASP_TEMPLATE=python
+```
+
+## 🧪 Development
+
+### Quick Setup
+
+```bash
+# Install development dependencies automatically
+python install_dev_deps.py
+
+# Or manually install
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Simple tests (no pytest required)
+python test_connect_simple.py
+
+# Full test suite (requires pytest)
+pytest tests/
+
+# Run specific test file
+pytest tests/test_connect.py -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+black .
+isort .
+
+# Type checking
+mypy .
+
+# Linting
+flake8 .
+```
+
+### Examples
+
+```bash
+# Run Connect usage examples
+python example_connect.py
+```
+
+## 📚 API Reference
+
+### GraspServer (Recommended)
+
+Async context manager for automatic sandbox resource management and browser automation.
+
+```python
+class GraspServer:
+    def __init__(self, options: Optional[Dict[str, Any]] = None)
+    async def __aenter__(self) -> Dict[str, Any]  # Returns connection info
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None
+```
+
+**Usage:**
+```python
+async with GraspServer(options) as connection:
+    # connection contains: {'id', 'ws_url', 'http_url'}
+    # Automatic cleanup on exit
+```
+
+**Options:**
+- `key`: Your Grasp API key (loaded from environment if not provided)
+- `type`: Browser type ('chromium' or 'chrome-stable')
+- `headless`: Run in headless mode (default: True)
+- `adblock`: Enable adblock (default: False)
+- `debug`: Enable debug mode (default: False)
+- `timeout`: Container maximum runtime in milliseconds (default: 30000, max: 86400000)
+
+### GraspServer
+
+Main class for interacting with E2B sandboxes and browser automation.
+
+```python
+class GraspServer:
+    def __init__(self, sandbox_config: Optional[Dict[str, Any]] = None)
+    async def create_browser_task(self, browser_type: str = 'chromium', config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]
+    async def cleanup(self) -> None
+    def get_status(self) -> Optional[SandboxStatus]
+    def get_sandbox_id(self) -> Optional[str]
+    @property
+    def sandbox(self) -> Optional[SandboxService]
+```
+
+## 🤝 Compatibility
+
+This Python implementation provides the same API surface as the Node.js/TypeScript version, ensuring:
+
+- **Feature Parity**: All features available in both implementations
+- **API Consistency**: Same method names and behavior
+- **Type Safety**: Equivalent type definitions using TypedDict and Pydantic
+- **Error Handling**: Consistent error types and messages
+
+## 📄 License
+
+MIT License - see the [LICENSE](../LICENSE) file for details.
+
+## 🔗 Related
+
+- [Node.js/TypeScript Implementation](../src/)
+- [E2B Platform](https://e2b.dev/)
+- [Playwright Python](https://playwright.dev/python/)

grasp_sdk-0.1.2/example_usage.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Grasp SDK Python 使用示例
+
+这个示例展示了如何使用 grasp_sdk 启动浏览器、连接 CDP、执行基本操作并截图。
+"""
+
+import asyncio
+import os
+from pathlib import Path
+from playwright.async_api import async_playwright
+from dotenv import load_dotenv
+
+from grasp_sdk import GraspServer
+from grasp_sdk.models import IBrowserConfig, ISandboxConfig
+
+# 加载环境变量
+load_dotenv("../.env.grasp")
+
+
+async def main():
+    """主函数：演示 Grasp SDK 的基本用法"""
+    
+    # 检查是否有 API key
+    api_key = os.getenv('GRASP_KEY')
+    if not api_key:
+        print("⚠️ 警告：未设置 GRASP_KEY 环境变量")
+        print("请设置 GRASP_KEY 环境变量或在 .env 文件中配置")
+        print("示例：export GRASP_KEY=your_api_key_here")
+        return
+
+    print("🚀 正在启动浏览器...")
+
+    async with GraspServer({
+            # 'key': api_key,
+            # 'type': 'chrome-stable',
+            # 'headless': False,
+            # 'adblock': True,
+            # 'debug': True,
+            'timeout': 3600000,  # 容器最长运行1小时（最大值可以为一天 86400000）
+        }) as connection:
+    
+        try:
+            print(f"连接信息: {connection}")
+            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'],
+                    timeout=150000
+                )
+                
+                # 等待一段时间（可选）
+                # await asyncio.sleep(10)
+                
+                # 创建第一个页面并访问网站
+                page1 = await browser.new_page()
+                await page1.goto('https://getgrasp.ai/', wait_until='domcontentloaded')
+                await page1.screenshot(path='grasp-ai.png')
+                await page1.close()
+                
+                # 获取或创建上下文
+                contexts = browser.contexts
+                context = contexts[0] if contexts else await browser.new_context()
+                
+                # 创建第二个页面
+                page2 = await context.new_page()
+                
+                # 将 HTML 字符串渲染到页面中
+                await page2.set_content('<h1>Hello Grasp</h1>', wait_until='networkidle')
+                
+                # 等待特定元素可见（可选）
+                # await page2.wait_for_selector('#my-element')
+                
+                # 截图演示
+                await page2.screenshot(path='hello-world.png', full_page=True)
+                
+                # 清理资源
+                await page2.close()
+                await context.close()
+                await browser.close()
+                
+            # print('⏳ 等待10秒...')
+            # await asyncio.sleep(10)
+            print('✅ 任务完成。')
+            
+        except Exception as e:
+            print(f"❌ 执行过程中出现错误: {str(e)}")
+            raise
+        
+        finally:
+            # 注意：使用 launch_browser 函数时，资源会在程序退出时自动清理
+            # 如果需要手动清理，可以使用 GraspServer 类的实例方法
+            print("程序结束，资源将自动清理")
+
+
+if __name__ == '__main__':
+    # 运行主函数
+    asyncio.run(main())

{grasp_sdk-0.1.0 → grasp_sdk-0.1.2}/grasp_sdk/__init__.py

@@ -24,7 +24,7 @@ from .models import (
     SandboxStatus,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __author__ = "Grasp Team"
 __email__ = "team@grasp.dev"
 
@@ -40,6 +40,19 @@ class GraspServer:
         """
         if sandbox_config is None:
             sandbox_config = {}
+        
+        # Extract browser-specific options
+        browser_type = sandbox_config.pop('type', 'chromium')
+        headless = sandbox_config.pop('headless', True)
+        adblock = sandbox_config.pop('adblock', False)
+
+        self.__browser_type = browser_type
+        
+        # Create browser task
+        self.__browser_config = {
+            'headless': headless,
+            'envs': {'ADBLOCK': 'true' if adblock else 'false'}
+        }
             
         config = get_config()
         config['sandbox'].update(sandbox_config)
@@ -55,6 +68,22 @@ class GraspServer:
             f'GraspE2B initialized (templateId: {config["sandbox"]["templateId"]})'
         )
     
+    async def __aenter__(self):
+        connection = await self.create_browser_task()
+    
+        # Register server
+        # if connection['id']:
+        #    _servers[connection['id']] = self
+            
+        return connection
+    
+    async def __aexit__(self, exc_type, exc, tb):
+        if self.browser_service and self.browser_service.id:
+            service_id = self.browser_service.id
+            self.logger.info(f'Closing browser service {service_id}')
+            await _servers[service_id].cleanup()
+            del _servers[service_id]
+    
     @property
     def sandbox(self) -> Optional[SandboxService]:
         """Get the underlying sandbox service.
@@ -82,8 +111,6 @@ class GraspServer:
     
     async def create_browser_task(
         self, 
-        browser_type: Literal['chrome-stable', 'chromium'] = 'chromium',
-        config: Optional[Dict[str, Any]] = None
     ) -> Dict[str, Any]:
         """Create and launch a browser task.
         
@@ -100,6 +127,9 @@ class GraspServer:
         if self.browser_service:
             raise RuntimeError('Browser service can only be initialized once')
         
+        config = self.__browser_config
+        browser_type = self.__browser_type
+
         if config is None:
             config = {}
             
@@ -132,6 +162,12 @@ class GraspServer:
             browser_config
         )
         await self.browser_service.initialize()
+
+        # Register server
+        _servers[str(self.browser_service.id)] = self
+        self.logger.info("🚀 Browser service initialized", {
+            'id': self.browser_service.id,
+        })
         
         self.logger.info('🌐 Launching Chromium browser with CDP...')
         cdp_connection = await self.browser_service.launch_browser(browser_type)
@@ -180,25 +216,11 @@ async def launch_browser(
         
     Returns:
         Dictionary containing connection information
-    """
-    if options is None:
-        options = {}
-        
-    # Extract browser-specific options
-    browser_type = options.pop('type', 'chromium')
-    headless = options.pop('headless', True)
-    adblock = options.pop('adblock', False)
-    
+    """    
     # Create server instance
     server = GraspServer(options)
     
-    # Create browser task
-    browser_config = {
-        'headless': headless,
-        'envs': {'ADBLOCK': 'true' if adblock else 'false'}
-    }
-    
-    connection = await server.create_browser_task(browser_type, browser_config)
+    connection = await server.create_browser_task()
     
     # Register server
     if connection['id']:
@@ -258,5 +280,5 @@ __all__ = [
 
 # Default export equivalent
 default = {
-    'launch_browser': launch_browser,
+    'GraspServer': GraspServer,
 }