blockquote-agents 0.1.0__py3-none-any.whl

blockquote_agents/__init__.py

@@ -0,0 +1,82 @@
+"""Official Blockquote client. Uses Python's standard library."""
+import json
+from dataclasses import dataclass
+from urllib.error import HTTPError
+from urllib.parse import quote, urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+
+@dataclass
+class Response:
+    data: object
+    status: int
+    headers: object
+
+
+class BlockquoteError(Exception):
+    def __init__(self, response):
+        super().__init__(f"Blockquote HTTP {response.status}")
+        self.data = response.data
+        self.status = response.status
+        self.headers = response.headers
+        self.retry_after = response.headers.get("Retry-After")
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class Blockquote:
+    def __init__(self, api_key=None, base_url="https://blockquote.io/api/v1", timeout=30):
+        base = urlsplit(base_url)
+        if base.scheme != "https" or not base.netloc or base.username or base.password or base.query or base.fragment:
+            raise ValueError("base_url must be an HTTPS URL without credentials, query, or fragment")
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._opener = build_opener(_NoRedirect())
+
+    def _request(self, path, body=None, idempotency_key=None):
+        headers = {"Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        request = Request(self.base_url + path, headers=headers,
+                          data=None if body is None else json.dumps(body).encode())
+        try:
+            raw = self._opener.open(request, timeout=self.timeout)
+        except HTTPError as error:
+            raw = error
+        with raw:
+            text = raw.read().decode("utf-8", errors="replace")
+            try:
+                data = json.loads(text)
+            except ValueError:
+                data = text
+            response = Response(data, raw.status, raw.headers)
+        if not 200 <= response.status < 300:
+            raise BlockquoteError(response)
+        return response
+
+    def start_scan(self, url, *, refresh=None, turnstile_token=None, idempotency_key=None):
+        body = {"url": url}
+        if refresh is not None:
+            body["refresh"] = refresh
+        if turnstile_token is not None:
+            body["turnstileToken"] = turnstile_token
+        return self._request("/scan", body, idempotency_key)
+
+    def get_scan(self, scan_id):
+        if not isinstance(scan_id, str) or not scan_id.strip() or scan_id in (".", ".."):
+            raise ValueError("A scan id is required")
+        return self._request("/scan/" + quote(scan_id, safe=""))
+
+    def compare_scans(self, *, from_id=None, to_id=None, url=None):
+        if (url and (from_id is not None or to_id is not None)) or (not url and (not from_id or not to_id)):
+            raise ValueError("Use url or both from_id and to_id")
+        query = {"url": url} if url else {"from": from_id, "to": to_id}
+        return self._request("/compare?" + urlencode(query))

blockquote_agents-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: blockquote-agents
+Version: 0.1.0
+Summary: Official Blockquote Python SDK for AI visibility scans
+License: MIT
+Project-URL: Homepage, https://blockquote.io
+Project-URL: Repository, https://github.com/ArneFfm/blockquote-agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Blockquote Python SDK
+
+Official client for [Blockquote](https://blockquote.io). Requires Python 3.10 or later. No runtime dependencies.
+
+```sh
+pip install blockquote-agents
+```
+
+```python
+import os
+import uuid
+from blockquote_agents import Blockquote, BlockquoteError
+
+client = Blockquote(api_key=os.getenv("BLOCKQUOTE_API_KEY"))
+started = client.start_scan("https://example.com", idempotency_key=str(uuid.uuid4()))
+print(started.data, started.headers.get("Retry-After"))
+# Wait for Retry-After, then read the returned id.
+report = client.get_scan(started.data["id"])
+comparison = client.compare_scans(from_id="BASELINE_ID", to_id="NEW_ID")
+```
+
+Each call returns a `Response` with `data`, `status`, and HTTP `headers`.
+`BlockquoteError` retains `data`, `status`, `headers`, and `retry_after`. Network errors pass through.
+Requests time out after 30 seconds. Set `timeout` in the constructor to change this.
+The client does not retry or poll automatically. Scans can return a cached result or pending status.
+Reuse an idempotency key only when you repeat the same scan request.
+
+Public report reads need no key. Account access uses an optional bearer key from [your account](https://blockquote.io/account).
+Keys require Pro or Agency. Unattended scan creation can require a paid key with the `scan` scope.
+Human verification still applies where required. Pass `turnstile_token` when available; the SDK does not obtain or bypass verification.
+Pass `refresh=True` to request a fresh scan with account authentication. Scan quotas still apply.
+Read access and comparison output follow your account plan.
+
+See the [API reference](https://blockquote.io/api/docs) and [OpenAPI document](https://blockquote.io/api/v1/openapi.json).
+
+Run tests from this package directory:
+
+```sh
+python3 -m unittest discover -s tests
+```

blockquote_agents-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+blockquote_agents/__init__.py,sha256=2IgHidlc5tfOFRRj3lkaUvNwQ8vz-sawhH7eUts9OnU,3314
+blockquote_agents-0.1.0.dist-info/licenses/LICENSE,sha256=Mhw__VbkCFuYx-tEHWJetFfCiqZ32FhZFflFskKDfic,1070
+blockquote_agents-0.1.0.dist-info/METADATA,sha256=Biahmag7AunrYt85Iw3cin9Z2BHaQPPcXVC1T2s6QXU,2177
+blockquote_agents-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+blockquote_agents-0.1.0.dist-info/top_level.txt,sha256=pPck6FKiGj-ONQ26c398t0Bhbo9RAaIkkxKOA_iBmgY,18
+blockquote_agents-0.1.0.dist-info/RECORD,,

blockquote_agents-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blockquote_agents-0.1.0.dist-info/licenses/LICENSE

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

blockquote_agents-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+blockquote_agents