Metadata-Version: 2.4
Name: shotapi
Version: 1.0.0
Summary: Python SDK for ShotAPI - Screenshot & Rendering API
Home-page: https://shotapi.net
Author: ShotAPI
Author-email: ShotAPI <support@shotapi.net>
License: MIT
Project-URL: Homepage, https://shotapi.net
Project-URL: Documentation, https://shotapi.net/docs-page
Project-URL: Repository, https://github.com/shotapi/shotapi-python
Project-URL: Issues, https://github.com/shotapi/shotapi-python/issues
Keywords: screenshot,api,web,capture,render,html,image,pdf
Classifier: Development Status :: 5 - Production/Stable
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ShotAPI Python SDK

Official Python SDK for [ShotAPI](https://shotapi.net) - The Screenshot & Rendering API.

## Installation

```bash
pip install shotapi
```

## Quick Start

```python
from shotapi import ShotAPI

# Initialize the client
client = ShotAPI("sk_your_api_key")

# Take a screenshot
image = client.screenshot("https://example.com")
with open("screenshot.png", "wb") as f:
    f.write(image)
```

## Features

- **URL Screenshots** - Capture any webpage as PNG, JPEG, WebP, or PDF
- **HTML Rendering** - Convert HTML/CSS to images
- **Metadata Extraction** - Get OG tags, title, description, tech stack
- **Batch Processing** - Screenshot multiple URLs in parallel
- **Visual Diff** - Compare two pages and get difference percentage

## Usage Examples

### Basic Screenshot

```python
from shotapi import ShotAPI

client = ShotAPI("sk_your_api_key")

# Simple screenshot
image = client.screenshot("https://stripe.com")

# Full-page screenshot
image = client.screenshot(
    "https://github.com",
    full_page=True,
    format="png"
)

# With options
image = client.screenshot(
    "https://example.com",
    width=1920,
    height=1080,
    dark_mode=True,
    device_scale_factor=2,
    block_ads=True,
)
```

### Device Mockups

```python
# Wrap in iPhone frame
image = client.screenshot(
    "https://example.com",
    mockup="iphone"
)

# MacBook mockup
image = client.screenshot(
    "https://example.com",
    mockup="macbook"
)
```

### HTML to Image

```python
# Render HTML to image
html = """
<div style="padding: 40px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
    <h1 style="color: white; font-family: sans-serif;">Hello World!</h1>
</div>
"""

image = client.render(html, width=800, height=400)
```

### Metadata Extraction

```python
# Get page metadata
meta = client.metadata("https://github.com")
print(meta["title"])
print(meta["description"])
print(meta["og_image"])

# With markdown content
meta = client.metadata("https://example.com", extract_markdown=True)
print(meta["markdown"])
```

### Batch Screenshots

```python
# Capture multiple URLs
urls = [
    "https://google.com",
    "https://github.com",
    "https://stripe.com",
]

result = client.batch(urls, format="png", full_page=True)
for item in result["results"]:
    print(f"{item['url']} -> {item['filename']}")
```

### Visual Diff

```python
# Compare two pages
diff_image, diff_percentage = client.diff(
    "https://example.com",
    "https://example.org"
)

print(f"Pages differ by {diff_percentage}%")
with open("diff.png", "wb") as f:
    f.write(diff_image)
```

### Advanced Options

```python
# Full control over the capture
image = client.screenshot(
    "https://example.com",
    width=1280,
    height=720,
    full_page=True,
    format="png",
    delay=2,  # Wait 2 seconds before capture
    dark_mode=True,
    device_scale_factor=2,
    custom_css="body { font-family: 'Comic Sans MS' !important; }",
    custom_js="document.querySelector('.popup').remove()",
    wait_for_selector=".content-loaded",
    click_selector=".accept-cookies",
    hide_selectors=[".ad-banner", ".newsletter-popup"],
    block_ads=True,
    headers={"Authorization": "Bearer token"},
    cookies=[{"name": "session", "value": "abc123", "domain": "example.com"}],
    geolocation={"latitude": 40.7128, "longitude": -74.0060},
    timezone="America/New_York",
)
```

## Error Handling

```python
from shotapi import ShotAPI, ShotAPIError, AuthenticationError, RateLimitError

client = ShotAPI("sk_your_api_key")

try:
    image = client.screenshot("https://example.com")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ShotAPIError as e:
    print(f"API error: {e.message}")
```

## Context Manager

```python
# Automatically close connection
with ShotAPI("sk_your_api_key") as client:
    image = client.screenshot("https://example.com")
```

## Configuration

```python
# Custom base URL and timeout
client = ShotAPI(
    api_key="sk_your_api_key",
    base_url="https://shotapi.net",  # default
    timeout=120.0,  # seconds
)
```

## Pro/Max Features

Some features require a Pro or Max plan:

| Feature | Free | Pro | Max |
|---------|------|-----|-----|
| Basic screenshots | Yes | Yes | Yes |
| Full-page capture | Yes | Yes | Yes |
| Dark mode | No | Yes | Yes |
| Device mockups | No | Yes | Yes |
| Custom CSS/JS | No | Yes | Yes |
| Element selection | No | Yes | Yes |
| Geo/Timezone emulation | No | Yes | Yes |
| Block ads | No | Yes | Yes |
| Batch processing | No | Yes | Yes |
| Markdown extraction | No | Yes | Yes |

## Links

- [Documentation](https://shotapi.net/docs-page)
- [Pricing](https://shotapi.net/pricing)
- [Dashboard](https://shotapi.net/dashboard)

## License

MIT License - see LICENSE file for details.
