grasp-sdk 0.1.0__tar.gz

grasp_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,30 @@
+# Include documentation and configuration files
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+include setup.py
+
+# Include all Python source files
+recursive-include . *.py
+recursive-include . *.pyi
+
+# Include type stubs
+recursive-include . py.typed
+
+# Include sandbox scripts
+recursive-include grasp_sdk/sandbox *.mjs
+recursive-include grasp_sdk/sandbox *.js
+recursive-include grasp_sdk/sandbox *.json
+
+# Exclude development and build files
+exclude .gitignore
+exclude .env*
+recursive-exclude . __pycache__
+recursive-exclude . *.pyc
+recursive-exclude . *.pyo
+recursive-exclude . .pytest_cache
+recursive-exclude . .mypy_cache
+recursive-exclude . *.egg-info
+recursive-exclude . build
+recursive-exclude . dist

grasp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: grasp_sdk
+Version: 0.1.0
+Summary: Python SDK for Grasp E2B - Browser automation and sandbox management
+Home-page: https://github.com/grasp-team/grasp-e2b
+Author: Grasp Team
+Author-email: Grasp Team <team@grasp.com>
+Project-URL: Homepage, https://github.com/grasp-team/grasp-e2b
+Project-URL: Bug Reports, https://github.com/grasp-team/grasp-e2b/issues
+Project-URL: Source, https://github.com/grasp-team/grasp-e2b
+Project-URL: Documentation, https://docs.grasp.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.8
+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: e2b>=1.5.0
+Requires-Dist: e2b-code-interpreter>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+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
+Dynamic: home-page
+Dynamic: requires-python
+
+# 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
+
+```python
+import asyncio
+from grasp_sdk import GraspServer
+
+async def main():
+    # Initialize Grasp server
+    server = GraspServer({
+        "key": api_key,
+        "timeout": 30000,
+    })
+    
+    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")
+        
+    finally:
+        # Clean up
+        await server.close()
+
+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
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black .
+isort .
+
+# Type checking
+mypy .
+
+# Linting
+flake8 .
+```
+
+## 📚 API Reference
+
+### 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
+```
+
+## 🤝 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.0/README.md

@@ -0,0 +1,154 @@
+# 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
+
+```python
+import asyncio
+from grasp_sdk import GraspServer
+
+async def main():
+    # Initialize Grasp server
+    server = GraspServer({
+        "key": api_key,
+        "timeout": 30000,
+    })
+    
+    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")
+        
+    finally:
+        # Clean up
+        await server.close()
+
+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
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black .
+isort .
+
+# Type checking
+mypy .
+
+# Linting
+flake8 .
+```
+
+## 📚 API Reference
+
+### 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
+```
+
+## 🤝 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.0/build_and_publish.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""
+Build and publish script for grasp_sdk package.
+
+Usage:
+    python build_and_publish.py --build-only    # Only build the package
+    python build_and_publish.py --test          # Upload to TestPyPI
+    python build_and_publish.py --prod          # Upload to PyPI
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run_command(cmd: str, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a shell command and return the result."""
+    print(f"Running: {cmd}")
+    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+    
+    if check and result.returncode != 0:
+        print(f"Error running command: {cmd}")
+        print(f"stdout: {result.stdout}")
+        print(f"stderr: {result.stderr}")
+        sys.exit(1)
+    
+    return result
+
+
+def clean_build_dirs():
+    """Clean previous build artifacts."""
+    print("Cleaning build directories...")
+    dirs_to_clean = ['build', 'dist', 'grasp_sdk.egg-info']
+    
+    for dir_name in dirs_to_clean:
+        if os.path.exists(dir_name):
+            run_command(f"rm -rf {dir_name}")
+
+
+def build_package():
+    """Build the package."""
+    print("Building package...")
+    
+    # Install build dependencies
+    run_command("pip install --upgrade build twine")
+    
+    # Build the package
+    run_command("python -m build")
+    
+    print("Package built successfully!")
+    print("Built files:")
+    if os.path.exists('dist'):
+        for file in os.listdir('dist'):
+            print(f"  - dist/{file}")
+
+
+def upload_to_testpypi():
+    """Upload package to TestPyPI."""
+    print("Uploading to TestPyPI...")
+    run_command("python -m twine upload --repository testpypi dist/*")
+    print("Package uploaded to TestPyPI successfully!")
+    print("Install with: pip install --index-url https://test.pypi.org/simple/ grasp_sdk")
+
+
+def upload_to_pypi():
+    """Upload package to PyPI."""
+    print("Uploading to PyPI...")
+    
+    # Confirm before uploading to production
+    response = input("Are you sure you want to upload to PyPI? (yes/no): ")
+    if response.lower() != 'yes':
+        print("Upload cancelled.")
+        return
+    
+    run_command("python -m twine upload dist/*")
+    print("Package uploaded to PyPI successfully!")
+    print("Install with: pip install grasp_sdk")
+
+
+def check_package():
+    """Run package checks."""
+    print("Running package checks...")
+    
+    # Check if required files exist
+    required_files = ['README.md', 'pyproject.toml', 'setup.py', '__init__.py']
+    for file in required_files:
+        if not os.path.exists(file):
+            print(f"Warning: {file} not found")
+    
+    # Check package with twine
+    if os.path.exists('dist'):
+        run_command("python -m twine check dist/*")
+    
+    print("Package checks completed.")
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Build and publish grasp_sdk package')
+    parser.add_argument('--build-only', action='store_true', help='Only build the package')
+    parser.add_argument('--test', action='store_true', help='Upload to TestPyPI')
+    parser.add_argument('--prod', action='store_true', help='Upload to PyPI')
+    parser.add_argument('--check', action='store_true', help='Run package checks only')
+    
+    args = parser.parse_args()
+    
+    # Change to script directory
+    script_dir = Path(__file__).parent
+    os.chdir(script_dir)
+    
+    if args.check:
+        check_package()
+        return
+    
+    # Clean and build
+    clean_build_dirs()
+    build_package()
+    check_package()
+    
+    if args.build_only:
+        print("Build completed. Use --test or --prod to upload.")
+    elif args.test:
+        upload_to_testpypi()
+    elif args.prod:
+        upload_to_pypi()
+    else:
+        print("Package built successfully!")
+        print("Next steps:")
+        print("  - Test upload: python build_and_publish.py --test")
+        print("  - Production upload: python build_and_publish.py --prod")
+
+
+if __name__ == '__main__':
+    main()

grasp_sdk-0.1.0/example_simple.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""
+Grasp SDK Python 简单示例
+
+这个示例展示了如何在没有 API key 的情况下测试 grasp_sdk 的基本功能。
+注意：这个示例主要用于测试包的导入和基本结构，实际的浏览器功能需要有效的 API key。
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+try:
+    from grasp_sdk import GraspServer, launch_browser
+    from grasp_sdk.models import IBrowserConfig, ISandboxConfig
+    print("✅ grasp_sdk 导入成功")
+except ImportError as e:
+    print(f"❌ 导入 grasp_sdk 失败: {e}")
+    exit(1)
+
+
+async def test_basic_functionality():
+    """测试基本功能（不需要实际启动浏览器）"""
+    
+    print("\n🧪 测试基本功能...")
+    
+    try:
+        # 测试 GraspServer 实例化
+        server = GraspServer()
+        print("✅ GraspServer 实例创建成功")
+        
+        # 测试获取状态
+        status = server.get_status()
+        print(f"✅ 服务器状态: {status}")
+        
+        # 测试获取沙箱 ID
+        sandbox_id = server.get_sandbox_id()
+        print(f"✅ 沙箱 ID: {sandbox_id}")
+        
+        print("\n✅ 基本功能测试通过")
+        
+    except Exception as e:
+        print(f"❌ 基本功能测试失败: {e}")
+        raise
+
+
+async def test_with_mock_config():
+    """使用模拟配置测试（不实际连接）"""
+    
+    print("\n🔧 测试配置功能...")
+    
+    try:
+        # 创建模拟的浏览器配置
+        browser_config: IBrowserConfig = {
+            'cdpPort': 9222,
+            'headless': True,
+            'launchTimeout': 30000,
+            'args': ['--disable-web-security'],
+            'envs': {'TEST': 'true'}
+        }
+        print("✅ 浏览器配置创建成功")
+        
+        # 创建模拟的沙箱配置
+        sandbox_config: ISandboxConfig = {
+            'key': 'mock_api_key',
+            'templateId': 'playwright-pnpm-template',
+            'timeout': 300000,
+            'debug': False
+        }
+        print("✅ 沙箱配置创建成功")
+        
+        print("\n✅ 配置功能测试通过")
+        
+    except Exception as e:
+        print(f"❌ 配置功能测试失败: {e}")
+        raise
+
+
+def test_imports():
+    """测试所有重要模块的导入"""
+    
+    print("\n📦 测试模块导入...")
+    
+    try:
+        # 测试服务模块
+        from grasp_sdk.services import BrowserService, SandboxService
+        print("✅ 服务模块导入成功")
+        
+        # 测试工具模块
+        from grasp_sdk.utils import get_config, get_logger
+        print("✅ 工具模块导入成功")
+        
+        # 测试模型模块
+        from grasp_sdk.models import SandboxStatus
+        print("✅ 模型模块导入成功")
+        
+        print("\n✅ 所有模块导入测试通过")
+        
+    except ImportError as e:
+        print(f"❌ 模块导入测试失败: {e}")
+        raise
+
+
+async def main():
+    """主函数：运行所有测试"""
+    
+    print("🎯 Grasp SDK Python 简单功能测试")
+    print("=" * 50)
+    
+    try:
+        # 1. 测试导入
+        test_imports()
+        
+        # 2. 测试基本功能
+        await test_basic_functionality()
+        
+        # 3. 测试配置
+        await test_with_mock_config()
+        
+        print("\n" + "=" * 50)
+        print("🎉 所有测试通过！")
+        print("\n💡 提示：")
+        print("   - 要运行完整的浏览器自动化示例，请使用 example_usage.py")
+        print("   - 确保设置了有效的 GRASP_KEY 环境变量")
+        print("   - 安装 Playwright：pip install playwright && playwright install")
+        
+    except Exception as e:
+        print(f"\n❌ 测试失败: {e}")
+        print("\n🔍 故障排除：")
+        print("   1. 确保 grasp-sdk 已正确安装")
+        print("   2. 检查 Python 版本（需要 3.8+）")
+        print("   3. 查看完整错误信息以获取更多详情")
+        raise
+
+
+if __name__ == '__main__':
+    # 运行测试
+    asyncio.run(main())