snaprender 0.2.3
Official Python SDK for SnapRender Screenshot API
License: MIT
Requires Python: >=3.8
Keywords: api, capture, screenshot, snaprender, webpage

# snaprender

[![PyPI version](https://img.shields.io/pypi/v/snaprender)](https://pypi.org/project/snaprender/)
[![PyPI downloads](https://img.shields.io/pypi/dm/snaprender)](https://pypi.org/project/snaprender/)
[![license](https://img.shields.io/pypi/l/snaprender)](https://github.com/User0856/snaprender/blob/main/LICENSE)

Official Python SDK for the [SnapRender](https://snap-render.com) Screenshot API — capture pixel-perfect screenshots of any webpage with a single API call.

**50 free screenshots/month — [Get your API key](https://app.snap-render.com/auth/signup?ref=pypi)**

## Features

- **Multiple output formats** — PNG, JPEG, WebP, and PDF
- **Device emulation** — iPhone, iPad, Pixel, and more presets
- **Dark mode** — Capture pages with `prefers-color-scheme: dark`
- **Ad blocking** — Remove ads automatically before capture
- **Cookie banner removal** — Clean screenshots without consent popups
- **Smart caching** — Configurable CDN cache with TTL control
- **Full-page captures** — Screenshot the entire scrollable page

## Install

```bash
pip install snaprender
```

## Quick Start

```python
from snaprender import SnapRender

snap = SnapRender(api_key="sk_live_...")

# Capture a screenshot
image = snap.capture("https://example.com")
with open("screenshot.png", "wb") as f:
    f.write(image)

# Capture with options
jpg = snap.capture(
    "https://example.com",
    format="jpeg",
    width=1920,
    height=1080,
    full_page=True,
    dark_mode=True,
    quality=95,
)

# Check cache status
info = snap.info("https://example.com")
print(info["cached"])      # True/False
print(info["expires_at"])  # ISO date string (when cached)

# Get usage
usage = snap.usage()
print(f"{usage['used']}/{usage['limit']} screenshots used")
```

## Context Manager

```python
with SnapRender(api_key="sk_live_...") as snap:
    image = snap.capture("https://example.com")
```

## API

### `SnapRender(api_key, base_url="https://app.snap-render.com", timeout=60.0)`

### `snap.capture(url, **options)` -> `bytes`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `url` | str | — | URL to capture (required) |
| `format` | str | `"png"` | `"png"`, `"jpeg"`, `"webp"`, or `"pdf"` |
| `width` | int | `1280` | Viewport width |
| `height` | int | `800` | Viewport height |
| `full_page` | bool | `False` | Capture full scrollable page |
| `quality` | int | `90` | JPEG/WebP quality (1-100) |
| `delay` | int | `0` | Wait ms after page load |
| `dark_mode` | bool | `False` | Emulate dark mode |
| `block_ads` | bool | `True` | Block ad networks |
| `block_cookie_banners` | bool | `True` | Remove cookie banners |
| `device` | str | — | Device preset (`"iphone_14"`, `"iphone_15_pro"`, `"pixel_7"`, `"ipad_pro"`, `"macbook_pro"`) |
| `hide_selectors` | str | — | Comma-separated CSS selectors to hide |
| `click_selector` | str | — | CSS selector to click before capture |
| `user_agent` | str | — | Custom user agent string |
| `cache` | bool | `True` | Use cache |
| `cache_ttl` | int | `86400` | Cache TTL in seconds |
| `response_type` | str | — | `"json"` returns metadata + base64 data URI |

### `snap.info(url)` -> `dict`

Check if a screenshot is cached without capturing. Returns `{ url, cached, cache_key, cached_at, expires_at, content_type }`.

### `snap.usage()` -> `dict`

Get current month's usage.

### `snap.usage_daily(days=30)` -> `dict`

Get daily usage breakdown (default 30 days).

## LangChain Integration

Use SnapRender as a [LangChain](https://python.langchain.com/) tool for AI agents:

```python
import os
from langchain_core.tools import tool
from snaprender import SnapRender

client = SnapRender(api_key=os.environ["SNAPRENDER_API_KEY"])

@tool
def take_screenshot(url: str, format: str = "png", dark_mode: bool = False) -> str:
    """Capture a screenshot of any website URL. Returns base64 data URI."""
    result = client.capture(
        url, format=format, dark_mode=dark_mode, response_type="json"
    )
    return result["image"]
```

Works with LangGraph, CrewAI, and any framework that supports LangChain tools.

## Error Handling

```python
from snaprender import SnapRender, SnapRenderError

snap = SnapRender(api_key="sk_live_...")

try:
    snap.capture("https://example.com")
except SnapRenderError as e:
    print(e.code)    # "QUOTA_EXCEEDED"
    print(e.status)  # 429
    print(e)         # "Monthly quota exceeded"
```

## Links

- [Documentation](https://app.snap-render.com/#docs)
- [Pricing](https://app.snap-render.com/pricing)
- [Dashboard](https://app.snap-render.com/dashboard)
- [Blog](https://app.snap-render.com/blog)
- [GitHub](https://github.com/User0856/snaprender)

## License

MIT