screenshotdude 1.0.0__tar.gz

screenshotdude-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules
+.next
+dist
+.turbo
+.env
+.env.local
+*.log
+coverage
+storage-data
+__pycache__
+*.egg-info
+.venv
+*.tsbuildinfo
+.vercel
+
+# npm pack output
+*.tgz

screenshotdude-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScreenshotDude
+
+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.

screenshotdude-1.0.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: screenshotdude
+Version: 1.0.0
+Summary: Official Python SDK for the ScreenshotDude screenshot, content and AI-analysis API.
+Project-URL: Homepage, https://screenshotdude.com
+Project-URL: Documentation, https://screenshotdude.com/docs
+Author: ScreenshotDude
+License: MIT
+License-File: LICENSE
+Keywords: pdf,screenshot,screenshot-api,screenshotdude,sdk,web-scraping
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# screenshotdude
+
+Official Python SDK for the [ScreenshotDude](https://screenshotdude.com) API — screenshots & PDFs, content extraction,
+AI analysis, raw-HTML crawling and async jobs. Sync and asyncio clients, fully typed, built on `httpx`.
+
+```bash
+pip install screenshotdude
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from screenshotdude import ScreenshotDude
+
+client = ScreenshotDude(api_key="sl_live_...")  # or set SCREENSHOTDUDE_API_KEY
+
+# Screenshot straight to disk
+client.capture_to_file("https://example.com", "example.png", full_page=True)
+
+# Screenshot in memory
+shot = client.capture("https://example.com", device="iphone_14_pro", format="webp")
+print(shot.content_type, len(shot.content), shot.credits_charged, shot.request_id, shot.cached)
+```
+
+### Async
+
+```python
+import asyncio
+from screenshotdude import AsyncScreenshotDude
+
+async def main():
+    async with AsyncScreenshotDude() as client:
+        page = await client.content("https://example.com", include_markdown=True)
+        print(page["data"]["markdown"])
+
+asyncio.run(main())
+```
+
+`AsyncScreenshotDude` has the same methods as `ScreenshotDude`, all awaitable.
+
+## Configuration
+
+```python
+ScreenshotDude(
+    api_key=None,      # default: $SCREENSHOTDUDE_API_KEY (sent as the x-api-key header)
+    base_url=None,     # default: $SCREENSHOTDUDE_BASE_URL or https://api.screenshotdude.com
+    timeout=65,        # seconds, per attempt
+    max_retries=3,
+    retry_delay=1.0,   # seconds; delay = retry_delay * 1.5 ** attempt
+    transport=None,    # custom httpx transport (e.g. httpx.MockTransport for tests)
+    http_client=None,  # or bring your own httpx.Client / httpx.AsyncClient
+)
+```
+
+Every endpoint method accepts `request_options={"max_retries": 0, "timeout": 30}` to override per request.
+Use the client as a context manager (or call `close()` / `await aclose()`) to release connections.
+
+## Endpoints
+
+Parameters are passed as keyword arguments with the API's names (see `screenshotdude.types` for typed,
+documented `TypedDict`s). Booleans are sent as `"true"`/`"false"`, lists comma-joined
+(`block_resources=["image", "font"]`), and dicts JSON-encoded (`headers`, `cookies`, `custom_response`).
+
+### Capture — `GET /v1/capture`
+
+```python
+res = client.capture(
+    "https://example.com",
+    format="jpeg",
+    image_quality=80,
+    viewport_width=1440,
+    block_resources=["font", "media"],
+    wait_until=["networkidle0"],
+    headers={"Accept-Language": "fr-FR"},
+    cookies=[{"name": "session", "value": "abc", "domain": "example.com"}],
+    remove_cookie_banners=True,
+    dark_mode=True,
+)
+res.save("example.jpg")
+```
+
+Returns a `CaptureResult(content: bytes, content_type, request_id, credits_charged, cached)`, or a `dict`
+when the API answers with JSON: `s3_url=True` → `{"success": True, "data": {"url", "key", "bucket"}}`,
+`is_async=True` → `{"job_id": ...}`.
+
+### Content — `GET /v1/content`
+
+```python
+page = client.content("https://example.com", include_markdown=True, use_defuddle=True)
+print(page["data"]["metadata"]["title"], page["data"]["links"]["external"])
+```
+
+### Analyze — `GET /v1/analyze`
+
+```python
+insights = client.analyze(
+    "https://example.com",
+    custom_prompt="Focus on pricing",
+    custom_response={"sentiment": "overall sentiment of the page"},
+)
+print(insights["data"]["summary"], insights["data"]["keyFeatures"], insights["data"]["sentiment"])
+```
+
+### Crawler — `GET /v1/website/crawler`
+
+```python
+info = client.crawler("https://example.com", allow_redirects=False)  # dict
+html = client.crawler("https://example.com", return_page_source=True)  # str
+```
+
+### Async jobs
+
+```python
+accepted = client.capture("https://example.com", full_page=True, is_async=True)
+job = client.wait_for_job(
+    accepted["job_id"],
+    interval=2,        # first poll delay in seconds; grows x1.5 up to 60s
+    timeout=300,
+    on_progress=lambda j: print(j["status"], j["progress"]),
+)
+print(job["result"])  # capture jobs: {"url", "content_type", "size"} — a download URL
+```
+
+`wait_for_job` raises `ScreenshotDudeJobError` (with `.job`) when the job ends in `Error`, `NotFound` or
+`BadRequest`, or on timeout. `client.job(job_id)` polls once (free).
+
+### Account
+
+```python
+client.usage()                  # GET /v1/usage
+client.stats(engine="capture")  # GET /v1/stats?engine=capture
+```
+
+### Anything else
+
+```python
+res = client.request("GET", "/v1/usage", {"some": "param"})
+print(res.data, res.status, res.request_id, res.credits_charged, res.cached)
+```
+
+### Batching
+
+```python
+urls = ["https://a.com", "https://b.com"]
+for r in client.batch(urls, lambda u: client.content(u), concurrency=5):
+    print(urls[r.index], r.status, r.value if r.status == "fulfilled" else r.reason)
+
+# async: results = await aclient.batch(urls, lambda u: aclient.content(u), concurrency=5)
+```
+
+Failures don't stop the other items; results come back in input order.
+
+## Errors & retries
+
+```python
+from screenshotdude import ScreenshotDudeApiError, ScreenshotDudeConnectionError
+
+try:
+    client.capture("https://example.com")
+except ScreenshotDudeApiError as e:
+    print(e.status, e.message, e.request_id, e.response_body)
+    if e.status == 402:
+        print("Out of credits")
+    elif e.is_quota_exceeded:
+        print("API key quota reached")
+except ScreenshotDudeConnectionError as e:
+    print("Network problem:", e)
+```
+
+Retried automatically (up to `max_retries`, delay `retry_delay * 1.5 ** attempt`; a `Retry-After` header wins):
+network errors and timeouts, `408`, `500`, `502`, `503`, `504`, and `401` plan rate limits
+(`Rate limit exceeded: ...`). Never retried: `402`, per-key quotas (`... quota ...`) and other `4xx`.
+
+With `soft_fail=True` the API always answers HTTP 200 and failures come back as `{"error": ...}`.
+
+## Webhooks
+
+With `is_async=True` and `webhook_url=...`, ScreenshotDude POSTs the finished job to your URL, signed with
+`t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<body>")>`. Verify against the **raw** request body:
+
+```python
+from screenshotdude import verify_webhook
+
+@app.post("/screenshotdude-webhook")
+async def hook(request: Request):
+    body = await request.body()
+    if not verify_webhook(WEBHOOK_SECRET, body, request.headers.get("x-snaplens-signature")):
+        raise HTTPException(400)
+    job = json.loads(body)
+```
+
+`verify_webhook(secret, body, header, tolerance=300)` uses a constant-time comparison and rejects
+signatures older than `tolerance` seconds.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## License
+
+MIT

screenshotdude-1.0.0/README.md

@@ -0,0 +1,206 @@
+# screenshotdude
+
+Official Python SDK for the [ScreenshotDude](https://screenshotdude.com) API — screenshots & PDFs, content extraction,
+AI analysis, raw-HTML crawling and async jobs. Sync and asyncio clients, fully typed, built on `httpx`.
+
+```bash
+pip install screenshotdude
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from screenshotdude import ScreenshotDude
+
+client = ScreenshotDude(api_key="sl_live_...")  # or set SCREENSHOTDUDE_API_KEY
+
+# Screenshot straight to disk
+client.capture_to_file("https://example.com", "example.png", full_page=True)
+
+# Screenshot in memory
+shot = client.capture("https://example.com", device="iphone_14_pro", format="webp")
+print(shot.content_type, len(shot.content), shot.credits_charged, shot.request_id, shot.cached)
+```
+
+### Async
+
+```python
+import asyncio
+from screenshotdude import AsyncScreenshotDude
+
+async def main():
+    async with AsyncScreenshotDude() as client:
+        page = await client.content("https://example.com", include_markdown=True)
+        print(page["data"]["markdown"])
+
+asyncio.run(main())
+```
+
+`AsyncScreenshotDude` has the same methods as `ScreenshotDude`, all awaitable.
+
+## Configuration
+
+```python
+ScreenshotDude(
+    api_key=None,      # default: $SCREENSHOTDUDE_API_KEY (sent as the x-api-key header)
+    base_url=None,     # default: $SCREENSHOTDUDE_BASE_URL or https://api.screenshotdude.com
+    timeout=65,        # seconds, per attempt
+    max_retries=3,
+    retry_delay=1.0,   # seconds; delay = retry_delay * 1.5 ** attempt
+    transport=None,    # custom httpx transport (e.g. httpx.MockTransport for tests)
+    http_client=None,  # or bring your own httpx.Client / httpx.AsyncClient
+)
+```
+
+Every endpoint method accepts `request_options={"max_retries": 0, "timeout": 30}` to override per request.
+Use the client as a context manager (or call `close()` / `await aclose()`) to release connections.
+
+## Endpoints
+
+Parameters are passed as keyword arguments with the API's names (see `screenshotdude.types` for typed,
+documented `TypedDict`s). Booleans are sent as `"true"`/`"false"`, lists comma-joined
+(`block_resources=["image", "font"]`), and dicts JSON-encoded (`headers`, `cookies`, `custom_response`).
+
+### Capture — `GET /v1/capture`
+
+```python
+res = client.capture(
+    "https://example.com",
+    format="jpeg",
+    image_quality=80,
+    viewport_width=1440,
+    block_resources=["font", "media"],
+    wait_until=["networkidle0"],
+    headers={"Accept-Language": "fr-FR"},
+    cookies=[{"name": "session", "value": "abc", "domain": "example.com"}],
+    remove_cookie_banners=True,
+    dark_mode=True,
+)
+res.save("example.jpg")
+```
+
+Returns a `CaptureResult(content: bytes, content_type, request_id, credits_charged, cached)`, or a `dict`
+when the API answers with JSON: `s3_url=True` → `{"success": True, "data": {"url", "key", "bucket"}}`,
+`is_async=True` → `{"job_id": ...}`.
+
+### Content — `GET /v1/content`
+
+```python
+page = client.content("https://example.com", include_markdown=True, use_defuddle=True)
+print(page["data"]["metadata"]["title"], page["data"]["links"]["external"])
+```
+
+### Analyze — `GET /v1/analyze`
+
+```python
+insights = client.analyze(
+    "https://example.com",
+    custom_prompt="Focus on pricing",
+    custom_response={"sentiment": "overall sentiment of the page"},
+)
+print(insights["data"]["summary"], insights["data"]["keyFeatures"], insights["data"]["sentiment"])
+```
+
+### Crawler — `GET /v1/website/crawler`
+
+```python
+info = client.crawler("https://example.com", allow_redirects=False)  # dict
+html = client.crawler("https://example.com", return_page_source=True)  # str
+```
+
+### Async jobs
+
+```python
+accepted = client.capture("https://example.com", full_page=True, is_async=True)
+job = client.wait_for_job(
+    accepted["job_id"],
+    interval=2,        # first poll delay in seconds; grows x1.5 up to 60s
+    timeout=300,
+    on_progress=lambda j: print(j["status"], j["progress"]),
+)
+print(job["result"])  # capture jobs: {"url", "content_type", "size"} — a download URL
+```
+
+`wait_for_job` raises `ScreenshotDudeJobError` (with `.job`) when the job ends in `Error`, `NotFound` or
+`BadRequest`, or on timeout. `client.job(job_id)` polls once (free).
+
+### Account
+
+```python
+client.usage()                  # GET /v1/usage
+client.stats(engine="capture")  # GET /v1/stats?engine=capture
+```
+
+### Anything else
+
+```python
+res = client.request("GET", "/v1/usage", {"some": "param"})
+print(res.data, res.status, res.request_id, res.credits_charged, res.cached)
+```
+
+### Batching
+
+```python
+urls = ["https://a.com", "https://b.com"]
+for r in client.batch(urls, lambda u: client.content(u), concurrency=5):
+    print(urls[r.index], r.status, r.value if r.status == "fulfilled" else r.reason)
+
+# async: results = await aclient.batch(urls, lambda u: aclient.content(u), concurrency=5)
+```
+
+Failures don't stop the other items; results come back in input order.
+
+## Errors & retries
+
+```python
+from screenshotdude import ScreenshotDudeApiError, ScreenshotDudeConnectionError
+
+try:
+    client.capture("https://example.com")
+except ScreenshotDudeApiError as e:
+    print(e.status, e.message, e.request_id, e.response_body)
+    if e.status == 402:
+        print("Out of credits")
+    elif e.is_quota_exceeded:
+        print("API key quota reached")
+except ScreenshotDudeConnectionError as e:
+    print("Network problem:", e)
+```
+
+Retried automatically (up to `max_retries`, delay `retry_delay * 1.5 ** attempt`; a `Retry-After` header wins):
+network errors and timeouts, `408`, `500`, `502`, `503`, `504`, and `401` plan rate limits
+(`Rate limit exceeded: ...`). Never retried: `402`, per-key quotas (`... quota ...`) and other `4xx`.
+
+With `soft_fail=True` the API always answers HTTP 200 and failures come back as `{"error": ...}`.
+
+## Webhooks
+
+With `is_async=True` and `webhook_url=...`, ScreenshotDude POSTs the finished job to your URL, signed with
+`t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<body>")>`. Verify against the **raw** request body:
+
+```python
+from screenshotdude import verify_webhook
+
+@app.post("/screenshotdude-webhook")
+async def hook(request: Request):
+    body = await request.body()
+    if not verify_webhook(WEBHOOK_SECRET, body, request.headers.get("x-snaplens-signature")):
+        raise HTTPException(400)
+    job = json.loads(body)
+```
+
+`verify_webhook(secret, body, header, tolerance=300)` uses a constant-time comparison and rejects
+signatures older than `tolerance` seconds.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## License
+
+MIT

screenshotdude-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "screenshotdude"
+version = "1.0.0"
+description = "Official Python SDK for the ScreenshotDude screenshot, content and AI-analysis API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "ScreenshotDude" }]
+keywords = ["screenshotdude", "screenshot", "screenshot-api", "pdf", "web-scraping", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+  "Framework :: AsyncIO",
+]
+dependencies = ["httpx>=0.24,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://screenshotdude.com"
+Documentation = "https://screenshotdude.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["screenshotdude"]
+
+[tool.hatch.build.targets.sdist]
+include = ["screenshotdude", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

screenshotdude-1.0.0/screenshotdude/__init__.py

@@ -0,0 +1,55 @@
+"""Official Python SDK for the ScreenshotDude screenshot, content and AI-analysis API.
+
+Example::
+
+    from screenshotdude import ScreenshotDude
+
+    with ScreenshotDude() as client:  # reads SCREENSHOTDUDE_API_KEY
+        client.capture_to_file("https://example.com", "example.png", full_page=True)
+"""
+
+from ._client import (
+    DEFAULT_BASE_URL,
+    AsyncScreenshotDude,
+    ScreenshotDude,
+    __version__,
+    build_query,
+    is_retryable,
+    parse_retry_after,
+)
+from ._errors import ScreenshotDudeApiError, ScreenshotDudeConnectionError, ScreenshotDudeError, ScreenshotDudeJobError
+from ._webhook import compute_webhook_signature, verify_webhook
+from .types import ApiResponse, BatchResult, CaptureResult
+
+# Deprecated aliases for the pre-rebrand names. They will be removed in a future major version.
+Snaplens = ScreenshotDude
+AsyncSnaplens = AsyncScreenshotDude
+SnaplensError = ScreenshotDudeError
+SnaplensApiError = ScreenshotDudeApiError
+SnaplensConnectionError = ScreenshotDudeConnectionError
+SnaplensJobError = ScreenshotDudeJobError
+
+__all__ = [
+    "ScreenshotDude",
+    "AsyncScreenshotDude",
+    "CaptureResult",
+    "ApiResponse",
+    "BatchResult",
+    "ScreenshotDudeError",
+    "ScreenshotDudeApiError",
+    "ScreenshotDudeConnectionError",
+    "ScreenshotDudeJobError",
+    "verify_webhook",
+    "compute_webhook_signature",
+    "build_query",
+    "is_retryable",
+    "parse_retry_after",
+    "DEFAULT_BASE_URL",
+    "__version__",
+    "Snaplens",
+    "AsyncSnaplens",
+    "SnaplensError",
+    "SnaplensApiError",
+    "SnaplensConnectionError",
+    "SnaplensJobError",
+]