reserp 0.1.0__tar.gz

reserp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: pytest
+
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src
+      - run: python -m build
+      - run: twine check dist/*

reserp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/

reserp-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-08-18
+
+- Initial synchronous and asynchronous Python SDK.
+- Typed search responses and API errors.
+- One-based pagination and raw Google Search URL support.
+- Billing-safe retries and configurable timeouts.
+
+[0.1.0]: https://github.com/reserp-ai/reserp-python/releases/tag/v0.1.0

reserp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Thanks for helping improve the Reserp Python SDK.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Run the validation suite before opening a pull request:
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+python -m build
+twine check dist/*
+```
+
+Keep changes focused on the public SDK and documented API contract. Do not include API keys, account data, or private implementation details.

reserp-0.1.0/LICENSE

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

reserp-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: reserp
+Version: 0.1.0
+Summary: Official Python SDK for the Reserp Google Search API
+Project-URL: Homepage, https://reserp.ai
+Project-URL: Documentation, https://reserp.ai/docs
+Project-URL: Repository, https://github.com/reserp-ai/reserp-python
+Project-URL: Issues, https://github.com/reserp-ai/reserp-python/issues
+Project-URL: Changelog, https://github.com/reserp-ai/reserp-python/blob/main/CHANGELOG.md
+Author-email: Reserp <no-reply@reserp.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,google-search,google-search-api,python,reserp,sdk,search-api,serp,serp-api
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: twine<7,>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://reserp.ai">
+    <img src="https://reserp.ai/icon-512.png" alt="Reserp Google Search API" width="112" height="112">
+  </a>
+</p>
+
+# Reserp Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/reserp.svg)](https://pypi.org/project/reserp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/reserp.svg)](https://pypi.org/project/reserp/)
+[![CI](https://github.com/reserp-ai/reserp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/reserp-ai/reserp-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The official Python SDK for [Reserp](https://reserp.ai), a Google Search API for developers and AI agents.
+
+Retrieve structured Google Search results through one stable JSON schema. Start for free with no credit card required.
+
+[Website](https://reserp.ai) · [API documentation](https://reserp.ai/docs) · [OpenAPI 3.1](https://reserp.ai/openapi.json) · [Pricing](https://reserp.ai/pricing)
+
+## Features
+
+- Synchronous and asynchronous clients built on HTTPX.
+- Typed responses that preserve the complete API response dictionary.
+- One-based pagination plus support for authoritative pagination URLs.
+- Configurable retries and timeouts.
+- Automatic retries only when the API says the request is retryable and was not billed.
+
+## Installation
+
+```bash
+pip install reserp
+```
+
+Python 3.10 or later is required.
+
+## Quick start
+
+```python
+import os
+
+from reserp import Reserp
+
+client = Reserp(api_key=os.environ["RESERP_API_KEY"])
+
+response = client.search(
+    query="best pizza in dubai",
+    gl="ae",
+    hl="en",
+)
+
+for result in response["results"]:
+    print(result.get("text"), result.get("url"))
+```
+
+Create an API key in the [Reserp dashboard](https://reserp.ai/dashboard). Keep API keys on your server; never embed one in browser or mobile code.
+
+The SDK returns the API response as a normal Python dictionary. Result order, nested `children`, pagination, and billing fields remain intact.
+
+## Async client
+
+```python
+import asyncio
+import os
+
+from reserp import AsyncReserp
+
+
+async def main() -> None:
+    async with AsyncReserp(api_key=os.environ["RESERP_API_KEY"]) as client:
+        response = await client.search(
+            query="semiconductor manufacturing",
+            gl="us",
+            hl="en",
+        )
+        print(response["results"])
+
+
+asyncio.run(main())
+```
+
+The synchronous client is also a context manager:
+
+```python
+with Reserp(api_key=os.environ["RESERP_API_KEY"]) as client:
+    response = client.search(query="photonic computing")
+```
+
+## Pagination
+
+`page` is one-based, so you do not need to calculate Google's `start` offsets:
+
+```python
+second_page = client.search(
+    query="photonic computing",
+    page=2,
+)
+```
+
+You can also follow the authoritative pagination URL returned by the API:
+
+```python
+first = client.search(query="photonic computing")
+second = client.next_page(first)
+```
+
+Do not derive pagination from `len(response["results"])`. A response can contain organic listings, news, carousels, sitelinks, and nested result blocks.
+
+## Google parameters
+
+Use `params` for additional Google parameters such as `tbs` and `tbm`:
+
+```python
+news = client.search(
+    query="semiconductor manufacturing",
+    params={"tbm": "nws", "tbs": "qdr:w"},
+)
+```
+
+For complete control, submit a full Google Search URL:
+
+```python
+response = client.search_url(
+    "https://www.google.com/search?q=semiconductor+manufacturing&gl=us&hl=en&tbs=qdr:w"
+)
+```
+
+All Google URL parameters pass through unchanged except parameters documented as unsupported by Reserp. The `num` parameter is currently unsupported.
+
+## Errors and retries
+
+API failures raise `ReserpAPIError` with the stable public error code and billing state:
+
+```python
+from reserp import ReserpAPIError
+
+try:
+    response = client.search(query="photonic computing")
+except ReserpAPIError as error:
+    print(error.status, error.code, error.retryable, error.billed)
+```
+
+The SDK retries retryable API responses up to two times by default, respecting `Retry-After` for rate limits. It never automatically retries a response whose `billed` field is true. Network failures are not automatically retried because the client cannot know whether the original request reached the API.
+
+Configure retries and per-attempt timeouts globally or per request:
+
+```python
+client = Reserp(
+    api_key=os.environ["RESERP_API_KEY"],
+    max_retries=1,
+    timeout=20.0,
+)
+
+response = client.search(
+    query="photonic computing",
+    max_retries=0,
+    timeout=10.0,
+)
+```
+
+Set `timeout=0` to disable the SDK timeout.
+
+## API reference
+
+- [Reserp API documentation](https://reserp.ai/docs)
+- [OpenAPI 3.1 document](https://reserp.ai/openapi.json)
+- [Pricing](https://reserp.ai/pricing)
+
+## License
+
+MIT

reserp-0.1.0/README.md

@@ -0,0 +1,170 @@
+<p align="center">
+  <a href="https://reserp.ai">
+    <img src="https://reserp.ai/icon-512.png" alt="Reserp Google Search API" width="112" height="112">
+  </a>
+</p>
+
+# Reserp Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/reserp.svg)](https://pypi.org/project/reserp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/reserp.svg)](https://pypi.org/project/reserp/)
+[![CI](https://github.com/reserp-ai/reserp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/reserp-ai/reserp-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The official Python SDK for [Reserp](https://reserp.ai), a Google Search API for developers and AI agents.
+
+Retrieve structured Google Search results through one stable JSON schema. Start for free with no credit card required.
+
+[Website](https://reserp.ai) · [API documentation](https://reserp.ai/docs) · [OpenAPI 3.1](https://reserp.ai/openapi.json) · [Pricing](https://reserp.ai/pricing)
+
+## Features
+
+- Synchronous and asynchronous clients built on HTTPX.
+- Typed responses that preserve the complete API response dictionary.
+- One-based pagination plus support for authoritative pagination URLs.
+- Configurable retries and timeouts.
+- Automatic retries only when the API says the request is retryable and was not billed.
+
+## Installation
+
+```bash
+pip install reserp
+```
+
+Python 3.10 or later is required.
+
+## Quick start
+
+```python
+import os
+
+from reserp import Reserp
+
+client = Reserp(api_key=os.environ["RESERP_API_KEY"])
+
+response = client.search(
+    query="best pizza in dubai",
+    gl="ae",
+    hl="en",
+)
+
+for result in response["results"]:
+    print(result.get("text"), result.get("url"))
+```
+
+Create an API key in the [Reserp dashboard](https://reserp.ai/dashboard). Keep API keys on your server; never embed one in browser or mobile code.
+
+The SDK returns the API response as a normal Python dictionary. Result order, nested `children`, pagination, and billing fields remain intact.
+
+## Async client
+
+```python
+import asyncio
+import os
+
+from reserp import AsyncReserp
+
+
+async def main() -> None:
+    async with AsyncReserp(api_key=os.environ["RESERP_API_KEY"]) as client:
+        response = await client.search(
+            query="semiconductor manufacturing",
+            gl="us",
+            hl="en",
+        )
+        print(response["results"])
+
+
+asyncio.run(main())
+```
+
+The synchronous client is also a context manager:
+
+```python
+with Reserp(api_key=os.environ["RESERP_API_KEY"]) as client:
+    response = client.search(query="photonic computing")
+```
+
+## Pagination
+
+`page` is one-based, so you do not need to calculate Google's `start` offsets:
+
+```python
+second_page = client.search(
+    query="photonic computing",
+    page=2,
+)
+```
+
+You can also follow the authoritative pagination URL returned by the API:
+
+```python
+first = client.search(query="photonic computing")
+second = client.next_page(first)
+```
+
+Do not derive pagination from `len(response["results"])`. A response can contain organic listings, news, carousels, sitelinks, and nested result blocks.
+
+## Google parameters
+
+Use `params` for additional Google parameters such as `tbs` and `tbm`:
+
+```python
+news = client.search(
+    query="semiconductor manufacturing",
+    params={"tbm": "nws", "tbs": "qdr:w"},
+)
+```
+
+For complete control, submit a full Google Search URL:
+
+```python
+response = client.search_url(
+    "https://www.google.com/search?q=semiconductor+manufacturing&gl=us&hl=en&tbs=qdr:w"
+)
+```
+
+All Google URL parameters pass through unchanged except parameters documented as unsupported by Reserp. The `num` parameter is currently unsupported.
+
+## Errors and retries
+
+API failures raise `ReserpAPIError` with the stable public error code and billing state:
+
+```python
+from reserp import ReserpAPIError
+
+try:
+    response = client.search(query="photonic computing")
+except ReserpAPIError as error:
+    print(error.status, error.code, error.retryable, error.billed)
+```
+
+The SDK retries retryable API responses up to two times by default, respecting `Retry-After` for rate limits. It never automatically retries a response whose `billed` field is true. Network failures are not automatically retried because the client cannot know whether the original request reached the API.
+
+Configure retries and per-attempt timeouts globally or per request:
+
+```python
+client = Reserp(
+    api_key=os.environ["RESERP_API_KEY"],
+    max_retries=1,
+    timeout=20.0,
+)
+
+response = client.search(
+    query="photonic computing",
+    max_retries=0,
+    timeout=10.0,
+)
+```
+
+Set `timeout=0` to disable the SDK timeout.
+
+## API reference
+
+- [Reserp API documentation](https://reserp.ai/docs)
+- [OpenAPI 3.1 document](https://reserp.ai/openapi.json)
+- [Pricing](https://reserp.ai/pricing)
+
+## License
+
+MIT

reserp-0.1.0/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+Do not include API keys or account data in issues, discussions, logs, or example code.
+
+To report a vulnerability privately, use [GitHub private vulnerability reporting](https://github.com/reserp-ai/reserp-python/security/advisories/new).

reserp-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling>=1.27,<1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reserp"
+dynamic = ["version"]
+description = "Official Python SDK for the Reserp Google Search API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Reserp", email = "no-reply@reserp.ai" }]
+keywords = [
+  "reserp",
+  "google-search",
+  "google-search-api",
+  "serp",
+  "serp-api",
+  "search-api",
+  "api-client",
+  "sdk",
+  "python",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "mypy>=1.13,<2",
+  "pytest>=8.3,<10",
+  "ruff>=0.8,<1",
+  "twine>=5.1,<7",
+]
+
+[project.urls]
+Homepage = "https://reserp.ai"
+Documentation = "https://reserp.ai/docs"
+Repository = "https://github.com/reserp-ai/reserp-python"
+Issues = "https://github.com/reserp-ai/reserp-python/issues"
+Changelog = "https://github.com/reserp-ai/reserp-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/reserp/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reserp"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "SIM", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+pretty = true
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

reserp-0.1.0/src/reserp/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

reserp-0.1.0/src/reserp/__init__.py

@@ -0,0 +1,37 @@
+from .__about__ import __version__
+from .client import AsyncReserp, Reserp
+from .errors import (
+    ReserpAPIError,
+    ReserpConnectionError,
+    ReserpError,
+    ReserpTimeoutError,
+    ReserpUnexpectedResponseError,
+)
+from .types import (
+    ErrorCode,
+    ErrorResponse,
+    GoogleParameterValue,
+    Pagination,
+    Result,
+    SearchResponse,
+)
+from .urls import build_google_search_url, validate_google_search_url
+
+__all__ = [
+    "AsyncReserp",
+    "ErrorCode",
+    "ErrorResponse",
+    "GoogleParameterValue",
+    "Pagination",
+    "Reserp",
+    "ReserpAPIError",
+    "ReserpConnectionError",
+    "ReserpError",
+    "ReserpTimeoutError",
+    "ReserpUnexpectedResponseError",
+    "Result",
+    "SearchResponse",
+    "__version__",
+    "build_google_search_url",
+    "validate_google_search_url",
+]