serpbit 0.1.0__tar.gz

serpbit-0.1.0/LICENSE

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

serpbit-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: serpbit
+Version: 0.1.0
+Summary: Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data: the Serpbit API client.
+Author-email: Serpbit <support@serpbit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://serpbit.com
+Project-URL: Documentation, https://serpbit.com/docs/#sdks
+Project-URL: Changelog, https://serpbit.com/changelog/
+Keywords: serp,google search api,serp api,web search,ai agents,rag
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# serpbit
+
+Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data, from
+[Serpbit](https://serpbit.com). No dependencies: the standard library only, Python 3.9+.
+
+```sh
+pip install serpbit
+```
+
+```python
+from serpbit import Serpbit
+
+sb = Serpbit()  # reads SERPBIT_API_KEY; make a key at https://app.serpbit.com/keys
+
+answer = sb.search("espresso grinder", gl="de", hl="de", pages=2)
+for r in answer["organic"]:
+    print(r["position"], r["title"], r["url"])
+
+# The first three results' pages, as Markdown text: 1 credit a page read.
+answer = sb.search("how to descale an espresso machine", content=3)
+print(answer["organic"][0]["content"]["text"][:500])
+
+# Markdown instead of JSON, for a language model's context.
+print(sb.news("wildfire", sort="date", output="md"))
+```
+
+Every door of the API has a method: `search`, `news`, `shopping`, `shopping_product`, `images`, `videos`, `maps`,
+`autocomplete`, `ai_mode`. Keyword arguments are the door's parameters, as the [docs](https://serpbit.com/docs/)
+name them:
+- `True` is sent as `true`;
+- `None` and `False` are left out;
+- a list is joined with commas.
+
+A method returns the API's JSON as a dict, or a `str` with `output="md"`. `sb.last_request_id` and
+`sb.last_credits` give the last answer's id and the credits it spent.
+
+## Errors and retries
+
+A failed call raises a `SerpbitError`. The subclasses are:
+- `BadRequestError` (400);
+- `AuthenticationError` (401);
+- `InsufficientCreditsError` (402);
+- `RateLimitError` (429, with `retry_after`);
+- `APIError` (5xx);
+- `APIConnectionError`.
+
+Each carries `status`, `code` and `request_id`. Quote the `request_id` to support.
+
+Calls are retried twice on 429 and 5xx (set with `max_retries`), waiting as `Retry-After` says. Every attempt of one
+call carries the same `Idempotency-Key`, so an answer lost on the way is given back free instead of being billed
+twice. You can pass your own with `idempotency_key=`.
+
+## Batches
+
+```python
+b = sb.batch([{"path": "/v1/search", "params": {"q": kw, "gl": "us"}, "id": kw} for kw in keywords],
+             webhook="https://example.com/serpbit")
+sb.get_batch(b["id"])                     # status, and each call's
+sb.batch_results(b["id"], offset=0)       # the answers, 100 at a time, for a day after it ends
+
+# In your webhook: check the event is Serpbit's before you trust it.
+from serpbit import verify_webhook
+ok = verify_webhook(request.body, request.headers["Serpbit-Signature"], api_key)
+```

serpbit-0.1.0/README.md

@@ -0,0 +1,64 @@
+# serpbit
+
+Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data, from
+[Serpbit](https://serpbit.com). No dependencies: the standard library only, Python 3.9+.
+
+```sh
+pip install serpbit
+```
+
+```python
+from serpbit import Serpbit
+
+sb = Serpbit()  # reads SERPBIT_API_KEY; make a key at https://app.serpbit.com/keys
+
+answer = sb.search("espresso grinder", gl="de", hl="de", pages=2)
+for r in answer["organic"]:
+    print(r["position"], r["title"], r["url"])
+
+# The first three results' pages, as Markdown text: 1 credit a page read.
+answer = sb.search("how to descale an espresso machine", content=3)
+print(answer["organic"][0]["content"]["text"][:500])
+
+# Markdown instead of JSON, for a language model's context.
+print(sb.news("wildfire", sort="date", output="md"))
+```
+
+Every door of the API has a method: `search`, `news`, `shopping`, `shopping_product`, `images`, `videos`, `maps`,
+`autocomplete`, `ai_mode`. Keyword arguments are the door's parameters, as the [docs](https://serpbit.com/docs/)
+name them:
+- `True` is sent as `true`;
+- `None` and `False` are left out;
+- a list is joined with commas.
+
+A method returns the API's JSON as a dict, or a `str` with `output="md"`. `sb.last_request_id` and
+`sb.last_credits` give the last answer's id and the credits it spent.
+
+## Errors and retries
+
+A failed call raises a `SerpbitError`. The subclasses are:
+- `BadRequestError` (400);
+- `AuthenticationError` (401);
+- `InsufficientCreditsError` (402);
+- `RateLimitError` (429, with `retry_after`);
+- `APIError` (5xx);
+- `APIConnectionError`.
+
+Each carries `status`, `code` and `request_id`. Quote the `request_id` to support.
+
+Calls are retried twice on 429 and 5xx (set with `max_retries`), waiting as `Retry-After` says. Every attempt of one
+call carries the same `Idempotency-Key`, so an answer lost on the way is given back free instead of being billed
+twice. You can pass your own with `idempotency_key=`.
+
+## Batches
+
+```python
+b = sb.batch([{"path": "/v1/search", "params": {"q": kw, "gl": "us"}, "id": kw} for kw in keywords],
+             webhook="https://example.com/serpbit")
+sb.get_batch(b["id"])                     # status, and each call's
+sb.batch_results(b["id"], offset=0)       # the answers, 100 at a time, for a day after it ends
+
+# In your webhook: check the event is Serpbit's before you trust it.
+from serpbit import verify_webhook
+ok = verify_webhook(request.body, request.headers["Serpbit-Signature"], api_key)
+```

serpbit-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serpbit"
+version = "0.1.0"
+description = "Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data: the Serpbit API client."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Serpbit", email = "support@serpbit.com" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["serp", "google search api", "serp api", "web search", "ai agents", "rag"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://serpbit.com"
+Documentation = "https://serpbit.com/docs/#sdks"
+Changelog = "https://serpbit.com/changelog/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+serpbit = ["py.typed"]

serpbit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

serpbit-0.1.0/src/serpbit/__init__.py

@@ -0,0 +1,26 @@
+"""Serpbit: Google results as data. A small client for https://api.serpbit.com, on the standard library alone."""
+
+from ._client import VERSION as __version__
+from ._client import Serpbit
+from ._webhook import verify_webhook
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    InsufficientCreditsError,
+    RateLimitError,
+    SerpbitError,
+)
+
+__all__ = [
+    "Serpbit",
+    "verify_webhook",
+    "SerpbitError",
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+]

serpbit-0.1.0/src/serpbit/_client.py

@@ -0,0 +1,201 @@
+"""The client: one method per API door, each a GET whose keyword arguments are the door's parameters."""
+
+import json
+import os
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, List, Optional, Union
+
+from ._errors import APIConnectionError, SerpbitError, error_for
+
+DEFAULT_BASE_URL = "https://api.serpbit.com"
+VERSION = "0.1.0"
+
+# A call is retried on these: the rate limit (after Retry-After), Google giving no page in time, our side failing.
+_RETRY = {429, 500, 502, 503, 504}
+
+Answer = Union[Dict[str, Any], str]
+
+
+class Serpbit:
+    """A Serpbit client.
+
+    >>> from serpbit import Serpbit
+    >>> sb = Serpbit()  # the key from SERPBIT_API_KEY
+    >>> answer = sb.search("espresso grinder", gl="de", pages=2, content=3)
+    >>> answer["organic"][0]["title"]
+
+    Every method returns the API's JSON as a dict, or Markdown as a str with output="md". A failed call raises a
+    SerpbitError. A retried call carries one Idempotency-Key, so a call that was answered but whose answer was lost
+    on the way is given back free rather than asked and billed again.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 90.0,
+        max_retries: int = 2,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("SERPBIT_API_KEY", "")
+        if not self.api_key:
+            raise SerpbitError("no API key: pass api_key or set SERPBIT_API_KEY (keys are made at https://app.serpbit.com/keys)")
+        self.base_url = (base_url or os.environ.get("SERPBIT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        # The last answer's id and credits, from its headers: a Markdown answer has no JSON to carry them.
+        self.last_request_id: Optional[str] = None
+        self.last_credits: Optional[int] = None
+
+    # --- the doors -------------------------------------------------------------------------------------------------
+
+    def search(self, q: Optional[str] = None, **params: Any) -> Answer:
+        """Google's results page (/v1/search). url= takes a Google results address instead of q."""
+        return self.request("/v1/search", q=q, **params)
+
+    def news(self, q: str, **params: Any) -> Answer:
+        """Google's News tab (/v1/news)."""
+        return self.request("/v1/news", q=q, **params)
+
+    def shopping(self, q: str, **params: Any) -> Answer:
+        """Google's Shopping tab (/v1/shopping)."""
+        return self.request("/v1/shopping", q=q, **params)
+
+    def shopping_product(self, product_id: Optional[str] = None, **params: Any) -> Answer:
+        """One product and every store's offer (/v1/shopping/product)."""
+        return self.request("/v1/shopping/product", product_id=product_id, **params)
+
+    def images(self, q: str, **params: Any) -> Answer:
+        """Google's Images tab (/v1/images)."""
+        return self.request("/v1/images", q=q, **params)
+
+    def videos(self, q: str, **params: Any) -> Answer:
+        """Google's Videos tab (/v1/videos)."""
+        return self.request("/v1/videos", q=q, **params)
+
+    def maps(self, q: str, **params: Any) -> Answer:
+        """Places as Google Maps lists them (/v1/maps)."""
+        return self.request("/v1/maps", q=q, **params)
+
+    def autocomplete(self, q: str, **params: Any) -> Answer:
+        """Google's search-box suggestions (/v1/autocomplete)."""
+        return self.request("/v1/autocomplete", q=q, **params)
+
+    def ai_mode(self, q: str, **params: Any) -> Answer:
+        """Google's AI Mode answer with its sources (/v1/ai-mode)."""
+        return self.request("/v1/ai-mode", q=q, **params)
+
+    # --- batches ---------------------------------------------------------------------------------------------------
+
+    def batch(self, requests: List[Dict[str, Any]], *, webhook: Optional[str] = None,
+              idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """Start a batch of up to 1,000 calls (POST /v1/batches), each {"path": "/v1/search", "params": {...}, "id": ...}.
+
+        The calls run in the background at the key's limits; each answer goes to webhook as it comes (verify it with
+        serpbit.verify_webhook) and stays readable with batch_results for a day after the batch ends.
+        """
+        body: Dict[str, Any] = {"requests": [
+            {**r, "params": {k: v for k, v in (r.get("params") or {}).items() if v is not None and v is not False}}
+            for r in requests]}
+        if webhook:
+            body["webhook"] = webhook
+        return self.request("/v1/batches", method="POST", json_body=body, idempotency_key=idempotency_key)
+
+    def get_batch(self, batch_id: str) -> Dict[str, Any]:
+        """A batch's state and each call's status (GET /v1/batches/{id})."""
+        return self.request("/v1/batches/" + urllib.parse.quote(batch_id, safe=""))
+
+    def batch_results(self, batch_id: str, *, offset: int = 0, limit: int = 100) -> Dict[str, Any]:
+        """A batch's answers, limit (at most 100) from offset (GET /v1/batches/{id}/results)."""
+        return self.request("/v1/batches/" + urllib.parse.quote(batch_id, safe="") + "/results", offset=offset, limit=limit)
+
+    # --- the call --------------------------------------------------------------------------------------------------
+
+    def request(self, path: str, *, method: str = "GET", json_body: Any = None, idempotency_key: Optional[str] = None,
+                **params: Any) -> Answer:
+        """Call path with params. True is sent as true; None and False are left out; a list is joined by commas."""
+        query = {k: _value(v) for k, v in params.items() if v is not None and v is not False}
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        key = idempotency_key or (uuid.uuid4().hex if self.max_retries else None)
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "Accept": "application/json, text/markdown",
+            "User-Agent": "serpbit-python/" + VERSION,
+        }
+        if key:
+            headers["Idempotency-Key"] = key
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode()
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            try:
+                req = urllib.request.Request(url, data=data, headers=headers, method=method)
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    body = resp.read()
+                    self.last_request_id = resp.headers.get("X-Request-Id")
+                    self.last_credits = _int(resp.headers.get("X-Credits"))
+                    if resp.headers.get_content_type() == "application/json":
+                        return json.loads(body)
+                    return body.decode("utf-8")
+            except urllib.error.HTTPError as e:
+                body = e.read()
+                retry_after = _float(e.headers.get("Retry-After"))
+                if e.code in _RETRY and attempt < self.max_retries:
+                    time.sleep(_backoff(attempt, retry_after))
+                    attempt += 1
+                    continue
+                raise _refusal(e.code, body, e.headers.get("X-Request-Id"), retry_after) from None
+            except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt, None))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"could not reach {self.base_url}: {getattr(e, 'reason', e)}") from None
+
+
+def _value(v: Any) -> str:
+    if v is True:
+        return "true"
+    if isinstance(v, (list, tuple)):
+        return ",".join(str(x) for x in v)
+    return str(v)
+
+
+def _int(s: Optional[str]) -> Optional[int]:
+    try:
+        return int(s) if s is not None else None
+    except ValueError:
+        return None
+
+
+def _float(s: Optional[str]) -> Optional[float]:
+    try:
+        return float(s) if s is not None else None
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int, retry_after: Optional[float]) -> float:
+    if retry_after is not None:
+        return min(retry_after, 60.0)
+    return min(0.5 * 2**attempt, 8.0) * (0.75 + random.random() / 2)
+
+
+def _refusal(status: int, body: bytes, request_id: Optional[str], retry_after: Optional[float]) -> SerpbitError:
+    try:
+        data = json.loads(body)
+    except ValueError:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    message = data.get("message") or f"the API answered {status}"
+    return error_for(status, message, code=data.get("error"), request_id=data.get("request_id") or request_id,
+                     body=data, retry_after=retry_after)

serpbit-0.1.0/src/serpbit/_errors.py

@@ -0,0 +1,75 @@
+"""Errors, one class a kind of refusal: catch SerpbitError for all of them."""
+
+from typing import Any, Mapping, Optional
+
+
+class SerpbitError(Exception):
+    """A call that did not answer. status, code and request_id are the API's (request_id is what support asks for)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        body: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status:
+            parts.append(f"status {self.status}")
+        if self.code:
+            parts.append(self.code)
+        if self.request_id:
+            parts.append(f"request_id {self.request_id}")
+        return " · ".join(parts)
+
+
+class BadRequestError(SerpbitError):
+    """400: a parameter the API does not take, or a value out of its range."""
+
+
+class AuthenticationError(SerpbitError):
+    """401: no key, or a key that is revoked or unknown."""
+
+
+class InsufficientCreditsError(SerpbitError):
+    """402: the account has not the credits this call needs."""
+
+
+class RateLimitError(SerpbitError):
+    """429: over the key's requests a minute or at once. retry_after is the seconds the API asked to wait."""
+
+    def __init__(self, message: str, *, retry_after: Optional[float] = None, **kw: Any) -> None:
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class APIError(SerpbitError):
+    """5xx: Google gave no page within the call's attempts and time (503), or something failed on our side."""
+
+
+class APIConnectionError(SerpbitError):
+    """The API could not be reached, or did not answer in time."""
+
+
+def error_for(status: int, message: str, retry_after: Optional[float] = None, **kw: Any) -> SerpbitError:
+    if status == 400:
+        return BadRequestError(message, status=status, **kw)
+    if status == 401:
+        return AuthenticationError(message, status=status, **kw)
+    if status == 402:
+        return InsufficientCreditsError(message, status=status, **kw)
+    if status == 429:
+        return RateLimitError(message, status=status, retry_after=retry_after, **kw)
+    if status >= 500:
+        return APIError(message, status=status, **kw)
+    return SerpbitError(message, status=status, **kw)

serpbit-0.1.0/src/serpbit/_webhook.py

@@ -0,0 +1,24 @@
+"""Webhooks: a batch's events are signed with the API key that started it."""
+
+import hashlib
+import hmac
+import time
+from typing import Optional, Union
+
+
+def verify_webhook(body: Union[bytes, str], signature: Optional[str], api_key: str, *, tolerance: float = 300) -> bool:
+    """True when a webhook's body is Serpbit's, sent within tolerance seconds.
+
+    signature is the Serpbit-Signature header ("t=<unix>,v1=<hex>"); body is the request's raw body, as received.
+    """
+    if not signature or not api_key:
+        return False
+    parts = dict(p.split("=", 1) for p in signature.split(",") if "=" in p)
+    ts, sig = parts.get("t", ""), parts.get("v1", "")
+    if not ts.isdigit() or not sig:
+        return False
+    if tolerance and abs(time.time() - int(ts)) > tolerance:
+        return False
+    raw = body.encode() if isinstance(body, str) else body
+    want = hmac.new(api_key.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(want, sig)

serpbit-0.1.0/src/serpbit.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: serpbit
+Version: 0.1.0
+Summary: Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data: the Serpbit API client.
+Author-email: Serpbit <support@serpbit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://serpbit.com
+Project-URL: Documentation, https://serpbit.com/docs/#sdks
+Project-URL: Changelog, https://serpbit.com/changelog/
+Keywords: serp,google search api,serp api,web search,ai agents,rag
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# serpbit
+
+Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data, from
+[Serpbit](https://serpbit.com). No dependencies: the standard library only, Python 3.9+.
+
+```sh
+pip install serpbit
+```
+
+```python
+from serpbit import Serpbit
+
+sb = Serpbit()  # reads SERPBIT_API_KEY; make a key at https://app.serpbit.com/keys
+
+answer = sb.search("espresso grinder", gl="de", hl="de", pages=2)
+for r in answer["organic"]:
+    print(r["position"], r["title"], r["url"])
+
+# The first three results' pages, as Markdown text: 1 credit a page read.
+answer = sb.search("how to descale an espresso machine", content=3)
+print(answer["organic"][0]["content"]["text"][:500])
+
+# Markdown instead of JSON, for a language model's context.
+print(sb.news("wildfire", sort="date", output="md"))
+```
+
+Every door of the API has a method: `search`, `news`, `shopping`, `shopping_product`, `images`, `videos`, `maps`,
+`autocomplete`, `ai_mode`. Keyword arguments are the door's parameters, as the [docs](https://serpbit.com/docs/)
+name them:
+- `True` is sent as `true`;
+- `None` and `False` are left out;
+- a list is joined with commas.
+
+A method returns the API's JSON as a dict, or a `str` with `output="md"`. `sb.last_request_id` and
+`sb.last_credits` give the last answer's id and the credits it spent.
+
+## Errors and retries
+
+A failed call raises a `SerpbitError`. The subclasses are:
+- `BadRequestError` (400);
+- `AuthenticationError` (401);
+- `InsufficientCreditsError` (402);
+- `RateLimitError` (429, with `retry_after`);
+- `APIError` (5xx);
+- `APIConnectionError`.
+
+Each carries `status`, `code` and `request_id`. Quote the `request_id` to support.
+
+Calls are retried twice on 429 and 5xx (set with `max_retries`), waiting as `Retry-After` says. Every attempt of one
+call carries the same `Idempotency-Key`, so an answer lost on the way is given back free instead of being billed
+twice. You can pass your own with `idempotency_key=`.
+
+## Batches
+
+```python
+b = sb.batch([{"path": "/v1/search", "params": {"q": kw, "gl": "us"}, "id": kw} for kw in keywords],
+             webhook="https://example.com/serpbit")
+sb.get_batch(b["id"])                     # status, and each call's
+sb.batch_results(b["id"], offset=0)       # the answers, 100 at a time, for a day after it ends
+
+# In your webhook: check the event is Serpbit's before you trust it.
+from serpbit import verify_webhook
+ok = verify_webhook(request.body, request.headers["Serpbit-Signature"], api_key)
+```

serpbit-0.1.0/src/serpbit.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/serpbit/__init__.py
+src/serpbit/_client.py
+src/serpbit/_errors.py
+src/serpbit/_webhook.py
+src/serpbit/py.typed
+src/serpbit.egg-info/PKG-INFO
+src/serpbit.egg-info/SOURCES.txt
+src/serpbit.egg-info/dependency_links.txt
+src/serpbit.egg-info/top_level.txt
+tests/test_client.py

serpbit-0.1.0/src/serpbit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

serpbit-0.1.0/src/serpbit.egg-info/top_level.txt

@@ -0,0 +1 @@
+serpbit

serpbit-0.1.0/tests/test_client.py

@@ -0,0 +1,167 @@
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+import serpbit
+from serpbit import Serpbit
+
+
+class FakeAPI(BaseHTTPRequestHandler):
+    """Answers as the API does; seen keeps each request, script the statuses to give before the answer."""
+
+    seen = []
+    script = []
+
+    def do_GET(self):  # noqa: N802
+        u = urlparse(self.path)
+        FakeAPI.seen.append({"path": u.path, "query": {k: v[0] for k, v in parse_qs(u.query).items()},
+                             "auth": self.headers.get("Authorization"), "idem": self.headers.get("Idempotency-Key"),
+                             "ua": self.headers.get("User-Agent")})
+        if FakeAPI.script:
+            status, headers = FakeAPI.script.pop(0)
+            self.send(status, {"error": "rate_limited" if status == 429 else "unavailable", "message": "later",
+                               "request_id": "r-err"}, headers)
+            return
+        q = FakeAPI.seen[-1]["query"]
+        if q.get("q") == "broke":
+            self.send(402, {"error": "out_of_credits", "message": "no credits left", "request_id": "r402"})
+            return
+        if q.get("output") == "md":
+            self.send(200, "# Google results", {"X-Credits": "1", "X-Request-Id": "rmd"}, "text/markdown; charset=utf-8")
+            return
+        self.send(200, {"request_id": "r1", "organic": [{"position": 1, "page": 1, "title": "T"}], "meta": {"credits": 1}},
+                  {"X-Credits": "1", "X-Request-Id": "r1"})
+
+    def do_POST(self):  # noqa: N802
+        n = int(self.headers.get("Content-Length") or 0)
+        FakeAPI.seen.append({"path": self.path, "method": "POST", "body": json.loads(self.rfile.read(n)),
+                             "idem": self.headers.get("Idempotency-Key"), "ctype": self.headers.get("Content-Type")})
+        self.send(202, {"id": "bat_1", "status": "running", "total": 1})
+
+    def send(self, status, body, headers=None, ctype="application/json"):
+        raw = (body if isinstance(body, str) else json.dumps(body)).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", ctype)
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def log_message(self, *a):
+        pass
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.srv = ThreadingHTTPServer(("127.0.0.1", 0), FakeAPI)
+        threading.Thread(target=cls.srv.serve_forever, daemon=True).start()
+        cls.base = "http://127.0.0.1:%d" % cls.srv.server_address[1]
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.srv.shutdown()
+
+    def setUp(self):
+        FakeAPI.seen, FakeAPI.script = [], []
+        self.sb = Serpbit("sb_live_test", base_url=self.base, max_retries=2)
+
+    def test_a_search_sends_its_parameters_and_reads_the_json(self):
+        a = self.sb.search("coffee grinder", gl="de", pages=2, content=True, ai_overview=True, safe=None, html=False,
+                           lr=["lang_de", "lang_en"])
+        self.assertEqual(a["organic"][0]["title"], "T")
+        r = FakeAPI.seen[0]
+        self.assertEqual(r["path"], "/v1/search")
+        self.assertEqual(r["query"], {"q": "coffee grinder", "gl": "de", "pages": "2", "content": "true",
+                                      "ai_overview": "true", "lr": "lang_de,lang_en"})
+        self.assertEqual(r["auth"], "Bearer sb_live_test")
+        self.assertTrue(r["ua"].startswith("serpbit-python/"))
+        self.assertEqual((self.sb.last_request_id, self.sb.last_credits), ("r1", 1))
+
+    def test_each_door_has_its_path(self):
+        for call, path in [(lambda: self.sb.news("x"), "/v1/news"), (lambda: self.sb.shopping("x"), "/v1/shopping"),
+                           (lambda: self.sb.shopping_product("123"), "/v1/shopping/product"),
+                           (lambda: self.sb.images("x"), "/v1/images"), (lambda: self.sb.videos("x"), "/v1/videos"),
+                           (lambda: self.sb.maps("x"), "/v1/maps"), (lambda: self.sb.autocomplete("x"), "/v1/autocomplete"),
+                           (lambda: self.sb.ai_mode("x"), "/v1/ai-mode")]:
+            call()
+            self.assertEqual(FakeAPI.seen[-1]["path"], path)
+        self.assertEqual(FakeAPI.seen[2]["query"], {"product_id": "123"})
+
+    def test_markdown_comes_as_text(self):
+        self.assertEqual(self.sb.search("x", output="md"), "# Google results")
+        self.assertEqual(self.sb.last_request_id, "rmd")
+
+    def test_retries_keep_one_idempotency_key_and_wait_as_asked(self):
+        FakeAPI.script = [(429, {"Retry-After": "0"}), (503, {})]
+        a = self.sb.search("x")
+        self.assertEqual(a["request_id"], "r1")
+        keys = {r["idem"] for r in FakeAPI.seen}
+        self.assertEqual(len(FakeAPI.seen), 3)
+        self.assertEqual(len(keys), 1)
+        self.assertTrue(next(iter(keys)))
+
+    def test_a_refusal_is_its_own_error(self):
+        with self.assertRaises(serpbit.InsufficientCreditsError) as e:
+            self.sb.search("broke")
+        self.assertEqual((e.exception.status, e.exception.code, e.exception.request_id), (402, "out_of_credits", "r402"))
+        FakeAPI.script = [(429, {"Retry-After": "0"})] * 3
+        with self.assertRaises(serpbit.RateLimitError) as e:
+            self.sb.search("x")
+        self.assertEqual(e.exception.retry_after, 0)
+        self.assertIsInstance(e.exception, serpbit.SerpbitError)
+
+    def test_an_unreachable_api(self):
+        sb = Serpbit("k", base_url="http://127.0.0.1:9", max_retries=0, timeout=2)
+        with self.assertRaises(serpbit.APIConnectionError):
+            sb.search("x")
+
+    def test_a_key_is_needed(self):
+        import os
+
+        old = os.environ.pop("SERPBIT_API_KEY", None)
+        try:
+            with self.assertRaises(serpbit.SerpbitError):
+                Serpbit()
+        finally:
+            if old is not None:
+                os.environ["SERPBIT_API_KEY"] = old
+
+
+if __name__ == "__main__":
+    unittest.main()
+
+
+class BatchTest(ClientTest):
+    def test_a_batch_posts_its_calls_and_is_read_back(self):
+        b = self.sb.batch([{"path": "/v1/search", "params": {"q": "x", "pages": 2, "html": False}, "id": "kw-1"}],
+                          webhook="https://example.com/hook", idempotency_key="b-1")
+        self.assertEqual(b["id"], "bat_1")
+        r = FakeAPI.seen[0]
+        self.assertEqual((r["method"], r["path"], r["idem"], r["ctype"]), ("POST", "/v1/batches", "b-1", "application/json"))
+        self.assertEqual(r["body"], {"requests": [{"path": "/v1/search", "params": {"q": "x", "pages": 2}, "id": "kw-1"}],
+                                     "webhook": "https://example.com/hook"})
+        self.sb.get_batch("bat_1")
+        self.sb.batch_results("bat_1", offset=100)
+        self.assertEqual(FakeAPI.seen[1]["path"], "/v1/batches/bat_1")
+        self.assertEqual((FakeAPI.seen[2]["path"], FakeAPI.seen[2]["query"]), ("/v1/batches/bat_1/results",
+                                                                               {"offset": "100", "limit": "100"}))
+
+    def test_a_webhook_is_verified_with_the_key(self):
+        import hashlib
+        import hmac
+        import time
+
+        body = b'{"type":"batch.completed","data":{}}'
+        ts = str(int(time.time()))
+        sig = hmac.new(b"sb_live_test", ts.encode() + b"." + body, hashlib.sha256).hexdigest()
+        header = "t=%s,v1=%s" % (ts, sig)
+        self.assertTrue(serpbit.verify_webhook(body, header, "sb_live_test"))
+        self.assertFalse(serpbit.verify_webhook(body + b" ", header, "sb_live_test"))
+        self.assertFalse(serpbit.verify_webhook(body, header, "another_key"))
+        old = "t=%d,v1=%s" % (int(time.time()) - 3600, sig)
+        self.assertFalse(serpbit.verify_webhook(body, old, "sb_live_test"))
+        self.assertFalse(serpbit.verify_webhook(body, None, "sb_live_test"))