grasp-sdk 0.1.4__tar.gz → 0.2.0__tar.gz

grasp_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: grasp-sdk
+Version: 0.2.0
+Summary: Official Python SDK for the Grasp browser automation platform
+Author-email: Grasp Team <dev@getgrasp.ai>
+License: MIT
+Project-URL: Homepage, https://getgrasp.ai
+Project-URL: Documentation, https://docs.getgrasp.ai
+Project-URL: Repository, https://github.com/getgrasp-ai/grasp
+Project-URL: Issues, https://github.com/getgrasp-ai/grasp/issues
+Keywords: browser,automation,chrome,devtools,cdp,playwright,puppeteer
+Classifier: Development Status :: 3 - Alpha
+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: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-core>=2.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: typing-extensions>=4.0; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
+Requires-Dist: pytest-httpx>=0.22; extra == "dev"
+Requires-Dist: pytest-sugar>=0.9.7; extra == "dev"
+Requires-Dist: pytest-watch>=4.2.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0; extra == "dev"
+Requires-Dist: rich>=13.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: playwright>=1.40; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+
+# Grasp Python SDK
+
+Official Python SDK for the Grasp browser automation platform.
+
+## Features
+
+- **Dual Client Architecture**: Both synchronous and asynchronous clients
+- **Type Safety**: Full type hints and Pydantic models for validation
+- **Browser Automation**: Seamless integration with Playwright and Puppeteer
+- **Proxy Support**: Built-in proxy configuration for different use cases
+- **Error Handling**: Comprehensive exception hierarchy
+- **Auto-retry**: Automatic retry with exponential backoff
+
+## Installation
+
+```bash
+pip install grasp-sdk
+```
+
+## Quick Start
+
+### Synchronous Usage
+
+```python
+from grasp import Grasp
+
+# Initialize client
+client = Grasp(api_key="your-api-key")  # or set GRASP_API_KEY env var
+
+# Create a container
+container = client.create(
+    idle_timeout=30000,  # 30 seconds
+    proxy={
+        "enabled": True,
+        "type": "residential",
+        "country": "US"
+    }
+)
+
+# Access browser information
+print(f"Container ID: {container.id}")
+print(f"CDP WebSocket: {container.browser.ws_endpoint}")
+print(f"Live View: {container.browser.live_url}")
+
+# Shutdown when done
+container.shutdown()
+```
+
+### Asynchronous Usage
+
+```python
+import asyncio
+from grasp import AsyncGrasp
+
+async def main():
+    # Use context manager for automatic cleanup
+    async with AsyncGrasp(api_key="your-api-key") as client:
+        # Create container
+        container = await client.create(idle_timeout=30000)
+
+        # Use the container
+        print(f"Container ID: {container.id}")
+
+        # Shutdown
+        await container.shutdown()
+
+asyncio.run(main())
+```
+
+### Playwright Integration
+
+```python
+from grasp import Grasp
+from playwright.sync_api import sync_playwright
+
+# Create Grasp container
+grasp = Grasp()
+container = grasp.create()
+
+# Connect Playwright
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(container.browser.ws_endpoint)
+    page = browser.new_page()
+    page.goto("https://example.com")
+
+    # Your automation code here
+    title = page.title()
+    print(f"Page title: {title}")
+
+    browser.close()
+
+# Cleanup
+container.shutdown()
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GRASP_API_KEY`: Your API key (alternative to passing in code)
+- `GRASP_BASE_URL`: API base URL (defaults to `https://api.getgrasp.ai`)
+
+### Client Options
+
+```python
+client = Grasp(
+    api_key="your-api-key",
+    base_url="https://api.getgrasp.ai",  # optional
+    timeout=60.0,  # request timeout in seconds
+    max_retries=2  # maximum retry attempts
+)
+```
+
+### Container Options
+
+```python
+container = client.create(
+    idle_timeout=30000,  # milliseconds before container sleeps
+    proxy={
+        "enabled": True,
+        "type": "residential",  # mobile, residential, isp, datacenter, custom
+        "country": "US",  # optional: country code
+        "state": "CA",    # optional: state code
+        "city": "LA"      # optional: city name
+    }
+)
+```
+
+## API Reference
+
+### Main Classes
+
+#### `Grasp` / `AsyncGrasp`
+Main client classes for interacting with the API.
+
+**Methods:**
+- `create(**options)`: Create a new container
+- `connect(container_id)`: Connect to existing container
+
+#### `GraspContainer` / `AsyncGraspContainer`
+Represents a browser automation container.
+
+**Properties:**
+- `id`: Container identifier
+- `status`: Current status (running, stopped, sleeping)
+- `created_at`: Creation timestamp
+- `browser`: Browser session information
+
+**Methods:**
+- `shutdown()`: Shut down the container
+
+#### `BrowserSession`
+Browser session information.
+
+**Properties:**
+- `ws_endpoint`: Chrome DevTools Protocol WebSocket endpoint
+- `live_url`: Live view URL for observing the browser
+
+### Exception Handling
+
+```python
+from grasp import (
+    GraspError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError
+)
+
+try:
+    container = client.create()
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after}")
+except GraspError as e:
+    print(f"API error: {e}")
+```
+
+### Exception Hierarchy
+
+- `GraspError`: Base exception
+  - `APIError`: API-related errors
+    - `APIStatusError`: HTTP status errors
+      - `AuthenticationError`: 401 Unauthorized
+      - `NotFoundError`: 404 Not Found
+      - `RateLimitError`: 429 Rate Limited
+      - `InternalServerError`: 500 Server Error
+  - `APIConnectionError`: Network issues
+    - `APITimeoutError`: Request timeout
+
+## Examples
+
+See the [examples](examples/) directory for more detailed examples:
+
+- [basic_usage.py](examples/basic_usage.py): Simple synchronous usage
+- [async_usage.py](examples/async_usage.py): Async with multiple containers
+- [playwright_integration.py](examples/playwright_integration.py): Full Playwright integration
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/getgrasp-ai/grasp.git
+cd grasp/packages/python-sdk
+
+# Install dependencies
+pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=grasp
+
+# Run specific test file
+pytest tests/test_client.py
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/
+```
+
+## Requirements
+
+- Python 3.8+
+- httpx >= 0.24.0
+- pydantic >= 2.0
+
+## License
+
+MIT

grasp_sdk-0.2.0/README.md

@@ -0,0 +1,246 @@
+# Grasp Python SDK
+
+Official Python SDK for the Grasp browser automation platform.
+
+## Features
+
+- **Dual Client Architecture**: Both synchronous and asynchronous clients
+- **Type Safety**: Full type hints and Pydantic models for validation
+- **Browser Automation**: Seamless integration with Playwright and Puppeteer
+- **Proxy Support**: Built-in proxy configuration for different use cases
+- **Error Handling**: Comprehensive exception hierarchy
+- **Auto-retry**: Automatic retry with exponential backoff
+
+## Installation
+
+```bash
+pip install grasp-sdk
+```
+
+## Quick Start
+
+### Synchronous Usage
+
+```python
+from grasp import Grasp
+
+# Initialize client
+client = Grasp(api_key="your-api-key")  # or set GRASP_API_KEY env var
+
+# Create a container
+container = client.create(
+    idle_timeout=30000,  # 30 seconds
+    proxy={
+        "enabled": True,
+        "type": "residential",
+        "country": "US"
+    }
+)
+
+# Access browser information
+print(f"Container ID: {container.id}")
+print(f"CDP WebSocket: {container.browser.ws_endpoint}")
+print(f"Live View: {container.browser.live_url}")
+
+# Shutdown when done
+container.shutdown()
+```
+
+### Asynchronous Usage
+
+```python
+import asyncio
+from grasp import AsyncGrasp
+
+async def main():
+    # Use context manager for automatic cleanup
+    async with AsyncGrasp(api_key="your-api-key") as client:
+        # Create container
+        container = await client.create(idle_timeout=30000)
+
+        # Use the container
+        print(f"Container ID: {container.id}")
+
+        # Shutdown
+        await container.shutdown()
+
+asyncio.run(main())
+```
+
+### Playwright Integration
+
+```python
+from grasp import Grasp
+from playwright.sync_api import sync_playwright
+
+# Create Grasp container
+grasp = Grasp()
+container = grasp.create()
+
+# Connect Playwright
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(container.browser.ws_endpoint)
+    page = browser.new_page()
+    page.goto("https://example.com")
+
+    # Your automation code here
+    title = page.title()
+    print(f"Page title: {title}")
+
+    browser.close()
+
+# Cleanup
+container.shutdown()
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GRASP_API_KEY`: Your API key (alternative to passing in code)
+- `GRASP_BASE_URL`: API base URL (defaults to `https://api.getgrasp.ai`)
+
+### Client Options
+
+```python
+client = Grasp(
+    api_key="your-api-key",
+    base_url="https://api.getgrasp.ai",  # optional
+    timeout=60.0,  # request timeout in seconds
+    max_retries=2  # maximum retry attempts
+)
+```
+
+### Container Options
+
+```python
+container = client.create(
+    idle_timeout=30000,  # milliseconds before container sleeps
+    proxy={
+        "enabled": True,
+        "type": "residential",  # mobile, residential, isp, datacenter, custom
+        "country": "US",  # optional: country code
+        "state": "CA",    # optional: state code
+        "city": "LA"      # optional: city name
+    }
+)
+```
+
+## API Reference
+
+### Main Classes
+
+#### `Grasp` / `AsyncGrasp`
+Main client classes for interacting with the API.
+
+**Methods:**
+- `create(**options)`: Create a new container
+- `connect(container_id)`: Connect to existing container
+
+#### `GraspContainer` / `AsyncGraspContainer`
+Represents a browser automation container.
+
+**Properties:**
+- `id`: Container identifier
+- `status`: Current status (running, stopped, sleeping)
+- `created_at`: Creation timestamp
+- `browser`: Browser session information
+
+**Methods:**
+- `shutdown()`: Shut down the container
+
+#### `BrowserSession`
+Browser session information.
+
+**Properties:**
+- `ws_endpoint`: Chrome DevTools Protocol WebSocket endpoint
+- `live_url`: Live view URL for observing the browser
+
+### Exception Handling
+
+```python
+from grasp import (
+    GraspError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError
+)
+
+try:
+    container = client.create()
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after}")
+except GraspError as e:
+    print(f"API error: {e}")
+```
+
+### Exception Hierarchy
+
+- `GraspError`: Base exception
+  - `APIError`: API-related errors
+    - `APIStatusError`: HTTP status errors
+      - `AuthenticationError`: 401 Unauthorized
+      - `NotFoundError`: 404 Not Found
+      - `RateLimitError`: 429 Rate Limited
+      - `InternalServerError`: 500 Server Error
+  - `APIConnectionError`: Network issues
+    - `APITimeoutError`: Request timeout
+
+## Examples
+
+See the [examples](examples/) directory for more detailed examples:
+
+- [basic_usage.py](examples/basic_usage.py): Simple synchronous usage
+- [async_usage.py](examples/async_usage.py): Async with multiple containers
+- [playwright_integration.py](examples/playwright_integration.py): Full Playwright integration
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/getgrasp-ai/grasp.git
+cd grasp/packages/python-sdk
+
+# Install dependencies
+pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=grasp
+
+# Run specific test file
+pytest tests/test_client.py
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/
+```
+
+## Requirements
+
+- Python 3.8+
+- httpx >= 0.24.0
+- pydantic >= 2.0
+
+## License
+
+MIT

grasp_sdk-0.2.0/RELEASE.md

@@ -0,0 +1,109 @@
+# Release Guide for Grasp Python SDK
+
+## Pre-release Checklist
+
+- [ ] All tests pass locally
+- [ ] Version number updated in `pyproject.toml`
+- [ ] README.md is up to date
+- [ ] CHANGELOG updated (if exists)
+- [ ] Examples work correctly
+
+## Current Release Info
+
+- **Package Name**: grasp-sdk (on PyPI)
+- **Import Name**: grasp (in Python code)
+- **Previous Version**: 0.1.11 (from previous maintainer)
+- **New Version**: 0.2.0 (complete rewrite)
+
+## Publishing Steps
+
+### 1. Clean previous builds
+```bash
+rm -rf dist/ build/ *.egg-info/
+```
+
+### 2. Install build tools
+```bash
+pip install --upgrade build twine
+```
+
+### 3. Build the package
+```bash
+python -m build
+```
+
+### 4. Check the distribution
+```bash
+# Check if package is correctly structured
+twine check dist/*
+
+# Test installation locally
+pip install dist/grasp_sdk-0.2.0-py3-none-any.whl
+
+# Verify it works
+python -c "from grasp import Grasp; print('Import successful!')"
+```
+
+### 5. Upload to Test PyPI (optional but recommended)
+```bash
+# Upload to test.pypi.org first
+twine upload --repository testpypi dist/*
+
+# Test install from Test PyPI
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ grasp-sdk==0.2.0
+```
+
+### 6. Upload to PyPI
+```bash
+# You'll need PyPI credentials or token
+twine upload dist/*
+```
+
+## Authentication
+
+You'll need PyPI credentials. There are two options:
+
+### Option 1: Using Token (Recommended)
+1. Go to https://pypi.org/manage/account/token/
+2. Create a token for `grasp-sdk` project
+3. Use `__token__` as username and the token as password
+
+### Option 2: Using .pypirc file
+Create `~/.pypirc`:
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-YOUR-TOKEN-HERE
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-YOUR-TEST-TOKEN-HERE
+```
+
+## Post-release
+
+After successful release:
+1. Create a git tag: `git tag v0.2.0`
+2. Push tag: `git push origin v0.2.0`
+3. Create GitHub release with changelog
+4. Update documentation if needed
+
+## Breaking Changes from 0.1.11
+
+Since this is a complete rewrite, users upgrading from 0.1.11 should be aware:
+- Completely new API design
+- Both sync and async clients available
+- Different import structure
+- New error handling system
+- Better container lifecycle management
+
+## Version History
+
+- **0.1.11** - Last version from previous maintainer
+- **0.2.0** - Complete rewrite with new architecture

grasp_sdk-0.2.0/TESTING.md

@@ -0,0 +1,55 @@
+# Testing the Grasp Python SDK
+
+## Prerequisites
+
+1. **API Server Running**: Ensure the Grasp API server is running locally on `http://localhost:3000`
+   ```bash
+   # From the root directory
+   pnpm --filter api-server dev
+   ```
+
+2. **Python Environment**: Python 3.8+ installed
+
+## Running Tests
+
+```bash
+cd packages/python-sdk
+./run_tests.sh
+```
+
+The test script will automatically:
+- Set environment variables (`GRASP_API_KEY="api-server-test"`, `GRASP_BASE_URL="http://localhost:3000"`)
+- Install the SDK in development mode
+- Install test dependencies (pytest, pytest-asyncio)
+- Install Playwright for browser automation tests
+- Run all tests including Playwright integration tests
+- Show clear pass/fail status with troubleshooting tips
+
+## Test Structure
+
+- `tests/test_client.py` - Tests for synchronous client
+- `tests/test_async_client.py` - Tests for asynchronous client
+
+Each test file covers:
+- Client initialization
+- Container creation and management
+- Browser endpoint validation
+- Error handling
+- Serialization
+- **Playwright Integration** (optional):
+  - Browser connection via CDP
+  - Page navigation and content scraping
+
+## Troubleshooting
+
+### Connection Errors
+If you see connection errors, ensure:
+1. API server is running on port 3000
+2. Environment variables are set correctly
+3. No firewall blocking localhost connections
+
+### API Key Errors
+The test API key `api-server-test` is hardcoded for local testing. Make sure the API server recognizes this key.
+
+### Cleanup
+Tests automatically clean up containers after completion. If tests fail, some containers might remain active. Check the API server logs for orphaned containers.