Metadata-Version: 2.4
Name: screenshot-pdf-api
Version: 1.1.0
Summary: Python wrapper for the Screenshot & PDF API — capture screenshots, generate PDFs, extract metadata, and render HTML to images.
Author-email: Screenshot PDF API <contact@screenshot-pdf-api.com>
License-Expression: MIT
Project-URL: Homepage, https://rapidapi.com/screenshot-pdf-api
Project-URL: Documentation, https://github.com/screenshot-pdf-api/screenshot-pdf-api-python
Project-URL: Repository, https://github.com/screenshot-pdf-api/screenshot-pdf-api-python
Project-URL: Issues, https://github.com/screenshot-pdf-api/screenshot-pdf-api-python/issues
Keywords: screenshot,pdf,webpage capture,html to image,metadata,open graph,web scraping,headless browser,api wrapper
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics :: Capture
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Screenshot & PDF API

Python wrapper for the **Screenshot & PDF API** on RapidAPI.

Capture screenshots, generate PDFs, extract page metadata, and render HTML/CSS to images — all from a single, zero-dependency package.

[![PyPI version](https://img.shields.io/pypi/v/screenshot-pdf-api.svg)](https://pypi.org/project/screenshot-pdf-api/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://pypi.org/project/screenshot-pdf-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install screenshot-pdf-api
```

## Quick Start

```python
from screenshot_pdf_api import ScreenshotAPI

api = ScreenshotAPI("your-rapidapi-key")

# Check API status
print(api.health())

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

## Get Your API Key

1. Go to [RapidAPI - Screenshot & PDF API](https://rapidapi.com/screenshot-pdf-api)
2. Subscribe to a plan (free tier available)
3. Copy your `X-RapidAPI-Key` from the dashboard

## Endpoints

### Free Tier

```python
api = ScreenshotAPI("your-key")

# Screenshot any URL → PNG, JPEG, or WebP
png = api.screenshot("https://example.com")

# Full-page screenshot with custom viewport
img = api.screenshot(
    "https://example.com",
    width=1920,
    height=1080,
    full_page=True,
    format="jpeg",
    quality=90,
)

# Screenshot a specific element
element = api.screenshot(
    "https://example.com",
    selector="#main-content",
)

# Wait for dynamic content before capture
img = api.screenshot(
    "https://example.com",
    delay=2000,  # wait 2 seconds
)
```

### Basic Tier

```python
# Generate a PDF from any URL
pdf = api.pdf("https://example.com")
with open("page.pdf", "wb") as f:
    f.write(pdf)

# PDF with custom options
pdf = api.pdf(
    "https://example.com",
    format="Letter",
    landscape=True,
    print_background=True,
    margin="narrow",
)

# Extract page metadata (title, OG tags, favicon, etc.)
meta = api.metadata("https://example.com")
print(meta["title"])
print(meta["og"])
print(meta["favicon"])
```

### Pro Tier

```python
# Render HTML/CSS to image
html = """
<html>
<body style="background: linear-gradient(135deg, #667eea, #764ba2);
             color: white; font-family: Arial; padding: 40px;">
  <h1>Hello World</h1>
  <p>Rendered from raw HTML</p>
</body>
</html>
"""
img = api.screenshot_html(html, width=800, height=600)
with open("rendered.png", "wb") as f:
    f.write(img)
```

## Error Handling

The library raises specific exceptions for different error types:

```python
from screenshot_pdf_api import (
    ScreenshotAPI,
    ScreenshotAuthError,
    ScreenshotForbiddenError,
    ScreenshotRateLimitError,
    ScreenshotAPIError,
)

api = ScreenshotAPI("your-key")

try:
    img = api.screenshot_html("<h1>Pro feature</h1>")
except ScreenshotAuthError:
    print("Invalid API key")
except ScreenshotForbiddenError:
    print("Upgrade your plan for this endpoint")
except ScreenshotRateLimitError:
    print("Rate limited — slow down or upgrade")
except ScreenshotAPIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

| Exception | HTTP Code | Meaning |
|-----------|-----------|---------|
| `ScreenshotAuthError` | 401 | Invalid or missing API key |
| `ScreenshotForbiddenError` | 403 | Endpoint not in your tier |
| `ScreenshotNotFoundError` | 404 | Resource not found |
| `ScreenshotRateLimitError` | 429 | Rate limit exceeded |
| `ScreenshotServerError` | 5xx | Server-side error |
| `ScreenshotAPIError` | any | Base class for all errors |

## Configuration

```python
api = ScreenshotAPI(
    api_key="your-key",
    timeout=60,       # request timeout in seconds (default: 30)
)
```

## Requirements

- Python 3.8+
- **Zero dependencies** — uses only `urllib.request` from the standard library

## License

MIT
