screenshotapi-to 1.0.0__tar.gz

screenshotapi_to-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/

screenshotapi_to-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScreenshotAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

screenshotapi_to-1.0.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: screenshotapi-to
+Version: 1.0.0
+Summary: Official Python SDK for ScreenshotAPI.
+Project-URL: Homepage, https://screenshotapi.to
+Project-URL: Documentation, https://screenshotapi.to/docs
+Project-URL: Pricing, https://screenshotapi.to/pricing
+Project-URL: Repository, https://github.com/miketromba/screenshotapi-python
+Project-URL: Issues, https://github.com/miketromba/screenshotapi-python/issues
+Project-URL: Support, https://screenshotapi.to
+Author-email: ScreenshotAPI <support@screenshotapi.to>
+Maintainer-email: ScreenshotAPI <support@screenshotapi.to>
+License: MIT License
+        
+        Copyright (c) 2026 ScreenshotAPI
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,capture,html-to-image,screenshot,screenshotapi,webpage,website-thumbnail
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+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 :: Only
+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 :: Screen Capture
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx<1.0,>=0.24.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy<1.15,>=1.8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# screenshotapi
+
+Official typed Python SDK for
+[ScreenshotAPI](https://screenshotapi.to?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk),
+the hosted screenshot API for turning URLs or HTML into PNG, JPEG, WebP, or PDF
+captures.
+
+## Install
+
+```bash
+pip install screenshotapi-to
+```
+
+Python 3.8+ is supported. The distribution package is `screenshotapi-to`, the
+import package is `screenshotapi`, and the package ships `py.typed` metadata for
+type checkers.
+
+## Authentication
+
+Create an API key in the ScreenshotAPI dashboard, then keep it in an environment
+variable:
+
+```bash
+export SCREENSHOTAPI_KEY="sk_live_your_key_here"
+```
+
+The SDK sends your key in the `x-api-key` header. Keep API keys on the server;
+do not expose them in browser bundles or mobile apps.
+
+## First Screenshot
+
+```python
+import os
+
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+metadata = client.save(
+    {
+        "url": "https://example.com",
+        "width": 1440,
+        "height": 900,
+    },
+    "screenshot.png",
+)
+
+print(f"Screenshot ID: {metadata.screenshot_id}")
+print(f"Credits remaining: {metadata.credits_remaining}")
+```
+
+## Usage
+
+### Initialize the Client
+
+```python
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(
+    "sk_live_your_key_here",
+    base_url="https://screenshotapi.to",
+    timeout=60.0,
+)
+```
+
+### Capture Bytes
+
+```python
+from screenshotapi import ScreenshotOptions
+
+result = client.screenshot(
+    ScreenshotOptions(
+        url="https://example.com",
+        full_page=True,
+        type="webp",
+        quality=90,
+        color_scheme="dark",
+    )
+)
+
+image_bytes = result.image
+content_type = result.content_type
+credits_remaining = result.metadata.credits_remaining
+```
+
+Plain dictionaries are also supported:
+
+```python
+result = client.screenshot(
+    {
+        "url": "https://example.com",
+        "full_page": True,
+        "type": "webp",
+    }
+)
+```
+
+### Async Capture
+
+```python
+import asyncio
+import os
+
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+
+async def main() -> None:
+    result = await client.async_screenshot({"url": "https://example.com"})
+    print(f"Duration: {result.metadata.duration_ms}ms")
+
+    await client.async_save({"url": "https://example.com"}, "screenshot.png")
+
+
+asyncio.run(main())
+```
+
+## Advanced Options
+
+```python
+result = client.screenshot(
+    {
+        "url": "https://example.com/dashboard",
+        "width": 1280,
+        "height": 720,
+        "device_pixel_ratio": 2,
+        "full_page": False,
+        "type": "webp",
+        "quality": 85,
+        "color_scheme": "dark",
+        "wait_until": "networkidle0",
+        "wait_for_selector": ".ready",
+        "delay": 500,
+        "block_ads": True,
+        "remove_cookie_banners": True,
+        "remove_popups": True,
+        "remove_elements": [".newsletter", "#cookie-banner"],
+        "css_inject": "body { caret-color: transparent; }",
+        "js_inject": "window.scrollTo(0, 0)",
+        "stealth_mode": True,
+        "timezone": "America/New_York",
+        "locale": "en-US",
+        "cache_ttl": 3600,
+        "preload_fonts": True,
+        "geo_latitude": 40.7128,
+        "geo_longitude": -74.0060,
+        "geo_accuracy": 25,
+    }
+)
+```
+
+HTML rendering uses `POST /api/v1/screenshot` automatically:
+
+```python
+result = client.screenshot(
+    {
+        "html": "<html><body><h1>Invoice #123</h1></body></html>",
+        "type": "pdf",
+    }
+)
+```
+
+Supported options:
+
+| Python option | API parameter | Notes |
+|---|---|---|
+| `url` | `url` | Required unless `html` is provided |
+| `html` | `html` | Raw HTML, sent with POST |
+| `width`, `height` | `width`, `height` | Viewport size |
+| `full_page` | `fullPage` | Capture full scrollable page |
+| `type` | `type` | `png`, `jpeg`, `webp`, or `pdf` |
+| `quality` | `quality` | JPEG/WebP quality, 1-100 |
+| `color_scheme` | `colorScheme` | `light` or `dark` |
+| `wait_until` | `waitUntil` | `load`, `domcontentloaded`, `networkidle0`, `networkidle2` |
+| `wait_for_selector` | `waitForSelector` | CSS selector to wait for |
+| `delay` | `delay` | Extra delay in milliseconds |
+| `block_ads` | `blockAds` | Remove ads before capture |
+| `remove_cookie_banners` | `removeCookieBanners` | Remove common consent banners |
+| `css_inject`, `js_inject` | `cssInject`, `jsInject` | Inject CSS or JavaScript before capture |
+| `stealth_mode` | `stealthMode` | Enable anti-bot fingerprint masking |
+| `device_pixel_ratio` | `devicePixelRatio` | `1`, `2`, or `3` |
+| `timezone`, `locale` | `timezone`, `locale` | Browser emulation settings |
+| `cache_ttl` | `cacheTtl` | Cache identical captures for N seconds |
+| `preload_fonts` | `preloadFonts` | Preload Google Fonts before capture |
+| `remove_elements` | `removeElements` | CSS selectors to remove |
+| `remove_popups` | `removePopups` | Remove common overlays and modals |
+| `mockup_device` | `mockupDevice` | `browser`, `iphone`, or `macbook` frame |
+| `geo_latitude`, `geo_longitude`, `geo_accuracy` | `geoLocation` or geo query params | Browser geolocation override |
+
+## Error Handling
+
+```python
+from screenshotapi import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidAPIKeyError,
+    NetworkError,
+    ScreenshotAPI,
+    ScreenshotAPIError,
+    ScreenshotFailedError,
+)
+
+client = ScreenshotAPI("sk_live_your_key_here")
+
+try:
+    client.screenshot({"url": "https://example.com"})
+except AuthenticationError:
+    print("Missing API key")
+except InvalidAPIKeyError:
+    print("Invalid or revoked API key")
+except InsufficientCreditsError as exc:
+    print(f"No credits remaining. Balance: {exc.balance}")
+except ScreenshotFailedError as exc:
+    print(f"Screenshot failed: {exc}")
+except NetworkError as exc:
+    print(f"Could not reach ScreenshotAPI: {exc}")
+except ScreenshotAPIError as exc:
+    print(f"ScreenshotAPI error {exc.status} ({exc.code}): {exc}")
+```
+
+## Examples
+
+Runnable examples live in `examples/`:
+
+- `script_usage.py` for one-off scripts and cron jobs
+- `fastapi_app.py` for FastAPI endpoints
+- `django_view.py` for Django views
+- `flask_app.py` for Flask routes
+
+## Pricing and Free Tier
+
+ScreenshotAPI includes
+[200 free screenshots per month](https://screenshotapi.to/pricing?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+with no credit card required. Paid subscriptions and credit packs are available
+when you need more volume.
+
+## Links
+
+- [Documentation](https://screenshotapi.to/docs?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Screenshot API reference](https://screenshotapi.to/docs/api/screenshot?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Pricing](https://screenshotapi.to/pricing?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Support](mailto:support@screenshotapi.to?subject=Python%20SDK%20support)
+
+## License
+
+MIT

screenshotapi_to-1.0.0/README.md

@@ -0,0 +1,247 @@
+# screenshotapi
+
+Official typed Python SDK for
+[ScreenshotAPI](https://screenshotapi.to?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk),
+the hosted screenshot API for turning URLs or HTML into PNG, JPEG, WebP, or PDF
+captures.
+
+## Install
+
+```bash
+pip install screenshotapi-to
+```
+
+Python 3.8+ is supported. The distribution package is `screenshotapi-to`, the
+import package is `screenshotapi`, and the package ships `py.typed` metadata for
+type checkers.
+
+## Authentication
+
+Create an API key in the ScreenshotAPI dashboard, then keep it in an environment
+variable:
+
+```bash
+export SCREENSHOTAPI_KEY="sk_live_your_key_here"
+```
+
+The SDK sends your key in the `x-api-key` header. Keep API keys on the server;
+do not expose them in browser bundles or mobile apps.
+
+## First Screenshot
+
+```python
+import os
+
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+metadata = client.save(
+    {
+        "url": "https://example.com",
+        "width": 1440,
+        "height": 900,
+    },
+    "screenshot.png",
+)
+
+print(f"Screenshot ID: {metadata.screenshot_id}")
+print(f"Credits remaining: {metadata.credits_remaining}")
+```
+
+## Usage
+
+### Initialize the Client
+
+```python
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(
+    "sk_live_your_key_here",
+    base_url="https://screenshotapi.to",
+    timeout=60.0,
+)
+```
+
+### Capture Bytes
+
+```python
+from screenshotapi import ScreenshotOptions
+
+result = client.screenshot(
+    ScreenshotOptions(
+        url="https://example.com",
+        full_page=True,
+        type="webp",
+        quality=90,
+        color_scheme="dark",
+    )
+)
+
+image_bytes = result.image
+content_type = result.content_type
+credits_remaining = result.metadata.credits_remaining
+```
+
+Plain dictionaries are also supported:
+
+```python
+result = client.screenshot(
+    {
+        "url": "https://example.com",
+        "full_page": True,
+        "type": "webp",
+    }
+)
+```
+
+### Async Capture
+
+```python
+import asyncio
+import os
+
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+
+async def main() -> None:
+    result = await client.async_screenshot({"url": "https://example.com"})
+    print(f"Duration: {result.metadata.duration_ms}ms")
+
+    await client.async_save({"url": "https://example.com"}, "screenshot.png")
+
+
+asyncio.run(main())
+```
+
+## Advanced Options
+
+```python
+result = client.screenshot(
+    {
+        "url": "https://example.com/dashboard",
+        "width": 1280,
+        "height": 720,
+        "device_pixel_ratio": 2,
+        "full_page": False,
+        "type": "webp",
+        "quality": 85,
+        "color_scheme": "dark",
+        "wait_until": "networkidle0",
+        "wait_for_selector": ".ready",
+        "delay": 500,
+        "block_ads": True,
+        "remove_cookie_banners": True,
+        "remove_popups": True,
+        "remove_elements": [".newsletter", "#cookie-banner"],
+        "css_inject": "body { caret-color: transparent; }",
+        "js_inject": "window.scrollTo(0, 0)",
+        "stealth_mode": True,
+        "timezone": "America/New_York",
+        "locale": "en-US",
+        "cache_ttl": 3600,
+        "preload_fonts": True,
+        "geo_latitude": 40.7128,
+        "geo_longitude": -74.0060,
+        "geo_accuracy": 25,
+    }
+)
+```
+
+HTML rendering uses `POST /api/v1/screenshot` automatically:
+
+```python
+result = client.screenshot(
+    {
+        "html": "<html><body><h1>Invoice #123</h1></body></html>",
+        "type": "pdf",
+    }
+)
+```
+
+Supported options:
+
+| Python option | API parameter | Notes |
+|---|---|---|
+| `url` | `url` | Required unless `html` is provided |
+| `html` | `html` | Raw HTML, sent with POST |
+| `width`, `height` | `width`, `height` | Viewport size |
+| `full_page` | `fullPage` | Capture full scrollable page |
+| `type` | `type` | `png`, `jpeg`, `webp`, or `pdf` |
+| `quality` | `quality` | JPEG/WebP quality, 1-100 |
+| `color_scheme` | `colorScheme` | `light` or `dark` |
+| `wait_until` | `waitUntil` | `load`, `domcontentloaded`, `networkidle0`, `networkidle2` |
+| `wait_for_selector` | `waitForSelector` | CSS selector to wait for |
+| `delay` | `delay` | Extra delay in milliseconds |
+| `block_ads` | `blockAds` | Remove ads before capture |
+| `remove_cookie_banners` | `removeCookieBanners` | Remove common consent banners |
+| `css_inject`, `js_inject` | `cssInject`, `jsInject` | Inject CSS or JavaScript before capture |
+| `stealth_mode` | `stealthMode` | Enable anti-bot fingerprint masking |
+| `device_pixel_ratio` | `devicePixelRatio` | `1`, `2`, or `3` |
+| `timezone`, `locale` | `timezone`, `locale` | Browser emulation settings |
+| `cache_ttl` | `cacheTtl` | Cache identical captures for N seconds |
+| `preload_fonts` | `preloadFonts` | Preload Google Fonts before capture |
+| `remove_elements` | `removeElements` | CSS selectors to remove |
+| `remove_popups` | `removePopups` | Remove common overlays and modals |
+| `mockup_device` | `mockupDevice` | `browser`, `iphone`, or `macbook` frame |
+| `geo_latitude`, `geo_longitude`, `geo_accuracy` | `geoLocation` or geo query params | Browser geolocation override |
+
+## Error Handling
+
+```python
+from screenshotapi import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidAPIKeyError,
+    NetworkError,
+    ScreenshotAPI,
+    ScreenshotAPIError,
+    ScreenshotFailedError,
+)
+
+client = ScreenshotAPI("sk_live_your_key_here")
+
+try:
+    client.screenshot({"url": "https://example.com"})
+except AuthenticationError:
+    print("Missing API key")
+except InvalidAPIKeyError:
+    print("Invalid or revoked API key")
+except InsufficientCreditsError as exc:
+    print(f"No credits remaining. Balance: {exc.balance}")
+except ScreenshotFailedError as exc:
+    print(f"Screenshot failed: {exc}")
+except NetworkError as exc:
+    print(f"Could not reach ScreenshotAPI: {exc}")
+except ScreenshotAPIError as exc:
+    print(f"ScreenshotAPI error {exc.status} ({exc.code}): {exc}")
+```
+
+## Examples
+
+Runnable examples live in `examples/`:
+
+- `script_usage.py` for one-off scripts and cron jobs
+- `fastapi_app.py` for FastAPI endpoints
+- `django_view.py` for Django views
+- `flask_app.py` for Flask routes
+
+## Pricing and Free Tier
+
+ScreenshotAPI includes
+[200 free screenshots per month](https://screenshotapi.to/pricing?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+with no credit card required. Paid subscriptions and credit packs are available
+when you need more volume.
+
+## Links
+
+- [Documentation](https://screenshotapi.to/docs?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Screenshot API reference](https://screenshotapi.to/docs/api/screenshot?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Pricing](https://screenshotapi.to/pricing?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Support](mailto:support@screenshotapi.to?subject=Python%20SDK%20support)
+
+## License
+
+MIT

screenshotapi_to-1.0.0/examples/django_view.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse, JsonResponse
+
+from screenshotapi import ScreenshotAPI, ScreenshotAPIError
+
+
+def screenshot_view(request: HttpRequest) -> HttpResponse:
+    url = request.GET.get("url")
+    if not url:
+        return JsonResponse({"error": "url is required"}, status=400)
+
+    client = ScreenshotAPI(settings.SCREENSHOTAPI_KEY)
+
+    try:
+        result = client.screenshot(
+            {
+                "url": url,
+                "width": 1280,
+                "height": 720,
+                "type": "png",
+                "cache_ttl": 3600,
+            }
+        )
+    except ScreenshotAPIError as exc:
+        return JsonResponse({"error": str(exc), "code": exc.code}, status=502)
+
+    response = HttpResponse(result.image, content_type=result.content_type)
+    response["x-screenshot-id"] = result.metadata.screenshot_id
+    response["x-credits-remaining"] = str(result.metadata.credits_remaining)
+    return response

screenshotapi_to-1.0.0/examples/fastapi_app.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+
+from fastapi import FastAPI, HTTPException, Response
+
+from screenshotapi import ScreenshotAPI, ScreenshotAPIError
+
+app = FastAPI()
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+
+@app.get("/screenshot")
+def screenshot(url: str) -> Response:
+    try:
+        result = client.screenshot(
+            {
+                "url": url,
+                "type": "webp",
+                "width": 1440,
+                "height": 900,
+                "block_ads": True,
+                "remove_cookie_banners": True,
+            }
+        )
+    except ScreenshotAPIError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    return Response(content=result.image, media_type=result.content_type)

screenshotapi_to-1.0.0/examples/flask_app.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import os
+
+from flask import Flask, Response, jsonify, request
+
+from screenshotapi import ScreenshotAPI, ScreenshotAPIError
+
+app = Flask(__name__)
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+
+@app.get("/screenshot")
+def screenshot() -> Response:
+    url = request.args.get("url")
+    if not url:
+        return jsonify({"error": "url is required"}), 400
+
+    try:
+        result = client.screenshot(
+            {
+                "url": url,
+                "full_page": request.args.get("full_page") == "true",
+                "type": "jpeg",
+                "quality": 85,
+            }
+        )
+    except ScreenshotAPIError as exc:
+        return jsonify({"error": str(exc), "code": exc.code}), 502
+
+    return Response(result.image, mimetype=result.content_type)