serqo 0.1.0__tar.gz

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-0.1.0/LICENSE ADDED
@@ -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.
serqo-0.1.0/PKG-INFO ADDED
@@ -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/).
serqo-0.1.0/README.md ADDED
@@ -0,0 +1,72 @@
1
+ # Serqo Python SDK
2
+
3
+ Official Python client for the Serqo Search API. Requires Python 3.10 or later and uses only the standard library.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ pip install serqo
9
+ ```
10
+
11
+ ## Quick start
12
+
13
+ ```python
14
+ import os
15
+ from serqo import Serqo
16
+
17
+ client = Serqo(api_key=os.environ["SERQO_API_KEY"])
18
+ response = client.search({
19
+ "q": "espresso machines",
20
+ "engine": "google",
21
+ "type": "web",
22
+ "gl": "us",
23
+ "hl": "en",
24
+ })
25
+
26
+ print(response["data"]["results"])
27
+ print("Request ID:", response["requestId"])
28
+ ```
29
+
30
+ 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.
31
+
32
+ ## Configure the client
33
+
34
+ ```python
35
+ from serqo import Serqo
36
+
37
+ client = Serqo(
38
+ api_key="your-api-key",
39
+ base_url="https://api.serqo.io",
40
+ timeout=30,
41
+ )
42
+ ```
43
+
44
+ `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.
45
+
46
+ ## Methods
47
+
48
+ - `search(query, idempotency_key=None)` sends `POST /v1/search`.
49
+ - `engines()` returns the supported engines and search types.
50
+ - `me()` returns account and API key identifiers.
51
+ - `health()` checks the product API without sending an API key.
52
+
53
+ 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.
54
+
55
+ ## Errors and retries
56
+
57
+ API errors raise `SerqoError`. It exposes `status`, `code`, `request_id`, `retryable`, `retry_after_ms`, and `details`:
58
+
59
+ ```python
60
+ from serqo import SerqoError
61
+
62
+ try:
63
+ response = client.search({"q": "coffee shops", "engine": "google", "type": "maps"})
64
+ except SerqoError as error:
65
+ print(error.status, error.code, error.request_id)
66
+ ```
67
+
68
+ 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.
69
+
70
+ ## Publish a release
71
+
72
+ 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,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "serqo"
7
+ version = "0.1.0"
8
+ description = "Official Python client for the Serqo Search API"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Serqo" }]
14
+ keywords = ["serp", "serp-api", "search-api", "google-search", "bing-search"]
15
+ classifiers = [
16
+ "Intended Audience :: Developers",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.10",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ ]
23
+
24
+ [project.urls]
25
+ Homepage = "https://serqo.io"
26
+ Documentation = "https://github.com/serqo-io/serqo-python#readme"
27
+ Repository = "https://github.com/serqo-io/serqo-python"
28
+ Issues = "https://github.com/serqo-io/serqo-python/issues"
29
+
30
+ [tool.setuptools]
31
+ package-dir = { "" = "src" }
32
+
33
+ [tool.setuptools.packages.find]
34
+ where = ["src"]
serqo-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,6 @@
1
+ """Python client for the Serqo Search API."""
2
+
3
+ from .client import Serqo, SerqoError
4
+
5
+ __all__ = ["Serqo", "SerqoError"]
6
+ __version__ = "0.1.0"
@@ -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,9 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/serqo/__init__.py
5
+ src/serqo/client.py
6
+ src/serqo.egg-info/PKG-INFO
7
+ src/serqo.egg-info/SOURCES.txt
8
+ src/serqo.egg-info/dependency_links.txt
9
+ src/serqo.egg-info/top_level.txt
@@ -0,0 +1 @@
1
+ serqo