parreq 1.0.0__tar.gz

parreq-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+runtime/
+__pycache__/
+*.pyc
+secrets.json
+docs/site/
+docs/site.zip
+runtime/admin_key.txt

parreq-1.0.0/LICENSE

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

parreq-1.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: parreq
+Version: 1.0.0
+Summary: Клиент ParReq: поисковая выдача Google и Яндекса в JSON
+Project-URL: Documentation, https://req.akuraq.dev/docs
+Project-URL: Homepage, https://req.akuraq.dev
+License: MIT
+License-File: LICENSE
+Keywords: google,scraping,search-api,serp,yandex
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# parreq
+
+Клиент [ParReq](https://req.akuraq.dev) — поисковая выдача Google и Яндекса в
+JSON. Без зависимостей, только стандартная библиотека.
+
+```bash
+pip install parreq
+```
+
+```python
+from parreq import ParReq
+
+client = ParReq("pr_ВАШКЛЮЧ")
+
+res = client.yandex("кофемашина", gl="by", hl="ru", include=["ads", "shopping"])
+print(len(res.organic), "органических,", len(res.ads), "объявлений")
+
+for item in res.organic:
+    print(item["position"], item["title"], item["link"])
+```
+
+`engine` обязателен, поэтому у общего метода он позиционно-именованный, а для
+двух движков есть сахар:
+
+```python
+client.search("coffee machine", engine="google", gl="us", hl="en")
+client.google("coffee machine", gl="us")
+client.yandex("кофемашина", gl="by", hl="ru")
+```
+
+## Секции
+
+По умолчанию приходит только органика. Остальное — через `include`:
+
+```python
+res = client.google("купить кофемашину", gl="by", hl="ru",
+                    include=["ads", "shopping", "videos", "related_searches"])
+res.ads, res.shopping, res.videos, res.related
+```
+
+Доступно: `ads`, `shopping`, `local`, `knowledge_graph`, `ai_overview`,
+`answer_box`, `people_also_ask`, `related_searches`, `images`, `videos`, `news`,
+`total_results`, либо `include="all"`.
+
+## Ошибки
+
+```python
+from parreq import ParReq, RateLimited, NoWorkers, SearchBlocked, ParReqError
+
+try:
+    res = client.google("coffee", gl="us")
+except NoWorkers as exc:          # 503: нет прогретого профиля под движок
+    print("повторить через", exc.retry_after, "с")
+except RateLimited as exc:        # 429: частота, квота или одновременность
+    print(exc.code, exc.retry_after)
+except SearchBlocked:             # 502: защиту обойти не удалось
+    ...
+except ParReqError as exc:        # всё остальное
+    print(exc.status, exc.code, exc.request_id)
+```
+
+Клиент **сам повторяет** то, что лечится повтором (429, 502, 503, 504), выжидая
+столько, сколько просит сервер в `Retry-After`. По умолчанию три попытки:
+
+```python
+client = ParReq("pr_…", retries=0)      # выключить повторы
+client = ParReq("pr_…", timeout=240)    # запрос с решением капчи бывает долгим
+```
+
+## Свой расход
+
+```python
+u = client.usage()
+print(u["used_today"], "из", u["limits"]["daily"])
+```

parreq-1.0.0/README.md

@@ -0,0 +1,75 @@
+# parreq
+
+Клиент [ParReq](https://req.akuraq.dev) — поисковая выдача Google и Яндекса в
+JSON. Без зависимостей, только стандартная библиотека.
+
+```bash
+pip install parreq
+```
+
+```python
+from parreq import ParReq
+
+client = ParReq("pr_ВАШКЛЮЧ")
+
+res = client.yandex("кофемашина", gl="by", hl="ru", include=["ads", "shopping"])
+print(len(res.organic), "органических,", len(res.ads), "объявлений")
+
+for item in res.organic:
+    print(item["position"], item["title"], item["link"])
+```
+
+`engine` обязателен, поэтому у общего метода он позиционно-именованный, а для
+двух движков есть сахар:
+
+```python
+client.search("coffee machine", engine="google", gl="us", hl="en")
+client.google("coffee machine", gl="us")
+client.yandex("кофемашина", gl="by", hl="ru")
+```
+
+## Секции
+
+По умолчанию приходит только органика. Остальное — через `include`:
+
+```python
+res = client.google("купить кофемашину", gl="by", hl="ru",
+                    include=["ads", "shopping", "videos", "related_searches"])
+res.ads, res.shopping, res.videos, res.related
+```
+
+Доступно: `ads`, `shopping`, `local`, `knowledge_graph`, `ai_overview`,
+`answer_box`, `people_also_ask`, `related_searches`, `images`, `videos`, `news`,
+`total_results`, либо `include="all"`.
+
+## Ошибки
+
+```python
+from parreq import ParReq, RateLimited, NoWorkers, SearchBlocked, ParReqError
+
+try:
+    res = client.google("coffee", gl="us")
+except NoWorkers as exc:          # 503: нет прогретого профиля под движок
+    print("повторить через", exc.retry_after, "с")
+except RateLimited as exc:        # 429: частота, квота или одновременность
+    print(exc.code, exc.retry_after)
+except SearchBlocked:             # 502: защиту обойти не удалось
+    ...
+except ParReqError as exc:        # всё остальное
+    print(exc.status, exc.code, exc.request_id)
+```
+
+Клиент **сам повторяет** то, что лечится повтором (429, 502, 503, 504), выжидая
+столько, сколько просит сервер в `Retry-After`. По умолчанию три попытки:
+
+```python
+client = ParReq("pr_…", retries=0)      # выключить повторы
+client = ParReq("pr_…", timeout=240)    # запрос с решением капчи бывает долгим
+```
+
+## Свой расход
+
+```python
+u = client.usage()
+print(u["used_today"], "из", u["limits"]["daily"])
+```

parreq-1.0.0/parreq/__init__.py

@@ -0,0 +1,281 @@
+"""ParReq — клиент поисковой выдачи Google и Яндекса.
+
+Зависимостей нет намеренно: библиотека тонкая, а `requests` в проекте, который
+берёт её ради одного запроса, тянет за собой лишнее и конфликтует с чужими
+версиями. Всё нужное есть в стандартной библиотеке.
+
+    from parreq import ParReq
+
+    client = ParReq("pr_…")
+    res = client.search("кофемашина", engine="yandex", gl="by", hl="ru",
+                        include=["ads", "shopping"])
+    for item in res.organic:
+        print(item["position"], item["title"])
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional
+
+__all__ = [
+    "ParReq", "SearchResult", "ParReqError", "BadRequest", "AuthError",
+    "RateLimited", "NoWorkers", "SearchBlocked", "ServerError", "DEFAULT_BASE_URL",
+]
+
+DEFAULT_BASE_URL = "https://req.akuraq.dev"
+# Запрос идёт в настоящий браузер: на прогретом профиле это 3–10 секунд, а с
+# решением капчи — до двух минут. Таймаут меньше рвёт нормальные запросы.
+DEFAULT_TIMEOUT = 180.0
+# Коды, которые лечатся повтором. Остальные повторять бессмысленно: неверный
+# параметр и отозванный ключ от этого не исправятся.
+RETRIABLE = frozenset({429, 502, 503, 504})
+USER_AGENT = "parreq-python/1.0"
+
+
+class ParReqError(Exception):
+    """Базовая ошибка. Разбирать стоит `code`, а не текст: текст переписывается."""
+
+    def __init__(self, status: int, code: str, message: str,
+                 request_id: str = "", retry_after: Optional[int] = None,
+                 details: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.details = details or {}
+
+
+class BadRequest(ParReqError):
+    """400 — параметры. Смотрите `details`, там перечислено допустимое."""
+
+
+class AuthError(ParReqError):
+    """401 и 403 — ключ не передан, не найден или отозван."""
+
+
+class RateLimited(ParReqError):
+    """429 — частота, суточная квота или одновременность. Ждите `retry_after`."""
+
+
+class NoWorkers(ParReqError):
+    """503 — нет прогретого профиля под этот движок. Повтор имеет смысл."""
+
+
+class SearchBlocked(ParReqError):
+    """502 search_blocked — защиту поисковика на этом запросе обойти не вышло."""
+
+
+class ServerError(ParReqError):
+    """Прочие 5xx, включая таймаут поисковика."""
+
+
+_BY_CODE = {
+    "invalid_request": BadRequest,
+    "missing_api_key": AuthError,
+    "invalid_api_key": AuthError,
+    "key_revoked": AuthError,
+    "admin_only": AuthError,
+    "rate_limited": RateLimited,
+    "quota_exceeded": RateLimited,
+    "concurrency_limit": RateLimited,
+    "no_workers_available": NoWorkers,
+    "search_blocked": SearchBlocked,
+}
+
+
+def _error_from(status: int, body: Dict[str, Any], retry_after: Optional[int]) -> ParReqError:
+    err = body.get("error") or {}
+    code = err.get("code") or f"http_{status}"
+    cls = _BY_CODE.get(code)
+    if cls is None:
+        cls = AuthError if status in (401, 403) else (
+            BadRequest if status == 400 else ServerError)
+    return cls(status, code, err.get("message") or "без описания",
+               err.get("request_id", ""), retry_after, err.get("details"))
+
+
+@dataclass
+class SearchResult:
+    """Ответ поиска. Секции доступны и как атрибуты, и целиком через `raw`."""
+
+    raw: Dict[str, Any] = field(repr=False)
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        return self.raw.get("search_metadata", {})
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return self.raw.get("search_parameters", {})
+
+    @property
+    def request_id(self) -> str:
+        return self.metadata.get("id", "")
+
+    @property
+    def organic(self) -> List[Dict[str, Any]]:
+        return self.raw.get("organic_results", [])
+
+    @property
+    def ads(self) -> List[Dict[str, Any]]:
+        return self.raw.get("ads", [])
+
+    @property
+    def shopping(self) -> List[Dict[str, Any]]:
+        return self.raw.get("shopping_results", [])
+
+    @property
+    def local(self) -> List[Dict[str, Any]]:
+        return self.raw.get("local_results", [])
+
+    @property
+    def videos(self) -> List[Dict[str, Any]]:
+        return self.raw.get("inline_videos", [])
+
+    @property
+    def images(self) -> List[Dict[str, Any]]:
+        return self.raw.get("inline_images", [])
+
+    @property
+    def news(self) -> List[Dict[str, Any]]:
+        return self.raw.get("top_stories", [])
+
+    @property
+    def related(self) -> List[Dict[str, Any]]:
+        return self.raw.get("related_searches", [])
+
+    @property
+    def people_also_ask(self) -> List[Dict[str, Any]]:
+        return self.raw.get("people_also_ask", [])
+
+    @property
+    def knowledge_graph(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("knowledge_graph")
+
+    @property
+    def answer_box(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("answer_box")
+
+    @property
+    def ai_overview(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("ai_overview")
+
+    @property
+    def total_results(self) -> Optional[int]:
+        return self.raw.get("total_results")
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def __repr__(self) -> str:
+        md = self.metadata
+        return (f"<SearchResult {md.get('engine')} "
+                f"organic={len(self.organic)} {md.get('total_ms')}ms>")
+
+
+class ParReq:
+    """Клиент.
+
+    :param api_key: ключ вида ``pr_…``
+    :param base_url: адрес сервиса
+    :param timeout: сколько ждать ответ, секунд
+    :param retries: сколько раз повторять то, что лечится повтором
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = DEFAULT_TIMEOUT, retries: int = 3) -> None:
+        if not api_key:
+            raise ValueError("нужен ключ ParReq")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = max(0, retries)
+
+    # --- публичное ----------------------------------------------------------
+    def search(self, q: str, engine: str, *, device: str = "desktop",
+               gl: str = "us", hl: str = "en", page: int = 1,
+               num: Optional[int] = None, location: Optional[str] = None,
+               domain: Optional[str] = None,
+               include: Optional[Iterable[str]] = None) -> SearchResult:
+        """Поиск. `engine` обязателен: `google` или `yandex`.
+
+        `include` — секции сверх органики: ``["ads", "shopping", "videos"]`` или
+        ``"all"``. По умолчанию приходит только органика.
+        """
+        params: Dict[str, Any] = {
+            "q": q, "engine": engine, "device": device, "gl": gl, "hl": hl,
+            "page": page,
+        }
+        if num is not None:
+            params["num"] = num
+        if location:
+            params["location"] = location
+        if domain:
+            params["domain"] = domain
+        if include:
+            params["include"] = include if isinstance(include, str) else ",".join(include)
+        return SearchResult(self._request("GET", "/v1/search", params=params))
+
+    def google(self, q: str, **kwargs: Any) -> SearchResult:
+        """Сахар: ``client.google("coffee machine", gl="us")``."""
+        return self.search(q, engine="google", **kwargs)
+
+    def yandex(self, q: str, **kwargs: Any) -> SearchResult:
+        """Сахар: ``client.yandex("кофемашина", gl="by", hl="ru")``."""
+        return self.search(q, engine="yandex", **kwargs)
+
+    def usage(self) -> Dict[str, Any]:
+        """Остаток лимитов по своему ключу."""
+        return self._request("GET", "/v1/usage")
+
+    def meta(self) -> Dict[str, Any]:
+        """Справочники: движки, устройства, страны, языки, секции."""
+        return self._request("GET", "/v1/meta")
+
+    # --- внутреннее ---------------------------------------------------------
+    def _request(self, method: str, path: str,
+                 params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        url = self.base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+
+        last: Optional[ParReqError] = None
+        for attempt in range(self.retries + 1):
+            try:
+                return self._once(method, url)
+            except ParReqError as exc:
+                if exc.status not in RETRIABLE or attempt == self.retries:
+                    raise
+                last = exc
+                # ждём столько, сколько попросил сервер: у квоты это время до
+                # полуночи, и «подождать 5 секунд» там ничего не изменит
+                time.sleep(exc.retry_after if exc.retry_after is not None else 5)
+        raise last  # недостижимо, но делает намерение явным
+
+    def _once(self, method: str, url: str) -> Dict[str, Any]:
+        req = urllib.request.Request(url, method=method, headers={
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        })
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode("utf-8", "replace")
+            try:
+                body = json.loads(raw)
+            except ValueError:
+                body = {"error": {"code": f"http_{exc.code}", "message": raw[:200]}}
+            retry_after = exc.headers.get("Retry-After") if exc.headers else None
+            raise _error_from(exc.code, body,
+                              int(retry_after) if retry_after and retry_after.isdigit() else None)
+        except urllib.error.URLError as exc:
+            raise ServerError(0, "connection_error", f"не удалось соединиться: {exc.reason}")

parreq-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "parreq"
+version = "1.0.0"
+description = "Клиент ParReq: поисковая выдача Google и Яндекса в JSON"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["serp", "google", "yandex", "scraping", "search-api"]
+# Зависимостей нет намеренно: библиотека тонкая, и тянуть requests ради одного
+# запроса значит навязывать чужому проекту разрешение версий.
+dependencies = []
+
+[project.urls]
+Documentation = "https://req.akuraq.dev/docs"
+Homepage = "https://req.akuraq.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["parreq"]