websitescreenshotworld 0.1.0__tar.gz

websitescreenshotworld-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.idea/
+.vscode/
+*.swp
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

websitescreenshotworld-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses
+[semantic versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-09
+
+The first release.
+
+### Added
+
+- `WebsiteScreenshotWorld` and `AsyncWebsiteScreenshotWorld`, one client for both products, with keys
+  read from `WSW_INSTANT_SNAP_API_KEY` and `WSW_AUTO_SCHEDULE_API_KEY` when not passed, and an
+  optional `httpx.Client` or `httpx.AsyncClient` of your own.
+- Instant Snap: `capture`, `capture_file` (the file streamed from the answer, with its metadata),
+  `capture_to_bucket`, `get`, `download`, `defaults` and `catalog`, taking every capture option as a
+  typed keyword argument.
+- Instant Snap async captures: `submit` and `submit_to_bucket` (answered at once with the capture
+  `queued`) and `wait`, which reads the capture until it has finished or `timeout_seconds` runs out;
+  the `timeout` option (`SubmitOptions`, 30 to 300 seconds); the `CaptureStatus.QUEUED` and
+  `CaptureStatus.RUNNING` statuses; and the `queue_full` (`RateLimitError`, not retried) and
+  `capture_expired` (`CaptureError`) error codes.
+- Auto Schedule: `trigger_now`.
+- The `press_escape` capture option, and the `sitemap_schedule_not_triggerable` error code (an
+  `InvalidRequestError`: a sitemap schedule runs only on its schedule), from API version 1.1.0.
+- Frozen dataclass results with timezone-aware `datetime` fields, string tokens with named constants,
+  and the answer as received in `raw`.
+- An `Idempotency-Key` on every capture, generated when not given and reused on retries.
+- Retries of `rate_limited`, `capture_busy`, `service_unavailable`, `idempotency_key_in_use` and
+  connection failures, honouring `retry_after_seconds` and `Retry-After`, within the call's timeout.
+- One error class per kind of refusal under `WebsiteScreenshotWorldError`, plus `APIConnectionError`
+  and `APITimeoutError`.
+- `webhooks.verify`, which checks the `X-WSW-Signature` header and returns a typed event for every
+  documented event type, or `UnknownEvent` for a type added later.
+
+[0.1.0]: https://github.com/websitescreenshotworld/websitescreenshotworld-python/tree/v0.1.0

websitescreenshotworld-0.1.0/LICENSE

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

websitescreenshotworld-0.1.0/PKG-INFO

@@ -0,0 +1,506 @@
+Metadata-Version: 2.4
+Name: websitescreenshotworld
+Version: 0.1.0
+Summary: Python client for the Website Screenshot World Instant Snap and Auto Schedule APIs.
+Project-URL: Homepage, https://websitescreenshotworld.com
+Project-URL: Source, https://github.com/websitescreenshotworld/websitescreenshotworld-python
+Project-URL: Changelog, https://github.com/websitescreenshotworld/websitescreenshotworld-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/websitescreenshotworld/websitescreenshotworld-python/issues
+Author-email: Silhouettec Solutions Private Limited <support@websitescreenshotworld.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,pdf,screenshot,webhooks,website screenshot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy==2.4.0; extra == 'dev'
+Requires-Dist: pytest==9.2.0; extra == 'dev'
+Requires-Dist: ruff==0.17.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Website Screenshot World for Python
+
+The Python client for [Website Screenshot World](https://websitescreenshotworld.com): capture web pages
+on demand with **Instant Snap**, start a scheduled capture now with **Auto Schedule**, and verify the
+webhooks both send.
+
+It has a sync and an asyncio client, typed options and results, streamed file downloads, async
+captures (`submit`, `submit_to_bucket` and `wait`), and the retry and idempotency rules the API
+expects.
+
+## Install
+
+```sh
+pip install websitescreenshotworld
+```
+
+Python 3.10 or later. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quick start
+
+Create API keys in the dashboard and put them in the environment:
+
+```sh
+export WSW_INSTANT_SNAP_API_KEY="wsw_api_..."
+export WSW_AUTO_SCHEDULE_API_KEY="wsw_autoapi_..."
+```
+
+### Instant Snap
+
+```python
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+with WebsiteScreenshotWorld() as client:
+    capture = client.instant_snap.capture(
+        url="https://example.com",
+        format="webp",
+        viewport={"width": 1440, "height": 900},
+        block_ads=True,
+    )
+    print(capture.id, capture.width, capture.height)
+    print(capture.download_url)  # valid for 60 minutes
+```
+
+Options are keyword arguments named exactly as in the
+[API reference](https://api.websitescreenshotworld.com/instant-snap/v1/openapi.json). Nested blocks
+(`viewport`, `geolocation`, `selectors`, `proxy`, `timestamp_watermark`, `page_source`) are plain
+dictionaries, typed with `TypedDict`s so your editor and type checker know their fields. An option you
+leave out (or pass as `None`) is not sent and takes the API's default; `False`, `0` and `""` are sent.
+The names in `headers` and `cookies` are sent exactly as you write them.
+
+### Auto Schedule
+
+```python
+from websitescreenshotworld import TriggerStatus, WebsiteScreenshotWorld
+
+with WebsiteScreenshotWorld() as client:
+    result = client.auto_schedule.trigger_now("7d4e2b1a-6c5f-4a3e-9d8c-2b1a0f9e8d7c")
+    if result.status == TriggerStatus.ALREADY_PENDING:
+        print("A capture of this page is already queued; nothing new was charged.")
+```
+
+The web page's id is in the dashboard. The capture's result arrives by [webhook](#webhooks).
+
+### asyncio
+
+`AsyncWebsiteScreenshotWorld` has the same settings and methods; await them.
+
+```python
+import asyncio
+
+from websitescreenshotworld import AsyncWebsiteScreenshotWorld
+
+
+async def main() -> None:
+    async with AsyncWebsiteScreenshotWorld() as client:
+        capture = await client.instant_snap.capture(url="https://example.com")
+        print(capture.download_url)
+
+
+asyncio.run(main())
+```
+
+## Getting the file
+
+### In the answer: `capture_file`
+
+`capture_file` returns the file itself, streamed from the connection rather than held in memory.
+Use it in a `with` block so the connection is released:
+
+```python
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+client = WebsiteScreenshotWorld()
+
+with client.instant_snap.capture_file(url="https://example.com", format="png") as file:
+    print(file.filename, file.content_type, file.width, file.height, file.sha256)
+    file.save("example.png")
+```
+
+The body can be read once: `save(path_or_stream)`, `read()` for the bytes, or `iter_bytes()` for
+chunks. The metadata from the `X-InstantSnap-*` headers is on the object (`id`, `status`, `width`,
+`height`, `size_bytes`, `duration_ms`, `page_http_status`, `captured_at`, `final_url`, `sha256`,
+`part_count`, `spec_version`), with `filename` taken from `Content-Disposition`.
+
+With asyncio, `async with client.instant_snap.capture_file(...) as file:` and `await file.save(...)`.
+
+A file returned this way is not kept by the API, and `page_source` is not available with it.
+
+### Later: `get` and `download`
+
+A capture made with `capture` is kept for 24 hours. `get` reads it back with a fresh
+`download_url`, and `download` streams the file to a path or a binary stream:
+
+```python
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+client = WebsiteScreenshotWorld()
+
+capture = client.instant_snap.get("3f6c2a1e-9b8d-4c7e-a5f4-1d2e3c4b5a69")
+client.instant_snap.download(capture, "example.png")
+
+with open("example-copy.png", "wb") as stream:
+    client.instant_snap.download(capture, stream)
+```
+
+The download link is signed, so the API key is not sent with it.
+
+### Into your bucket: `capture_to_bucket`
+
+```python
+import os
+
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+client = WebsiteScreenshotWorld()
+
+capture = client.instant_snap.capture_to_bucket(
+    url="https://example.com",
+    s3_delivery={
+        "access_key_id": os.environ["S3_ACCESS_KEY_ID"],
+        "secret_access_key": os.environ["S3_SECRET_ACCESS_KEY"],
+        "bucket": "captures",
+        "region": "eu-west-2",
+        "key_prefix": "example/",
+    },
+)
+assert capture.s3_delivery is not None
+print(capture.s3_delivery.status)  # "in_progress", or "completed" with wait_for_sync
+```
+
+Any S3-compatible service works: give `endpoint_url` (https) instead of, or as well as, `region`.
+
+### Defaults and catalog
+
+`client.instant_snap.defaults()` returns the value each option takes when you leave it out, and the
+limits (no key needed). `client.instant_snap.catalog()` lists the devices `emulated_device` accepts
+and the countries `proxy` accepts.
+
+## Async captures
+
+`submit` queues a capture and answers at once with the capture in status `queued`; it then runs when a
+browser is free (`queued`, then `running`, then `succeeded` or `failed`). `wait` reads it with `get`
+until it has finished:
+
+```python
+from websitescreenshotworld import CaptureStatus, WebsiteScreenshotWorld
+
+with WebsiteScreenshotWorld() as client:
+    queued = client.instant_snap.submit(url="https://example.com", format="png", timeout=240)
+    print(queued.id, queued.status)  # "queued"
+
+    capture = client.instant_snap.wait(queued, timeout_seconds=360, poll_interval_seconds=3)
+    if capture.status == CaptureStatus.SUCCEEDED:
+        client.instant_snap.download(capture, "example.png")
+    elif capture.status == CaptureStatus.FAILED:
+        print("Failed:", capture.error_code)
+    else:
+        print("Still", capture.status, "- wait again later")
+```
+
+`submit_to_bucket` does the same into your bucket, taking `s3_delivery` as `capture_to_bucket` does:
+
+```python
+import os
+
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+client = WebsiteScreenshotWorld()
+
+queued = client.instant_snap.submit_to_bucket(
+    url="https://example.com",
+    s3_delivery={
+        "access_key_id": os.environ["S3_ACCESS_KEY_ID"],
+        "secret_access_key": os.environ["S3_SECRET_ACCESS_KEY"],
+        "bucket": "captures",
+        "region": "eu-west-2",
+    },
+)
+capture = client.instant_snap.wait(queued.id)
+```
+
+- `timeout` here is the API's option (`SubmitOptions`): the browser time the capture may use, 30 to
+  300 seconds, 120 when left out. Only `submit` and `submit_to_bucket` take it. The call itself waits
+  only for the answer, so it uses the client's `timeout` (30 seconds), not `capture_timeout`.
+- A capture still waiting 15 minutes after it was accepted ends `failed` with `capture_expired`, and
+  is not charged.
+- When the organization already has as many async captures waiting or running as it may, `submit`
+  raises `RateLimitError` with `error_code` `queue_full` and `retry_after_seconds`. It is not retried
+  by the library: wait that long, or for some captures to finish, and submit again.
+- `wait` takes the capture or its id. It returns as soon as the status is no longer `queued`,
+  `running` or `pending`. If `timeout_seconds` (default 360) runs out first, it returns the capture as
+  last read, still unfinished, rather than raising. `poll_interval_seconds` defaults to 3. An error
+  from `get` is raised as it is. With asyncio, cancelling the task or `asyncio.timeout()` stops it.
+
+## Results
+
+Results are frozen dataclasses: `Capture`, `TriggerResult`, `Defaults`, `Catalog`. Timestamps are
+timezone-aware `datetime`s. Tokens such as `status` and `format` stay plain strings, so a value the
+API adds later still comes through; compare them with the constants in `CaptureStatus`, `Format`,
+`MediaCategory`, `ResponseType`, `S3DeliveryStatus`, `TriggerStatus` and `TriggeredBy`. Each result
+also has `raw`, the answer as received, for fields added after this release.
+
+## Errors and retries
+
+Every error is a `WebsiteScreenshotWorldError` with `error_code`, `message`, `http_status`,
+`retry_after_seconds` and `body`. Branch on the class or on `error_code`, never on the status or the
+message:
+
+| Class | Raised for |
+|---|---|
+| `AuthenticationError` | `api_key_invalid`, or no key for the product (raised before sending) |
+| `InvalidRequestError` | `validation_failed`, `s3_destination_invalid`, `web_page_id_invalid`, `idempotency_key_reused`, `sitemap_schedule_not_triggerable` |
+| `PlanLimitError` | `quota_exhausted`, `feature_not_available`, `no_trigger_allowance`, `forbidden` |
+| `NotFoundError` | `capture_not_found`, `web_page_not_found`, `not_found` |
+| `RateLimitError` | `rate_limited`, `queue_full` |
+| `CaptureError` | `capture_failed`, `capture_timeout`, `payload_too_large`, `capture_expired` |
+| `ServiceError` | `capture_busy`, `service_unavailable`, `internal_error`, `request_cancelled`, `idempotency_key_in_use` |
+| `APIConnectionError` | the request could not be sent, or no answer came back |
+| `APITimeoutError` | a subclass of `APIConnectionError`: the timeout passed |
+| `SignatureVerificationError` | a webhook signature that does not match |
+
+A code this version does not know yet raises `WebsiteScreenshotWorldError` itself.
+
+```python
+from websitescreenshotworld import (
+    CaptureError,
+    PlanLimitError,
+    WebsiteScreenshotWorld,
+    WebsiteScreenshotWorldError,
+)
+
+client = WebsiteScreenshotWorld()
+
+try:
+    capture = client.instant_snap.capture(url="https://example.com")
+except CaptureError as error:
+    print("The page could not be captured:", error.message)
+except PlanLimitError as error:
+    print("Plan limit:", error.error_code)
+except WebsiteScreenshotWorldError as error:
+    print("Failed:", error)
+```
+
+`rate_limited`, `capture_busy`, `service_unavailable`, `idempotency_key_in_use` and connection
+failures are retried twice (three attempts in all). The wait is the API's `retry_after_seconds` (or
+`Retry-After`), at most 60 seconds, and otherwise 0.5 s and then 1 s with a little jitter. Nothing
+else is retried: `capture_failed` and `capture_timeout` are answers about the website, and a retry
+would fail the same way; `queue_full` would only meet the same full queue, so it is raised at once
+with `retry_after_seconds`. Set `max_retries` on the client to change the count, or `0` to turn retries
+off.
+
+## Idempotency keys
+
+Every capture carries an `Idempotency-Key`, so a retry never captures or charges twice. The client
+makes a random one per call and reuses it on that call's retries. Pass your own to make a call safe
+to repeat across processes for 24 hours, for example when a job queue may run a task twice:
+
+```python
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+client = WebsiteScreenshotWorld()
+
+capture = client.instant_snap.capture(
+    url="https://example.com/pricing",
+    idempotency_key="order-1234-hero",
+)
+```
+
+A repeat with the same key gets the first capture back. The key must not be reused with different
+options (`InvalidRequestError`, `idempotency_key_reused`), and `capture_file` results are not kept,
+so they cannot be replayed. `trigger_now` needs no key: it is idempotent by itself.
+
+## Timeouts
+
+A capture may take the API up to 120 seconds on a slow page, so captures are allowed 180 seconds
+and every other call 30 seconds. The time covers the whole call, retries included: once it has
+passed, retrying stops and `APITimeoutError` is raised. Change the defaults on the client, or pass
+`timeout` to a single capture or download:
+
+```python
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+client = WebsiteScreenshotWorld(timeout=10, capture_timeout=240)
+capture = client.instant_snap.capture(url="https://example.com", timeout=60)
+```
+
+`submit` and `submit_to_bucket` use `timeout`, not `capture_timeout`, since they are answered at
+once; their `timeout` keyword is the API's async option (see [Async captures](#async-captures)).
+
+For asyncio, `asyncio.timeout()` and task cancellation stop a call, retries included, at once.
+
+## Webhooks
+
+Deliveries are signed with the endpoint's secret in the `X-WSW-Signature` header.
+`webhooks.verify` checks the signature and the timestamp (within 5 minutes by default) and returns a
+typed event:
+
+```python
+from websitescreenshotworld import webhooks
+
+
+def handle(body: bytes, signature: str | None, secret: str) -> None:
+    event = webhooks.verify(body, signature, secret)
+    match event:
+        case webhooks.InstantSnapCaptureEvent(type="capture.succeeded", data=capture):
+            print("Instant Snap capture ready:", capture.id)
+        case webhooks.AutoScheduleCaptureEvent(data=capture):
+            print(event.type, capture.schedule_id, capture.status)
+        case webhooks.CaptureChangedEvent(data=change):
+            print(f"{change.url} changed by {change.change_percent}%")
+        case webhooks.UnknownEvent():
+            print("An event type this library does not know yet:", event.type, event.data)
+```
+
+| Class | `type` | `data` |
+|---|---|---|
+| `InstantSnapCaptureEvent` | `capture.succeeded`, `capture.failed` (Instant Snap) | `Capture` |
+| `AutoScheduleCaptureEvent` | `capture.succeeded`, `capture.failed` (Auto Schedule) | `ScheduleCapture` |
+| `DeliveryCompletedEvent` | `delivery.completed` | `Delivery` |
+| `CaptureChangedEvent` | `capture.changed` | `CaptureChange` |
+| `SchedulePausedEvent` | `schedule.paused` | `SchedulePaused` |
+| `SitemapRunCompletedEvent` | `sitemap_run.completed` | `SitemapRun` |
+| `PingEvent` | `ping` | `Ping` |
+| `UnknownEvent` | anything else | the `data` dictionary |
+
+Every event has `id` (the same on redeliveries, so you can drop duplicates), `type`, `created_at`,
+`product` and `raw`. A bad signature raises `SignatureVerificationError`; answer it with a 400.
+
+**Pass the raw body.** The signature covers the exact bytes sent. A framework that parses the JSON
+and serialises it again changes them, and the signature no longer matches.
+
+Flask:
+
+```python
+from flask import Flask, request
+
+from websitescreenshotworld import webhooks
+
+app = Flask(__name__)
+
+
+@app.post("/webhooks/wsw")
+def wsw_webhook() -> tuple[str, int]:
+    try:
+        event = webhooks.verify(
+            request.get_data(), request.headers.get("X-WSW-Signature"), app.config["WSW_SECRET"]
+        )
+    except webhooks.SignatureVerificationError:
+        return "bad signature", 400
+    print(event.type)
+    return "", 204
+```
+
+Django:
+
+```python
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse, HttpResponseBadRequest
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+
+from websitescreenshotworld import webhooks
+
+
+@csrf_exempt
+@require_POST
+def wsw_webhook(request: HttpRequest) -> HttpResponse:
+    try:
+        event = webhooks.verify(
+            request.body, request.headers.get("X-WSW-Signature"), settings.WSW_SECRET
+        )
+    except webhooks.SignatureVerificationError:
+        return HttpResponseBadRequest("bad signature")
+    print(event.type)
+    return HttpResponse(status=204)
+```
+
+FastAPI (and Starlette):
+
+```python
+import os
+
+from fastapi import FastAPI, HTTPException, Request, Response
+
+from websitescreenshotworld import webhooks
+
+app = FastAPI()
+
+
+@app.post("/webhooks/wsw", status_code=204)
+async def wsw_webhook(request: Request) -> Response:
+    try:
+        event = webhooks.verify(
+            await request.body(),
+            request.headers.get("X-WSW-Signature"),
+            os.environ["WSW_WEBHOOK_SECRET"],
+        )
+    except webhooks.SignatureVerificationError:
+        raise HTTPException(status_code=400, detail="bad signature") from None
+    print(event.type)
+    return Response(status_code=204)
+```
+
+`webhooks.SignatureVerificationError` is the same class as `websitescreenshotworld.SignatureVerificationError`.
+
+## Configuration
+
+| Argument | Default |
+|---|---|
+| `instant_snap_api_key` | `WSW_INSTANT_SNAP_API_KEY` from the environment |
+| `auto_schedule_api_key` | `WSW_AUTO_SCHEDULE_API_KEY` from the environment |
+| `instant_snap_base_url` | `https://api.websitescreenshotworld.com` |
+| `auto_schedule_base_url` | `https://autoapi.websitescreenshotworld.com` |
+| `capture_timeout` | 180 seconds |
+| `timeout` | 30 seconds, for everything but captures |
+| `max_retries` | 2 |
+| `http_client` | a new `httpx.Client` (`httpx.AsyncClient` for the async client) |
+
+Either key may be left out if you use only one product; calling the other raises
+`AuthenticationError` before anything is sent.
+
+Pass your own `httpx.Client` for proxies, custom certificates or connection limits. The library does
+not close a client you pass in:
+
+```python
+import httpx
+
+from websitescreenshotworld import WebsiteScreenshotWorld
+
+http = httpx.Client(proxy="http://proxy.example.com:3128")
+client = WebsiteScreenshotWorld(http_client=http)
+```
+
+Create the client once and reuse it, so connections are pooled.
+
+## Supported versions
+
+CPython 3.10 to 3.13, tested on 3.10 and 3.13. The library follows semantic versioning; until 1.0, a
+minor version may change the API, as noted in the [changelog](CHANGELOG.md).
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+ruff format --check . && ruff check . && mypy
+pytest
+```
+
+The tests start `spec/conformance/server.js`, so they need Node.js 22 or later. `spec/` is the
+[websitescreenshotworld-spec](https://github.com/websitescreenshotworld/websitescreenshotworld-spec) submodule:
+clone with `git clone --recurse-submodules`, or run `git submodule update --init` in an existing clone.
+
+## License
+
+MIT. See [LICENSE](LICENSE).