e6c34ef760
Some checks failed
Build & Deploy to Staging / Build & Deploy to Staging (push) Has been cancelled
- Add 5 new Python tests for darkMode and hideSelectors parameters - Update Node.js SDK README with darkMode/hideSelectors examples - Update Python SDK README with darkMode/hideSelectors examples - Add API reference entries for new parameters - All tests passing: Node.js (19 tests), Python (22 tests) Features already implemented in v0.7.0 but needed better test coverage and documentation.
168 lines
3.4 KiB
Markdown
168 lines
3.4 KiB
Markdown
# SnapAPI Python SDK
|
||
|
||
Official Python client for [SnapAPI](https://snapapi.eu) — the EU-hosted screenshot API.
|
||
|
||
**Zero dependencies.** Uses only Python standard library (`urllib`).
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
pip install snapapi
|
||
```
|
||
|
||
## Quick Start
|
||
|
||
```python
|
||
from snapapi import SnapAPI
|
||
|
||
snap = SnapAPI("your-api-key")
|
||
|
||
# Capture a screenshot
|
||
screenshot = snap.capture("https://example.com")
|
||
|
||
with open("screenshot.png", "wb") as f:
|
||
f.write(screenshot)
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Basic Screenshot
|
||
|
||
```python
|
||
png = snap.capture("https://example.com")
|
||
```
|
||
|
||
### With Options
|
||
|
||
```python
|
||
jpg = snap.capture(
|
||
"https://example.com",
|
||
format="jpeg",
|
||
width=1920,
|
||
height=1080,
|
||
quality=90,
|
||
)
|
||
```
|
||
|
||
### Full-Page Capture
|
||
|
||
```python
|
||
full = snap.capture(
|
||
"https://example.com/blog",
|
||
full_page=True,
|
||
device_scale=2, # Retina
|
||
)
|
||
```
|
||
|
||
### Mobile Viewport
|
||
|
||
```python
|
||
mobile = snap.capture(
|
||
"https://example.com",
|
||
width=375,
|
||
height=812,
|
||
device_scale=2,
|
||
)
|
||
```
|
||
|
||
### Wait for Dynamic Content
|
||
|
||
```python
|
||
screenshot = snap.capture(
|
||
"https://example.com/dashboard",
|
||
wait_for_selector="#chart-loaded",
|
||
wait_until="networkidle2",
|
||
)
|
||
```
|
||
|
||
### Dark Mode Capture
|
||
|
||
```python
|
||
# Capture in dark mode (prefers-color-scheme: dark)
|
||
dark_screenshot = snap.capture(
|
||
"https://example.com",
|
||
dark_mode=True,
|
||
format="png",
|
||
)
|
||
```
|
||
|
||
### Hide Elements Before Capture
|
||
|
||
```python
|
||
# Hide cookie banners, popups, ads
|
||
clean_screenshot = snap.capture(
|
||
"https://example.com",
|
||
hide_selectors=[
|
||
".cookie-banner",
|
||
".popup-overlay",
|
||
"#advertisement",
|
||
".tracking-notice"
|
||
],
|
||
)
|
||
|
||
# Hide single element
|
||
single_hide = snap.capture(
|
||
"https://example.com",
|
||
hide_selectors=".newsletter-popup",
|
||
)
|
||
```
|
||
|
||
### Combined Dark Mode + Element Hiding
|
||
|
||
```python
|
||
# Perfect for clean marketing screenshots
|
||
marketing_shot = snap.capture(
|
||
"https://your-saas-app.com",
|
||
dark_mode=True,
|
||
hide_selectors=[".dev-banner", ".beta-notice"],
|
||
width=1920,
|
||
height=1080,
|
||
device_scale=2,
|
||
)
|
||
```
|
||
|
||
### Error Handling
|
||
|
||
```python
|
||
from snapapi import SnapAPI, SnapAPIError
|
||
|
||
snap = SnapAPI("your-api-key")
|
||
|
||
try:
|
||
screenshot = snap.capture("https://example.com")
|
||
except SnapAPIError as e:
|
||
print(f"API error {e.status}: {e.detail}")
|
||
```
|
||
|
||
## API Reference
|
||
|
||
### `SnapAPI(api_key, base_url="https://snapapi.eu", timeout=30)`
|
||
|
||
### `snap.capture(url, **options) -> bytes`
|
||
|
||
| Option | Type | Default | Description |
|
||
|--------|------|---------|-------------|
|
||
| `url` | `str` | — | URL to capture (required) |
|
||
| `format` | `str` | `"png"` | Output: `png`, `jpeg`, `webp` |
|
||
| `width` | `int` | `1280` | Viewport width (320–3840) |
|
||
| `height` | `int` | `800` | Viewport height (200–2160) |
|
||
| `full_page` | `bool` | `False` | Capture full page |
|
||
| `quality` | `int` | `80` | JPEG/WebP quality (1–100) |
|
||
| `wait_for_selector` | `str` | — | CSS selector to wait for |
|
||
| `device_scale` | `float` | `1` | Device pixel ratio (1–3) |
|
||
| `delay` | `int` | `0` | Extra delay in ms (0–5000) |
|
||
| `wait_until` | `str` | `"domcontentloaded"` | Load event |
|
||
| `dark_mode` | `bool` | `False` | Emulate prefers-color-scheme: dark |
|
||
| `hide_selectors` | `list` | — | CSS selectors to hide before capture |
|
||
|
||
### `snap.health() -> dict`
|
||
|
||
Returns API health status.
|
||
|
||
## EU-Hosted & GDPR Compliant
|
||
|
||
SnapAPI runs entirely on EU infrastructure (Germany). Your data never leaves the EU.
|
||
|
||
## License
|
||
|
||
MIT — [Cloonar Technologies GmbH](https://snapapi.eu)
|