lambda-playwright 0.1.4
SDK for invoking Lambda Playwright service
Requires Python: >=3.8

# Lambda Playwright SDK

A Python SDK for interacting with the Lambda Playwright service.

## Installation

```bash
pip install lambda-playwright
```

## Usage

### Initialization

```python
from lambda_playwright import LambdaPlaywright

# Initialize with environment variables (AWS_PLAYWRIGHT_FUNCTION_URL, AWS_PLAYWRIGHT_ACCESS_KEY, AWS_PLAYWRIGHT_SECRET_ACCESS)
client = LambdaPlaywright()

# Or explicitly
client = LambdaPlaywright(
    function_url="https://your-function-url.lambda-url.ap-southeast-1.on.aws",
    access_key_id="your-access-key-id",
    secret_access_key="your-secret-access-key",
    region="ap-southeast-2"
)
```

### Visit a Page

```python
response = client.visit({
    "url": "https://example.com",
    "actions": [
        {"type": "wait_for_selector", "selector": "a"}
    ],
})

print(response["html"])
```

### Render HTML

```python
response = client.render_html({
    "html_content": "<h1>Hello World</h1><script>document.write('Loaded');</script>",
    "actions": [],
    "scroll_to_bottom": True
})

print(response["html"])
```

## Development

To run locally against a local Lambda container:

```python
client = LambdaPlaywright(debug=True)
```

## Available Actions

You can pass a list of actions to be executed on the page.

### `click`
Clicks on an element matching the selector.
```python
{"type": "click", "selector": "button#submit"}
```

### `wait_for_selector`
Waits for an element to appear in the DOM.
- `timeout` (optional): Maximum time to wait in milliseconds (default: 10000).
```python
{"type": "wait_for_selector", "selector": ".content", "timeout": 5000}
```

### `sleep`
Pauses execution for a specified duration.
```python
{"type": "sleep", "duration": 2.5}  # Sleep for 2.5 seconds
```

### `scroll_to_bottom`
Scrolls to the bottom of the page to load dynamic content.
```python
{"type": "scroll_to_bottom"}
```

### `fill`
Fills a form input field.
```python
{"type": "fill", "selector": "input[name='q']", "value": "search term"}
```

### `type`
Types text into an input field, with optional delay between key presses.
```python
{"type": "type", "selector": "#notes", "text": "Hello", "delay": 100}
```

### `evaluate`
Executes custom JavaScript in the browser context.
```python
{"type": "evaluate", "script": "document.body.style.backgroundColor = 'red'"}
```

## Payload Reference

### Visit Page Payload (`client.visit`)

| Field | Type | Description |
|-------|------|-------------|
| `url` | `str` | **Required**. The URL to visit. |
| `actions` | `List[Action]` | List of actions to perform. |
| `headers` | `dict` | Custom HTTP headers. |
| `cookies` | `dict` | Cookies to set. |
| `user_agent` | `str` | Custom User-Agent string. |
| `max_retries` | `int` | Number of retries on failure (default: 3). |
| `timeout_ms` | `int` | Global timeout in milliseconds (default: 60000). |
| `wait_for_network_idle` | `bool` | Wait for network to be idle (default: True). |
| `scroll_to_bottom` | `bool` | Automatically scroll to bottom (default: True). |

### Render HTML Payload (`client.render_html`)

| Field | Type | Description |
|-------|------|-------------|
| `html_content` | `str` | **Required**. The HTML content to render. |
| `actions` | `List[Action]` | List of actions to perform. |
| `max_retries` | `int` | Number of retries on failure (default: 3). |
| `timeout_ms` | `int` | Global timeout in milliseconds (default: 60000). |
| `wait_for_network_idle` | `bool` | Wait for network to be idle (default: True). |
| `scroll_to_bottom` | `bool` | Automatically scroll to bottom (default: False). |

## Publishing to PyPI

To publish a new version of the SDK to PyPI:

1.  **Update Version**: Increment the version number in `setup.py`.
    ```python
    setup(
        # ...
        version="0.1.x",
        # ...
    )
    ```

2.  **Clean Builds**: Remove previous build artifacts.
    ```bash
    rm -rf dist build *.egg-info
    ```

3.  **Build Package**: Create source and wheel distributions.
    ```bash
    python3 setup.py sdist bdist_wheel
    ```

4.  **Upload**: Upload the new version to PyPI using `twine`.
    ```bash
    twine upload dist/*
    ```