> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getgrasp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Official Python SDK for Grasp

## Installation

Install the SDK using pip:

```bash theme={null}
pip install grasp-sdk
```

## Quick Start

<CodeGroup>
  ```python Sync theme={null}
  from grasp import Grasp

  # Initialize the client
  grasp = Grasp()

  # Create a new container
  container = grasp.create()

  print(f"CDP Endpoint: {container.browser.ws_endpoint}")

  # Shut down the container
  container.shutdown()
  ```

  ```python Async theme={null}
  import asyncio
  from grasp import AsyncGrasp

  async def main():
      # Initialize the async client
      async with AsyncGrasp() as grasp:
          # Create a new container
          container = await grasp.create()

          print(f"CDP Endpoint: {container.browser.ws_endpoint}")

          # Shut down the container
          await container.shutdown()

  asyncio.run(main())
  ```
</CodeGroup>

## API Reference

### `Grasp(**options)`

Initializes the Grasp client.

<ParamField body="options" type="dict" optional>
  <Expandable title="Configuration options">
    <ParamField body="api_key" type="str" optional>
      API key for authentication. Falls back to `GRASP_API_KEY` environment variable.
    </ParamField>
  </Expandable>
</ParamField>

### `grasp.create(**options)`

Create a new container.

<ParamField body="options" type="dict" optional>
  <Expandable title="Container configuration options">
    <ParamField body="idle_timeout" type="int" optional>
      Idle timeout in milliseconds.
    </ParamField>

    <ParamField body="proxy" type="dict" optional>
      Proxy configuration.
    </ParamField>
  </Expandable>
</ParamField>

**Returns:** `GraspContainer`

**Example:**

```python theme={null}
# Create a container with a 30-second idle timeout
container = grasp.create(idle_timeout=30000)

# Create a container with a proxy
container = grasp.create(
    proxy={
        "enabled": True,
        "type": "residential",
        "country": "US"
    }
)
```

### `grasp.connect(container_id)`

Connect to an existing container. This will wake up the container if it's sleeping.

<ParamField body="container_id" type="str" required>
  The ID of the container to connect to.
</ParamField>

**Returns:** `GraspContainer`

**Example:**

```python theme={null}
# Connect to an existing container
container = grasp.connect("container-123")
```

### `GraspContainer`

The container object returned by `grasp.create()` and `grasp.connect()`.

**Properties:**

<ParamField body="id" type="str">
  Unique container identifier.
</ParamField>

<ParamField body="status" type="str">
  Container status.
</ParamField>

<ParamField body="created_at" type="str">
  ISO timestamp of creation.
</ParamField>

<ParamField body="browser" type="BrowserSession">
  Browser session details.
</ParamField>

**Methods:**

#### `container.shutdown()`

Stop and clean up the container.

**Returns:** None

**Example:**

```python theme={null}
container.shutdown()
```

### `BrowserSession`

Browser session details associated with a container.

**Properties:**

<ParamField body="ws_endpoint" type="str">
  Chrome DevTools Protocol WebSocket endpoint.
</ParamField>

<ParamField body="live_url" type="str">
  URL to view the live browser session.
</ParamField>

**Example:**

```python theme={null}
cdp_url = container.browser.ws_endpoint
print(f"Connect to: {cdp_url}")
```

## Environment Variables

* `GRASP_API_KEY` - Default API key (recommended).

## Error Handling

```python theme={null}
from grasp import Grasp, GraspError

try:
    grasp = Grasp()
    container = grasp.create()
    # Use container
    container.shutdown()
except GraspError as error:
    print(f"An API error occurred: {error}")
```

## Type Hints

The SDK includes full type hints for better IDE support.

```python theme={null}
from grasp import Grasp, GraspContainer
from typing import Optional

def create_browser_session(api_key: Optional[str] = None) -> GraspContainer:
    grasp = Grasp(api_key=api_key)
    container = grasp.create()
    return container
```

## Using with Playwright

```python theme={null}
from grasp import Grasp
from playwright.sync_api import sync_playwright

# Initialize the Grasp client
grasp = Grasp()

# Create a new container
container = grasp.create()

# Connect Playwright to the cloud browser
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(container.browser.ws_endpoint)
    page = browser.new_page()
    page.goto("https://example.com")

    # Perform automation
    print(page.title())

    browser.close()

# Clean up
container.shutdown()
```

## Async Support

```python theme={null}
import asyncio
from grasp import AsyncGrasp
from playwright.async_api import async_playwright

async def main():
    # Initialize the async client
    async with AsyncGrasp() as grasp:
        # Create a new container
        container = await grasp.create()

        # Connect Playwright
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(container.browser.ws_endpoint)
            page = await browser.new_page()
            await page.goto("https://example.com")

            print(await page.title())

            await browser.close()

        # Clean up
        await container.shutdown()

asyncio.run(main())
```