jsonseo 1.0.0__py3-none-any.whl

jsonseo/__init__.py

@@ -0,0 +1,45 @@
+"""
+Официальный Python SDK для JSON SEO API.
+
+>>> from jsonseo import Client
+>>> client = Client("ВАШ_КЛЮЧ")
+>>> serp = client.yandex("купить ноутбук", region=213)
+"""
+
+from .client import VERSION, Client
+from .errors import (
+    ApiError,
+    IncompleteResponseError,
+    InvalidArgumentError,
+    JsonSeoError,
+    NetworkError,
+    ParseError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TimeoutError,
+    UnauthorizedError,
+    ValidationError,
+)
+from .transport import Response, UrllibTransport
+
+__version__ = VERSION
+
+__all__ = [
+    "Client",
+    "Response",
+    "UrllibTransport",
+    "JsonSeoError",
+    "ApiError",
+    "PaymentRequiredError",
+    "UnauthorizedError",
+    "ValidationError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "NetworkError",
+    "TimeoutError",
+    "IncompleteResponseError",
+    "ParseError",
+    "InvalidArgumentError",
+    "__version__",
+]

jsonseo/client.py

@@ -0,0 +1,394 @@
+"""Клиент JSON SEO API."""
+
+import email.utils
+import json
+import random
+import time
+import urllib.parse
+from typing import Any, Dict, Optional, Sequence, Union
+
+from .errors import (
+    IncompleteResponseError,
+    InvalidArgumentError,
+    NetworkError,
+    ParseError,
+    TimeoutError,
+    api_error_for,
+)
+from .transport import Response, UrllibTransport
+from .types import (
+    BalanceResponse,
+    DirectResponse,
+    GeoipResponse,
+    GoogleRegionsResponse,
+    ImagesResponse,
+    SearchResponse,
+    SuggestResponse,
+    VideoResponse,
+    WordstatFrequencyResponse,
+    WordstatGraphResponse,
+    WordstatMapResponse,
+    WordstatResponse,
+    YandexRegionsResponse,
+)
+
+__all__ = ["Client"]
+
+VERSION = "1.0.0"
+DEFAULT_BASE_URL = "https://jsonseo.ru/api"
+
+Primary = Union[str, int, Sequence[str], None]
+
+
+class Client:
+    """
+    Клиент JSON SEO API.
+
+    >>> client = Client("ВАШ_КЛЮЧ")
+    >>> serp = client.yandex("купить ноутбук", region=213)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 300.0,
+        attempts: int = 3,
+        retry_delay: float = 1.0,
+        max_retry_delay: float = 30.0,
+        auth: str = "header",
+        user_agent: Optional[str] = None,
+        transport: Any = None,
+    ) -> None:
+        if not isinstance(api_key, str) or api_key.strip() == "":
+            raise InvalidArgumentError(
+                "Нужен API-ключ: возьмите его в личном кабинете на https://jsonseo.ru."
+            )
+
+        if auth not in ("header", "query"):
+            raise InvalidArgumentError(
+                'Настройка auth принимает "header" или "query", получено: {!r}.'.format(auth)
+            )
+
+        if not isinstance(attempts, int) or isinstance(attempts, bool) or attempts < 1:
+            raise InvalidArgumentError(
+                "Настройка attempts ожидает целое число не меньше 1, получено: {!r}.".format(attempts)
+            )
+
+        self._api_key = api_key.strip()
+        self._base_url = base_url.rstrip("/")
+        # Многостраничная выдача идёт минутами, и оборванный запрос всё
+        # равно будет досчитан и оплачен.
+        self._timeout = float(timeout)
+        self._attempts = attempts
+        self._retry_delay = float(retry_delay)
+        self._max_retry_delay = float(max_retry_delay)
+        self._auth = auth
+        self._user_agent = user_agent or "jsonseo-python/{}".format(VERSION)
+        self._transport = transport or UrllibTransport()
+
+    # --- Яндекс ---
+
+    def yandex(self, text: Primary = None, **params: Any) -> SearchResponse:
+        """Органическая выдача Яндекса: мобильная, регион 213. 0.01 ₽ за страницу."""
+        return self._request("yandex", self._primary(text, "text", params))
+
+    def yandex_suggest(self, text: Primary = None, **params: Any) -> SuggestResponse:
+        """Подсказки Яндекса: до 50 фраз с учётом региона. 0.01 ₽ за запрос."""
+        return self._request("yandex/suggest", self._primary(text, "text", params))
+
+    def yandex_regions(self, name: Primary = None, **params: Any) -> YandexRegionsResponse:
+        """Код региона (lr) по названию города или области. Бесплатно, нужен ключ."""
+        return self._request("yandex/regions", self._primary(name, "name", params))
+
+    def yandex_images(self, q: Primary = None, **params: Any) -> ImagesResponse:
+        """Картинки Яндекса: 20 карточек на страницу, 0.01 ₽ за страницу."""
+        return self._request("yandex/images", self._primary(q, "q", params))
+
+    def yandex_video(self, q: Primary = None, **params: Any) -> VideoResponse:
+        """Видео Яндекса: 20 карточек на страницу, 0.01 ₽ за страницу."""
+        return self._request("yandex/video", self._primary(q, "q", params))
+
+    # --- Google ---
+
+    def google(self, q: Primary = None, **params: Any) -> SearchResponse:
+        """Органическая выдача google.com: мобильная, 0.01 ₽ за страницу."""
+        return self._request("google", self._primary(q, "q", params))
+
+    def google_suggest(self, q: Primary = None, **params: Any) -> SuggestResponse:
+        """Подсказки Google: до ~15 фраз. 0.01 ₽ за запрос."""
+        return self._request("google/suggest", self._primary(q, "q", params))
+
+    def google_regions(self, name: Primary = None, **params: Any) -> GoogleRegionsResponse:
+        """ID региона Google по названию и готовый uule. Бесплатно, нужен ключ."""
+        return self._request("google/regions", self._primary(name, "name", params))
+
+    def google_images(self, q: Primary = None, **params: Any) -> ImagesResponse:
+        """Картинки Google: 100 карточек на страницу, 0.01 ₽ за страницу."""
+        return self._request("google/images", self._primary(q, "q", params))
+
+    def google_video(self, q: Primary = None, **params: Any) -> VideoResponse:
+        """Видео Google: 10 карточек на страницу, 0.01 ₽ за страницу."""
+        return self._request("google/video", self._primary(q, "q", params))
+
+    # --- Bing ---
+
+    def bing(self, q: Primary = None, **params: Any) -> SearchResponse:
+        """Органическая выдача bing.com: без локации — Россия, 0.01 ₽ за страницу."""
+        return self._request("bing", self._primary(q, "q", params))
+
+    def bing_suggest(self, q: Primary = None, **params: Any) -> SuggestResponse:
+        """Подсказки Bing. 0.01 ₽ за запрос."""
+        return self._request("bing/suggest", self._primary(q, "q", params))
+
+    def bing_images(self, q: Primary = None, **params: Any) -> ImagesResponse:
+        """Картинки Bing: count карточек (по умолчанию 35), дальше 700-й не листает."""
+        return self._request("bing/images", self._primary(q, "q", params))
+
+    def bing_video(self, q: Primary = None, **params: Any) -> VideoResponse:
+        """Видео Bing: count карточек на страницу, по умолчанию 105."""
+        return self._request("bing/video", self._primary(q, "q", params))
+
+    # --- Вордстат ---
+
+    def wordstat(self, text: Primary = None, **params: Any) -> WordstatResponse:
+        """Популярные и похожие запросы. 0.01 ₽ за запрос."""
+        return self._request("wordstat", self._primary(text, "text", params))
+
+    def wordstat_frequency(self, text: Primary = None, **params: Any) -> WordstatFrequencyResponse:
+        """Частота запроса одним числом — results.totalValue. 0.01 ₽ за запрос."""
+        return self._request("wordstat/frequency", self._primary(text, "text", params))
+
+    def wordstat_graph(self, text: Primary = None, **params: Any) -> WordstatGraphResponse:
+        """Динамика показов: month и week — с 2018 года, day — последние 60 дней."""
+        return self._request("wordstat/graph", self._primary(text, "text", params))
+
+    def wordstat_map(self, text: Primary = None, **params: Any) -> WordstatMapResponse:
+        """Показы по регионам и городам. popularity — affinity-индекс, 100 — средний."""
+        return self._request("wordstat/map", self._primary(text, "text", params))
+
+    # --- Директ и служебные ---
+
+    def direct(self, phrases: Primary = None, **params: Any) -> DirectResponse:
+        """
+        Прогноз показов Директа со ставками и бюджетом. Кабинет не нужен.
+
+        Список фраз передаётся как есть — SDK склеит его сам. Вид частотности
+        задаётся операторами во фразе: "ремонт айфона" — фразовая,
+        "!ремонт !айфона" — точная.
+        """
+        return self._request("direct", self._primary(phrases, "phrases", params))
+
+    def geoip(self, ip: Primary = None, **params: Any) -> GeoipResponse:
+        """Страна, регион и координаты по IPv4. Бесплатно, нужен ключ."""
+        return self._request("geoip", self._primary(ip, "ip", params))
+
+    def balance(self) -> BalanceResponse:
+        """Текущий баланс. Бесплатно, нужен ключ."""
+        return self._request("balance", {})
+
+    # --- Запасной выход ---
+
+    def call(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Произвольный метод API — если в сервисе появился новый."""
+        return self._request(path, dict(params or {}))
+
+    def call_raw(self, path: str, params: Optional[Dict[str, Any]] = None) -> str:
+        """То же, но ответ возвращается строкой без разбора."""
+        return self._request(path, dict(params or {}), decode_json=False)
+
+    # --- Внутреннее ---
+
+    def _primary(self, value: Primary, name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Даёт вызывать метод позиционно: yandex("купить ноутбук").
+
+        Дубль (и позиционно, и по имени) ловит сам Python: у аргумента то же
+        имя, что у параметра, и вызов не состоится.
+        """
+        if value is not None:
+            params[name] = value
+
+        return params
+
+    def _request(self, path: str, params: Dict[str, Any], decode_json: bool = True) -> Any:
+        """
+        Выполняет запрос, повторяя те отказы, за которые сервис не берёт
+        денег: 429, 5xx и обрывы связи до того, как ответ начал приходить.
+        """
+        query = self._normalize(params)
+
+        if self._auth == "query":
+            query["key"] = self._api_key
+
+        headers = {
+            "Accept": "application/json" if decode_json else "application/xml, text/xml",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": self._user_agent,
+        }
+
+        if self._auth == "header":
+            headers["Authorization"] = "Bearer " + self._api_key
+
+        # Всегда POST: длинные списки фраз в GET не помещаются.
+        url = "{}/{}".format(self._base_url, path.lstrip("/"))
+        body = urllib.parse.urlencode(query)
+
+        attempt = 0
+
+        while True:
+            try:
+                response = self._transport.send("POST", url, headers, body, self._timeout)
+            except NetworkError as error:
+                # Таймаут и обрыв на середине тела не повторяем: выдача уже
+                # собрана и оплачена.
+                if (
+                    self._is_last_attempt(attempt)
+                    or isinstance(error, (TimeoutError, IncompleteResponseError))
+                ):
+                    raise
+
+                time.sleep(self._backoff(attempt))
+                attempt += 1
+
+                continue
+
+            if 200 <= response.status < 300:
+                return self._decode(response.body) if decode_json else response.body
+
+            retry_after = self._retry_after(response)
+            error = api_error_for(
+                response.status, response.body, self._decode_quietly(response.body), retry_after
+            )
+
+            # Проснуться раньше названного срока — снова получить тот же
+            # отказ. Ждать дольше потолка не станем: отдаём ошибку.
+            if (
+                self._is_last_attempt(attempt)
+                or not self._is_retryable(response.status)
+                or (retry_after is not None and retry_after > self._max_retry_delay)
+            ):
+                raise error
+
+            # Не раньше, чем просит сервис, и не чаще своего бэкоффа:
+            # Retry-After прошедшей датой даёт ноль.
+            pause = self._backoff(attempt)
+            time.sleep(pause if retry_after is None else max(float(retry_after), pause))
+            attempt += 1
+
+    def _is_last_attempt(self, attempt: int) -> bool:
+        """Попытки нумеруются с нуля: при attempts = 3 у последней индекс 2."""
+        return attempt + 1 >= self._attempts
+
+    def _is_retryable(self, status: int) -> bool:
+        return status == 429 or status >= 500
+
+    def _normalize(self, params: Dict[str, Any]) -> Dict[str, str]:
+        """Приводит параметры к тому виду, в каком их ждёт форма запроса."""
+        normalized = {}
+
+        for name, value in params.items():
+            if value is None:
+                continue
+
+            if isinstance(value, bool):
+                normalized[name] = "1" if value else "0"
+
+                continue
+
+            if isinstance(value, (list, tuple)):
+                items = list(value)
+
+                # Пустой список — «параметр не задан»: от region= сервис
+                # отказал бы валидацией.
+                if not items:
+                    continue
+
+                # Фразы — переводом строки: запятая в них встречается.
+                separator = "\n" if name == "phrases" else ","
+                normalized[name] = separator.join(
+                    self._scalar(item, "{}[{}]".format(name, index)) for index, item in enumerate(items)
+                )
+
+                continue
+
+            normalized[name] = self._scalar(value, name)
+
+        return normalized
+
+    def _scalar(self, value: Any, name: str) -> str:
+        if isinstance(value, bool):
+            return "1" if value else "0"
+
+        if isinstance(value, (int, float)):
+            return str(value)
+
+        if isinstance(value, str):
+            return value
+
+        if isinstance(value, (set, frozenset)):
+            raise InvalidArgumentError(
+                "Параметр {} получил множество: порядок его обхода не определён, "
+                "и запрос перестал бы быть воспроизводимым. Передайте список.".format(name)
+            )
+
+        raise InvalidArgumentError(
+            "Значение параметра {} должно быть строкой, числом, флагом или списком "
+            "таких значений, получено: {!r}.".format(name, value)
+        )
+
+    def _decode(self, body: str) -> Any:
+        try:
+            return json.loads(body)
+        except ValueError as error:
+            # Тело кладём в ошибку: страница выдачи уже оплачена.
+            raise ParseError(
+                "Ответ JSON SEO API не разобрался как JSON: {}.".format(error), body
+            ) from error
+
+    def _decode_quietly(self, body: str) -> Dict[str, Any]:
+        """Тело ошибки может быть и не JSON — тогда подробностей просто нет."""
+        try:
+            parsed = json.loads(body)
+        except ValueError:
+            return {}
+
+        return parsed if isinstance(parsed, dict) else {}
+
+    def _retry_after(self, response: Response) -> Optional[int]:
+        """
+        Сколько секунд просит подождать сервис. RFC 9110 разрешает число
+        секунд и HTTP-дату, разбираются обе.
+        """
+        value = response.header("retry-after")
+
+        if value is None:
+            return None
+
+        value = value.strip()
+
+        # isdigit() истинно и для юникод-цифр вроде «²», которые int() не
+        # берёт: без проверки на ASCII запрос падал бы голым ValueError.
+        if value.isascii() and value.isdigit():
+            return int(value)
+
+        try:
+            when = email.utils.parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+
+        if when is None:
+            return None
+
+        return max(0, int(when.timestamp() - time.time()))
+
+    def _backoff(self, attempt: int) -> float:
+        """
+        Пауза удваивается с каждой попыткой; случайная добавка разводит
+        параллельные запросы, чтобы они не вернулись разом.
+        """
+        delay = self._retry_delay * (2 ** attempt)
+
+        # Потолок накладывается после добавки, иначе она бы его превышала.
+        return min(delay + delay * 0.25 * random.random(), self._max_retry_delay)

jsonseo/errors.py

@@ -0,0 +1,127 @@
+"""Ошибки SDK."""
+
+from typing import Any, Dict, List, Optional
+
+_BuiltinTimeoutError = TimeoutError
+
+
+class JsonSeoError(Exception):
+    """Общий предок всех ошибок SDK."""
+
+
+class ApiError(JsonSeoError):
+    """Сервис ответил отказом. Тело сохраняется целиком."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        body: str = "",
+        payload: Optional[Dict[str, Any]] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+        self.payload = payload or {}
+        # Через сколько секунд вернуться. None, если срок не назван.
+        self.retry_after = retry_after
+
+
+class PaymentRequiredError(ApiError):
+    """402: на счёте не хватает средств, см. balance()."""
+
+
+class UnauthorizedError(ApiError):
+    """403 или 401: ключ не передан или недействителен."""
+
+
+class ServiceUnavailableError(ApiError):
+    """503: выдачу получить не вышло. Деньги не списаны, SDK повторит сам."""
+
+
+class RateLimitError(ApiError):
+    """429: превышен лимит частоты. Срок повтора — в retry_after."""
+
+
+class ValidationError(ApiError):
+    """422: параметры не приняты. Деньги не списываются."""
+
+    @property
+    def errors(self) -> Dict[str, List[str]]:
+        """Ошибки по именам параметров: {'text': ['Введите запрос']}."""
+        raw = self.payload.get("errors")
+
+        if not isinstance(raw, dict):
+            return {}
+
+        return {
+            field: [str(m) for m in messages] if isinstance(messages, list) else [str(messages)]
+            for field, messages in raw.items()
+        }
+
+    @property
+    def fields(self) -> List[str]:
+        """Забракованные параметры."""
+        return list(self.errors)
+
+
+class NetworkError(JsonSeoError):
+    """До сервиса не достучались: сеть, DNS, TLS. Статуса нет."""
+
+
+class TimeoutError(NetworkError, _BuiltinTimeoutError):  # noqa: A001
+    """
+    Ответа не дождались. Автоматически не повторяется: выдача всё равно
+    будет собрана и оплачена. Нужен ответ — поднимайте timeout, не attempts.
+
+    Наследует и встроенный TimeoutError, чтобы привычный except его ловил.
+    """
+
+
+class IncompleteResponseError(NetworkError):
+    """
+    Пришло меньше, чем обещал сервис. Автоматически не повторяется: выдача
+    уже собрана и оплачена, обрыв случился на отдаче.
+    """
+
+
+class ParseError(JsonSeoError):
+    """
+    Успех, но тело не разобралось как JSON. Тело сохраняется: страница уже
+    оплачена, и достать из неё данные руками лучше, чем не иметь ничего.
+    """
+
+    def __init__(self, message: str, body: str) -> None:
+        super().__init__(message)
+        self.body = body
+
+
+class InvalidArgumentError(JsonSeoError):
+    """SDK забраковал аргументы, запрос не отправлялся."""
+
+
+_BY_STATUS = {
+    401: UnauthorizedError,
+    402: PaymentRequiredError,
+    403: UnauthorizedError,
+    422: ValidationError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}
+
+
+def api_error_for(
+    status: int,
+    body: str,
+    payload: Dict[str, Any],
+    retry_after: Optional[int],
+) -> ApiError:
+    """Собирает ошибку под этот HTTP-статус."""
+    message = payload.get("message")
+
+    if not isinstance(message, str) or message == "":
+        message = "JSON SEO API вернул ошибку {}.".format(status)
+
+    return _BY_STATUS.get(status, ApiError)(message, status, body, payload, retry_after)

jsonseo/transport.py

@@ -0,0 +1,107 @@
+"""Как SDK ходит в сеть. Подменяется в тестах и в проектах со своим клиентом."""
+
+import http.client
+import socket
+import urllib.error
+import urllib.request
+from typing import Dict, Optional
+
+from .errors import IncompleteResponseError, JsonSeoError, NetworkError, TimeoutError
+
+
+class Response:
+    """Сырой ответ транспорта: статус, заголовки и тело как есть."""
+
+    __slots__ = ("status", "headers", "body")
+
+    def __init__(self, status: int, headers: Dict[str, str], body: str) -> None:
+        self.status = int(status)
+        # Имена в нижнем регистре — HTTP их регистр не различает.
+        self.headers = {name.lower(): value for name, value in headers.items()}
+        self.body = body
+
+    def header(self, name: str) -> Optional[str]:
+        return self.headers.get(name.lower())
+
+
+class UrllibTransport:
+    """
+    Транспорт на стандартной библиотеке: пакет остаётся без зависимостей.
+
+    Свой транспорт — это объект с таким же методом send. Он обязан бросать
+    ошибки SDK: от их класса зависит, повторит клиент запрос или нет.
+    """
+
+    def send(
+        self,
+        method: str,
+        url: str,
+        headers: Dict[str, str],
+        body: Optional[str],
+        timeout: float,
+    ) -> Response:
+        data = body.encode("utf-8") if body is not None else None
+        request = urllib.request.Request(url, data=data, method=method)
+
+        for name, value in headers.items():
+            # urllib сам подставляет свой User-Agent, если его не задать.
+            request.add_header(name, value)
+
+        response = self._open(request, timeout)
+
+        # Чтение тела намеренно вынесено из-под обработки ошибок соединения:
+        # сюда мы попадаем, только когда заголовки уже пришли, а значит
+        # выдача собрана и оплачена. Любой сбой отсюда повторять нельзя.
+        with response:
+            return self._read(response)
+
+    def _open(self, request: urllib.request.Request, timeout: float):
+        try:
+            return urllib.request.urlopen(request, timeout=timeout)
+        except urllib.error.HTTPError as error:
+            # Это не сбой, а ответ с кодом 4xx или 5xx: сообщение сервиса
+            # о причине отказа лежит в теле, и терять его нельзя.
+            return error
+        except socket.timeout as error:
+            raise TimeoutError("Ответа от JSON SEO API не дождались.") from error
+        except urllib.error.URLError as error:
+            if isinstance(error.reason, socket.timeout):
+                raise TimeoutError("Ответа от JSON SEO API не дождались.") from error
+
+            raise NetworkError("Запрос к JSON SEO API не удался: {}.".format(error.reason)) from error
+        except OSError as error:
+            raise NetworkError("Запрос к JSON SEO API не удался: {}.".format(error)) from error
+
+    def _read(self, response) -> Response:
+        try:
+            raw = response.read()
+        except http.client.IncompleteRead as error:
+            raise IncompleteResponseError(self._incomplete_message(error)) from error
+        except socket.timeout as error:
+            raise TimeoutError("Ответа от JSON SEO API не дождались: тело пришло не целиком.") from error
+        except JsonSeoError:
+            # Наши собственные ошибки наследуют OSError и не должны попадать
+            # под общий перехват ниже.
+            raise
+        except OSError as error:
+            # Сброс соединения на середине тела: чистого EOF не было, но
+            # выдача всё равно уже собрана и оплачена.
+            raise IncompleteResponseError(
+                "Ответ от JSON SEO API пришёл не целиком: {}.".format(error)
+            ) from error
+
+        headers = {name: value for name, value in response.headers.items()}
+
+        return Response(response.status, headers, raw.decode("utf-8", errors="replace"))
+
+    def _incomplete_message(self, error: http.client.IncompleteRead) -> str:
+        # У обрыва chunked-ответа expected равен None: сколько обещали,
+        # неизвестно, и придумывать число нельзя.
+        if error.expected is None:
+            return "Ответ от JSON SEO API пришёл не целиком: получено {} байт, передача оборвалась.".format(
+                len(error.partial)
+            )
+
+        return "Ответ от JSON SEO API пришёл не целиком: получено {} из {} байт.".format(
+            len(error.partial), len(error.partial) + error.expected
+        )