serqo 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- serqo/__init__.py +6 -0
- serqo/client.py +94 -0
- serqo-0.1.0.dist-info/METADATA +94 -0
- serqo-0.1.0.dist-info/RECORD +7 -0
- serqo-0.1.0.dist-info/WHEEL +5 -0
- serqo-0.1.0.dist-info/licenses/LICENSE +21 -0
- serqo-0.1.0.dist-info/top_level.txt +1 -0
serqo/__init__.py
ADDED
serqo/client.py
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
"""Small, dependency-free HTTP client for the public Serqo API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from typing import Any
|
|
7
|
+
from urllib.error import HTTPError, URLError
|
|
8
|
+
from urllib.request import Request, urlopen
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class SerqoError(Exception):
|
|
12
|
+
"""API error with HTTP status and structured Serqo error fields."""
|
|
13
|
+
|
|
14
|
+
def __init__(self, status: int, body: dict[str, Any], request_id: str | None = None):
|
|
15
|
+
self.status = status
|
|
16
|
+
self.code = str(body.get("code", "UNKNOWN_ERROR"))
|
|
17
|
+
self.request_id = request_id
|
|
18
|
+
self.retryable = bool(body.get("retryable", False))
|
|
19
|
+
self.retry_after_ms = body.get("retryAfterMs")
|
|
20
|
+
self.details = body.get("details")
|
|
21
|
+
super().__init__(str(body.get("message") or f"Serqo API request failed with HTTP {status}"))
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class Serqo:
|
|
25
|
+
"""Client for Serqo search and account endpoints.
|
|
26
|
+
|
|
27
|
+
Args:
|
|
28
|
+
api_key: Secret API key. Keep it on a trusted server.
|
|
29
|
+
base_url: API origin, defaulting to ``https://api.serqo.io``.
|
|
30
|
+
timeout: Per-request timeout in seconds (default 60).
|
|
31
|
+
|
|
32
|
+
Search calls are not retried automatically because successful searches may
|
|
33
|
+
consume credits. Use an idempotency key when retrying identical parameters.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
def __init__(self, api_key: str, base_url: str = "https://api.serqo.io", timeout: float = 60):
|
|
37
|
+
if not api_key.strip():
|
|
38
|
+
raise ValueError("api_key is required")
|
|
39
|
+
self._api_key = api_key
|
|
40
|
+
self._base_url = base_url.rstrip("/")
|
|
41
|
+
self._timeout = timeout
|
|
42
|
+
|
|
43
|
+
def search(self, query: dict[str, Any], *, idempotency_key: str | None = None) -> dict[str, Any]:
|
|
44
|
+
"""Run one search with a JSON body and return the full API envelope."""
|
|
45
|
+
headers = {"x-api-key": self._api_key}
|
|
46
|
+
if idempotency_key:
|
|
47
|
+
headers["Idempotency-Key"] = idempotency_key
|
|
48
|
+
return self._request("POST", "/v1/search", body=query, headers=headers)
|
|
49
|
+
|
|
50
|
+
def engines(self) -> dict[str, Any]:
|
|
51
|
+
"""Return the current engines and supported search types."""
|
|
52
|
+
return self._request("GET", "/v1/engines")
|
|
53
|
+
|
|
54
|
+
def me(self) -> dict[str, Any]:
|
|
55
|
+
"""Return account and API key identifiers associated with this key."""
|
|
56
|
+
return self._request("GET", "/v1/me")
|
|
57
|
+
|
|
58
|
+
def health(self) -> dict[str, Any]:
|
|
59
|
+
"""Check whether the product API responds; no API key is sent."""
|
|
60
|
+
return self._request("GET", "/v1/health", authenticated=False)
|
|
61
|
+
|
|
62
|
+
def _request(
|
|
63
|
+
self,
|
|
64
|
+
method: str,
|
|
65
|
+
path: str,
|
|
66
|
+
*,
|
|
67
|
+
body: dict[str, Any] | None = None,
|
|
68
|
+
headers: dict[str, str] | None = None,
|
|
69
|
+
authenticated: bool = True,
|
|
70
|
+
) -> dict[str, Any]:
|
|
71
|
+
request_headers = {"Accept": "application/json", **(headers or {})}
|
|
72
|
+
if authenticated:
|
|
73
|
+
request_headers["x-api-key"] = self._api_key
|
|
74
|
+
data = None
|
|
75
|
+
if body is not None:
|
|
76
|
+
data = json.dumps(body).encode("utf-8")
|
|
77
|
+
request_headers["Content-Type"] = "application/json"
|
|
78
|
+
request = Request(f"{self._base_url}{path}", data=data, headers=request_headers, method=method)
|
|
79
|
+
try:
|
|
80
|
+
with urlopen(request, timeout=self._timeout) as response:
|
|
81
|
+
payload = json.loads(response.read().decode("utf-8"))
|
|
82
|
+
if not isinstance(payload, dict) or payload.get("success") is not True:
|
|
83
|
+
raise SerqoError(response.status, {"code": "INVALID_RESPONSE", "message": "Serqo API returned an invalid response"}, response.headers.get("x-request-id"))
|
|
84
|
+
return payload
|
|
85
|
+
except HTTPError as error:
|
|
86
|
+
try:
|
|
87
|
+
payload = json.loads(error.read().decode("utf-8"))
|
|
88
|
+
except (UnicodeDecodeError, json.JSONDecodeError):
|
|
89
|
+
payload = {}
|
|
90
|
+
body_error = payload.get("error", {}) if isinstance(payload, dict) else {}
|
|
91
|
+
request_id = payload.get("requestId", error.headers.get("x-request-id")) if isinstance(payload, dict) else error.headers.get("x-request-id")
|
|
92
|
+
raise SerqoError(error.code, body_error if isinstance(body_error, dict) else {}, request_id) from error
|
|
93
|
+
except URLError as error:
|
|
94
|
+
raise ConnectionError(f"Could not reach Serqo API: {error.reason}") from error
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: serqo
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Official Python client for the Serqo Search API
|
|
5
|
+
Author: Serqo
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://serqo.io
|
|
8
|
+
Project-URL: Documentation, https://github.com/serqo-io/serqo-python#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/serqo-io/serqo-python
|
|
10
|
+
Project-URL: Issues, https://github.com/serqo-io/serqo-python/issues
|
|
11
|
+
Keywords: serp,serp-api,search-api,google-search,bing-search
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Dynamic: license-file
|
|
22
|
+
|
|
23
|
+
# Serqo Python SDK
|
|
24
|
+
|
|
25
|
+
Official Python client for the Serqo Search API. Requires Python 3.10 or later and uses only the standard library.
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
pip install serqo
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import os
|
|
37
|
+
from serqo import Serqo
|
|
38
|
+
|
|
39
|
+
client = Serqo(api_key=os.environ["SERQO_API_KEY"])
|
|
40
|
+
response = client.search({
|
|
41
|
+
"q": "espresso machines",
|
|
42
|
+
"engine": "google",
|
|
43
|
+
"type": "web",
|
|
44
|
+
"gl": "us",
|
|
45
|
+
"hl": "en",
|
|
46
|
+
})
|
|
47
|
+
|
|
48
|
+
print(response["data"]["results"])
|
|
49
|
+
print("Request ID:", response["requestId"])
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Keep the API key in a server-side environment variable. The client returns the full response envelope as dictionaries and uses only Python's standard library.
|
|
53
|
+
|
|
54
|
+
## Configure the client
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from serqo import Serqo
|
|
58
|
+
|
|
59
|
+
client = Serqo(
|
|
60
|
+
api_key="your-api-key",
|
|
61
|
+
base_url="https://api.serqo.io",
|
|
62
|
+
timeout=30,
|
|
63
|
+
)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`base_url` and `timeout` are optional. The default timeout is 60 seconds. Do not expose the API key in browser code or commit it to source control.
|
|
67
|
+
|
|
68
|
+
## Methods
|
|
69
|
+
|
|
70
|
+
- `search(query, idempotency_key=None)` sends `POST /v1/search`.
|
|
71
|
+
- `engines()` returns the supported engines and search types.
|
|
72
|
+
- `me()` returns account and API key identifiers.
|
|
73
|
+
- `health()` checks the product API without sending an API key.
|
|
74
|
+
|
|
75
|
+
Read results from `response["data"]["results"]`. For pagination, use `response["data"]["pagination"]["nextStart"]`. See the [API reference](https://github.com/serqo-io/serqo-python/blob/main/API.md) for search parameters, response fields, and pagination behavior.
|
|
76
|
+
|
|
77
|
+
## Errors and retries
|
|
78
|
+
|
|
79
|
+
API errors raise `SerqoError`. It exposes `status`, `code`, `request_id`, `retryable`, `retry_after_ms`, and `details`:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from serqo import SerqoError
|
|
83
|
+
|
|
84
|
+
try:
|
|
85
|
+
response = client.search({"q": "coffee shops", "engine": "google", "type": "maps"})
|
|
86
|
+
except SerqoError as error:
|
|
87
|
+
print(error.status, error.code, error.request_id)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Connection failures raise `ConnectionError`; request timeouts raise `TimeoutError`. The SDK does not retry searches automatically. When retrying an uncertain request, reuse the same `idempotency_key` with the same query within 24 hours.
|
|
91
|
+
|
|
92
|
+
## Publish a release
|
|
93
|
+
|
|
94
|
+
Releases are published from GitHub Actions using PyPI Trusted Publishing. Configure a pending publisher on PyPI for owner `serqo-io`, repository `serqo-python`, workflow `release.yml`, and environment `pypi`. Then push a tag matching the version in `pyproject.toml`, such as `v0.1.0`. The workflow builds and checks both distributions before publishing them. See the [PyPI publishing guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
serqo/__init__.py,sha256=rkRLk62ySlrGzgj2MxkYh8bMKwO4az4baxbTKpjQtiY,142
|
|
2
|
+
serqo/client.py,sha256=vIk4e3lZvXr6Zq5b8oPKcL4_6-rp5byn2Itzt4zpUmI,4251
|
|
3
|
+
serqo-0.1.0.dist-info/licenses/LICENSE,sha256=n67QNz2CijVgCZuKhkDbXKkrCTEDpNUyP0VuV2KgqXs,1062
|
|
4
|
+
serqo-0.1.0.dist-info/METADATA,sha256=19swNijKTmpxioZH4sJtGtrlWu41hZIYcBNH22d-C9g,3454
|
|
5
|
+
serqo-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
6
|
+
serqo-0.1.0.dist-info/top_level.txt,sha256=Qsi_Tn57x-XqXjkLczElak7pG0d_1NZ_9cmvXvqaHgA,6
|
|
7
|
+
serqo-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Serqo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
serqo
|