yandex-audience-cli 0.0.1__py3-none-any.whl

yac/__init__.py

@@ -0,0 +1,5 @@
+"""yac — CLI для Yandex Audience API."""
+
+from .cli import app, __version__
+
+__all__ = ["app", "__version__"]

yac/__main__.py

@@ -0,0 +1,6 @@
+"""Запуск пакета как модуля: ``python -m yac ...``."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

yac/api/__init__.py

@@ -0,0 +1 @@
+"""Слой ресурсов API — HTTP-классы по группам эндпоинтов."""

yac/api/accounts.py

@@ -0,0 +1,15 @@
+"""Ресурс «Аккаунты» — 1 эндпоинт."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..registry import GROUP_ACCOUNTS
+from ..base import Resource
+
+
+class Accounts(Resource):
+    group = GROUP_ACCOUNTS
+
+    def list(self, *, pretty: bool = False) -> Any:
+        return self._call("list", pretty=pretty)

yac/api/delegates.py

@@ -0,0 +1,33 @@
+"""Ресурс «Представители» (delegates) — 3 эндпоинта."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ..registry import GROUP_DELEGATES
+from ..base import Resource
+
+
+class Delegates(Resource):
+    group = GROUP_DELEGATES
+
+    def list(self, *, pretty: bool = False) -> Any:
+        return self._call("list", pretty=pretty)
+
+    def add(
+        self,
+        user_login: str,
+        *,
+        perm: Optional[str] = None,
+        comment: Optional[str] = None,
+        pretty: bool = False,
+    ) -> Any:
+        delegate: dict = {"user_login": user_login}
+        if perm is not None:
+            delegate["perm"] = perm
+        if comment is not None:
+            delegate["comment"] = comment
+        return self._call("add", json={"delegate": delegate}, pretty=pretty)
+
+    def remove(self, user_login: str, *, pretty: bool = False) -> Any:
+        return self._call("remove", params={"user_login": user_login}, pretty=pretty)

yac/api/grants.py

@@ -0,0 +1,36 @@
+"""Ресурс «Разрешения» (grants) — 3 эндпоинта."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ..registry import GROUP_GRANTS
+from ..base import Resource
+
+
+class Grants(Resource):
+    group = GROUP_GRANTS
+
+    def list(self, segment_id: int, *, pretty: bool = False) -> Any:
+        return self._call("list", id=segment_id, pretty=pretty)
+
+    def add(
+        self,
+        segment_id: int,
+        user_login: str,
+        *,
+        permission: Optional[str] = None,
+        comment: Optional[str] = None,
+        pretty: bool = False,
+    ) -> Any:
+        grant: dict = {"user_login": user_login}
+        if permission is not None:
+            grant["permission"] = permission
+        if comment is not None:
+            grant["comment"] = comment
+        return self._call("add", id=segment_id, json={"grant": grant}, pretty=pretty)
+
+    def remove(self, segment_id: int, user_login: str, *, pretty: bool = False) -> Any:
+        return self._call(
+            "remove", id=segment_id, params={"user_login": user_login}, pretty=pretty
+        )

yac/api/pixels.py

@@ -0,0 +1,29 @@
+"""Ресурс «Пиксели» — 5 эндпоинтов."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..registry import GROUP_PIXELS
+from ..base import Resource
+
+
+class Pixels(Resource):
+    group = GROUP_PIXELS
+
+    def list(self, *, pretty: bool = False) -> Any:
+        return self._call("list", pretty=pretty)
+
+    def create(self, name: str, *, pretty: bool = False) -> Any:
+        return self._call("create", json={"pixel": {"name": name}}, pretty=pretty)
+
+    def update(self, pixel_id: int, name: str, *, pretty: bool = False) -> Any:
+        return self._call(
+            "update", id=pixel_id, json={"pixel": {"name": name}}, pretty=pretty
+        )
+
+    def delete(self, pixel_id: int, *, pretty: bool = False) -> Any:
+        return self._call("delete", id=pixel_id, pretty=pretty)
+
+    def undelete(self, pixel_id: int, *, pretty: bool = False) -> Any:
+        return self._call("undelete", id=pixel_id, pretty=pretty)

yac/api/segments.py

@@ -0,0 +1,135 @@
+"""Ресурс «Сегменты» — 16 эндпоинтов.
+
+Имена методов совпадают с ``op`` соответствующих эндпоинтов в registry.py.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from ..registry import GROUP_SEGMENTS
+from ..base import Resource
+
+
+class Segments(Resource):
+    group = GROUP_SEGMENTS
+
+    # -- чтение -------------------------------------------------------------
+    def list(
+        self,
+        *,
+        pixel: Optional[int] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        pretty: bool = False,
+    ) -> Any:
+        params: dict = {}
+        if pixel is not None:
+            params["pixel"] = pixel
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        return self._call("list", params=params or None, pretty=pretty)
+
+    # -- создание сегментов по типам ---------------------------------------
+    def create_pixel(self, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call("create_pixel", json={"segment": segment}, pretty=pretty)
+
+    def create_lookalike(self, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call("create_lookalike", json={"segment": segment}, pretty=pretty)
+
+    def create_metrika(self, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call("create_metrika", json={"segment": segment}, pretty=pretty)
+
+    def create_appmetrica(self, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call("create_appmetrica", json={"segment": segment}, pretty=pretty)
+
+    def create_geo(self, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call("create_geo", json={"segment": segment}, pretty=pretty)
+
+    def create_geo_polygon(self, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call(
+            "create_geo_polygon", json={"segment": segment}, pretty=pretty
+        )
+
+    # -- загрузка файлов ----------------------------------------------------
+    def upload_file(self, file_path: str, *, pretty: bool = False) -> Any:
+        return self._upload("upload_file", file_path, pretty=pretty)
+
+    def upload_csv_file(self, file_path: str, *, pretty: bool = False) -> Any:
+        return self._upload("upload_csv_file", file_path, pretty=pretty)
+
+    def _upload(self, op: str, file_path: str, *, pretty: bool) -> Any:
+        path = Path(file_path)
+        with path.open("rb") as fh:
+            files = {"file": (path.name, fh)}
+            return self._call(op, files=files, pretty=pretty)
+
+    # -- изменение координат гео-окружности --------------------------------
+    def update_geo_points(
+        self, segment_id: int, points: list, *, pretty: bool = False
+    ) -> Any:
+        return self._call(
+            "update_geo_points", id=segment_id, json={"points": points}, pretty=pretty
+        )
+
+    # -- изменение данных загруженного сегмента (multipart) ----------------
+    def modify_data(
+        self,
+        segment_id: int,
+        file_path: str,
+        modification_type: str,
+        *,
+        check_size: Optional[bool] = None,
+        pretty: bool = False,
+    ) -> Any:
+        params: dict = {"modification_type": modification_type}
+        if check_size is not None:
+            params["check_size"] = str(check_size).lower()
+        path = Path(file_path)
+        with path.open("rb") as fh:
+            files = {"file": (path.name, fh)}
+            return self._call(
+                "modify_data", id=segment_id, params=params, files=files, pretty=pretty
+            )
+
+    # -- подтверждение/сохранение загруженного сегмента --------------------
+    def confirm(
+        self,
+        segment_id: int,
+        segment: dict,
+        *,
+        check_size: Optional[bool] = None,
+        pretty: bool = False,
+    ) -> Any:
+        params = (
+            {"check_size": str(check_size).lower()} if check_size is not None else None
+        )
+        return self._call(
+            "confirm",
+            id=segment_id,
+            params=params,
+            json={"segment": segment},
+            pretty=pretty,
+        )
+
+    def confirm_client_id(
+        self, segment_id: int, segment: dict, *, pretty: bool = False
+    ) -> Any:
+        return self._call(
+            "confirm_client_id", id=segment_id, json={"segment": segment}, pretty=pretty
+        )
+
+    # -- изменение / удаление / переобработка ------------------------------
+    def update(self, segment_id: int, segment: dict, *, pretty: bool = False) -> Any:
+        return self._call(
+            "update", id=segment_id, json={"segment": segment}, pretty=pretty
+        )
+
+    def delete(self, segment_id: int, *, pretty: bool = False) -> Any:
+        return self._call("delete", id=segment_id, pretty=pretty)
+
+    def reprocess(self, segment_id: int, *, pretty: bool = False) -> Any:
+        return self._call("reprocess", id=segment_id, pretty=pretty)

yac/base.py

@@ -0,0 +1,44 @@
+"""Базовый класс ресурса.
+
+Связывает группу ресурса с реестром эндпоинтов и предоставляет хелпер
+:meth:`Resource._call`, который берёт описание эндпоинта из registry.py
+(HTTP-метод и путь) — так слой ресурсов не дублирует строки путей.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from . import registry
+from .client import Client
+
+
+class Resource:
+    """Базовый ресурс. Подклассы задают ``group``."""
+
+    group: str = ""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def _call(
+        self,
+        op: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+        files: Optional[Mapping[str, Any]] = None,
+        pretty: bool = False,
+        **path_params: object,
+    ) -> Any:
+        """Выполнить вызов эндпоинта ``self.group``/``op`` из реестра."""
+        ep = registry.get(self.group, op)
+        path = registry.render_path(ep, **path_params)
+        return self._client.request(
+            ep.method,
+            path,
+            params=params,
+            json=json,
+            files=files,
+            pretty=pretty,
+        )

yac/cli.py

@@ -0,0 +1,88 @@
+"""yac — CLI для Yandex Audience API.
+
+Точка входа и сборка корневого Typer-приложения. Зеркалит структуру
+HTTP API Яндекс.Аудиторий «1 в 1»:
+версия (v1) → пространство (management) → 5 ресурсных групп
+(segments, grants, pixels, accounts, delegates).
+
+Единый источник правды по эндпоинтам — registry.py.
+Запуск: ``yac ...`` (консольный скрипт) или ``python -m yac ...``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from .config import ENV_BASE_URL, ENV_TOKEN
+from .context import AppState, get_state
+
+from .commands import segments as segments_cli
+from .commands import grants as grants_cli
+from .commands import pixels as pixels_cli
+from .commands import accounts as accounts_cli
+from .commands import delegates as delegates_cli
+
+__version__ = "0.0.1"
+
+app = typer.Typer(
+    name="yac",
+    help="CLI для Yandex Audience API — структура API 1:1 (5 групп, 28 эндпоинтов).",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+# Под-приложения = ресурсные группы API.
+app.add_typer(segments_cli.app, name="segments")
+app.add_typer(grants_cli.app, name="grants")
+app.add_typer(pixels_cli.app, name="pixels")
+app.add_typer(accounts_cli.app, name="accounts")
+app.add_typer(delegates_cli.app, name="delegates")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"yandex-audience-cli {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    token: Optional[str] = typer.Option(
+        None, "--token", envvar=ENV_TOKEN, help="OAuth-токен Яндекса."
+    ),
+    base_url: Optional[str] = typer.Option(
+        None,
+        "--base-url",
+        envvar=ENV_BASE_URL,
+        help="Базовый URL API (для тестов/прокси).",
+    ),
+    output: str = typer.Option(
+        "json", "--output", "-o", help="Формат вывода: json | table."
+    ),
+    pretty: bool = typer.Option(
+        False, "--pretty", help="Запрашивать pretty-ответ у API."
+    ),
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Версия CLI.",
+    ),
+) -> None:
+    """Общие опции применяются ко всем командам."""
+    state = get_state(ctx)
+    state.token = token
+    state.base_url = base_url
+    state.output = output
+    state.pretty = pretty
+
+
+__all__ = ["app", "AppState", "__version__"]
+
+
+if __name__ == "__main__":
+    app()

yac/client.py

@@ -0,0 +1,204 @@
+"""HTTP-клиент к Yandex Audience API поверх httpx.
+
+Отвечает за единые правила транспорта:
+- заголовок ``Authorization: OAuth <token>`` (именно OAuth, не Bearer);
+- сборку URL относительно ``.../v1/management``;
+- параметр ``pretty`` для форматированного ответа;
+- загрузку файлов через ``multipart/form-data``;
+- разбор ошибок API и отдельную обработку HTTP 429 (превышение квот).
+
+Слой ресурсов (<group>_api.py) пользуется только методами этого класса
+и не знает деталей транспорта.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from .config import Config
+
+DEFAULT_TIMEOUT = 30.0
+
+#: Повторных попыток после HTTP 429 (итого попыток: RETRY_429_ATTEMPTS + 1).
+RETRY_429_ATTEMPTS = 1
+#: Пауза перед повтором, если API не отдал заголовок Retry-After.
+RETRY_429_DEFAULT_WAIT = 60.0
+
+
+def _sleep(seconds: float) -> None:
+    """Точка подмены в тестах (реальный сон — time.sleep)."""
+    time.sleep(seconds)
+
+
+def _retry_wait(response: httpx.Response) -> float:
+    """Пауза до повтора: Retry-After от API, иначе дефолт. Мусорный заголовок не роняет."""
+    raw = response.headers.get("Retry-After")
+    if raw:
+        try:
+            return max(float(raw), 0.0)
+        except ValueError:
+            pass
+    return RETRY_429_DEFAULT_WAIT
+    return RETRY_429_DEFAULT_WAIT
+
+
+class APIError(RuntimeError):
+    """Ошибка, вернувшаяся от API (или транспортная)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        payload: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+class RateLimitError(APIError):
+    """HTTP 429 — превышены квоты запросов."""
+
+
+class Client:
+    """Тонкий клиент над httpx.Client с авторизацией Audience API."""
+
+    def __init__(
+        self,
+        config: Config,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.config = config
+        self._http = httpx.Client(
+            base_url=config.management_url,
+            headers={"Authorization": f"OAuth {config.token}"},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # -- контекстный менеджер ------------------------------------------------
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # -- основной примитив ---------------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+        files: Optional[Mapping[str, Any]] = None,
+        pretty: bool = False,
+    ) -> Any:
+        """Выполнить запрос и вернуть разобранный JSON (или None).
+
+        ``path`` задаётся относительно пространства management,
+        например ``"segments"`` или ``"segment/123/grants"``.
+        """
+        query = dict(params or {})
+        if pretty:
+            query["pretty"] = 1
+
+        # HTTP 429 — не доменный отказ, а квотный голод: повтор безопасен (запрос
+        # отклонён до обработки), поэтому ретраим с паузой Retry-After/60с —
+        # иначе любой скрипт >10 записей/мин падает на 11-й. Пауза печатается в
+        # stderr, чтобы ожидание не было молчаливым.
+        response = self._send(method, path, query, json, files)
+        for attempt in range(RETRY_429_ATTEMPTS):
+            if response.status_code != 429:
+                break
+            wait = _retry_wait(response)
+            print(
+                f"HTTP 429: пауза {wait:g}с и повтор (осталось попыток: "
+                f"{RETRY_429_ATTEMPTS - attempt})…",
+                file=sys.stderr,
+            )
+            _sleep(wait)
+            response = self._send(method, path, query, json, files)
+
+        return self._handle(response)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        query: Mapping[str, Any],
+        json: Any,
+        files: Optional[Mapping[str, Any]],
+    ) -> httpx.Response:
+        try:
+            return self._http.request(
+                method.upper(),
+                path.lstrip("/"),
+                params=query or None,
+                json=json,
+                files=files,
+            )
+        except httpx.HTTPError as exc:  # сетевые/таймаут-ошибки
+            raise APIError(f"Сетевая ошибка: {exc}") from exc
+
+    # -- разбор ответа -------------------------------------------------------
+    @staticmethod
+    def _handle(response: httpx.Response) -> Any:
+        if response.status_code == 429:
+            raise RateLimitError(
+                "Превышена квота запросов (HTTP 429). "
+                "Лимиты: 30 req/s по IP, 5000 req/day по логину, "
+                "запись 10/мин · 100/час · 500/день.",
+                status_code=429,
+                payload=_safe_json(response),
+            )
+
+        if response.is_success:
+            if not response.content:
+                return None
+            return _safe_json(response)
+
+        payload = _safe_json(response)
+        message = _extract_error_message(payload) or response.text or "Ошибка API"
+        raise APIError(
+            f"HTTP {response.status_code}: {message}",
+            status_code=response.status_code,
+            payload=payload,
+        )
+
+
+def _safe_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def _extract_error_message(payload: Any) -> Optional[str]:
+    """Достать человекочитаемое сообщение из тела ошибки Audience API."""
+    if not isinstance(payload, Mapping):
+        return None
+    # Возможные формы: {"errors": [{"text": ...}]} или {"message": ...}
+    errors = payload.get("errors")
+    if isinstance(errors, list) and errors:
+        texts = [
+            str(e.get("text") or e.get("message") or e)
+            for e in errors
+            if isinstance(e, Mapping)
+        ]
+        if texts:
+            return "; ".join(texts)
+    for key in ("message", "error", "text"):
+        if payload.get(key):
+            return str(payload[key])
+    return None

yac/commands/__init__.py

@@ -0,0 +1 @@
+"""Слой CLI — Typer-команды по ресурсным группам."""

yac/commands/accounts.py

@@ -0,0 +1,20 @@
+"""Команды группы ``accounts``."""
+
+from __future__ import annotations
+
+import typer
+
+from ..api.accounts import Accounts
+from ..render import render
+from ..context import get_state, handle_errors
+
+app = typer.Typer(
+    help="Аккаунты, где вы — представитель (1 эндпоинт).", no_args_is_help=True
+)
+
+
+@app.command("list")
+@handle_errors
+def list_(ctx: typer.Context) -> None:
+    """Список аккаунтов."""
+    render(ctx, Accounts(get_state(ctx).client()).list(pretty=get_state(ctx).pretty))

yac/commands/delegates.py

@@ -0,0 +1,52 @@
+"""Команды группы ``delegates`` (представители)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..api.delegates import Delegates
+from ..render import render
+from ..context import get_state, handle_errors
+
+app = typer.Typer(
+    help="Управление представителями (3 эндпоинта).", no_args_is_help=True
+)
+
+
+def _delegates(ctx: typer.Context) -> Delegates:
+    return Delegates(get_state(ctx).client())
+
+
+@app.command("list")
+@handle_errors
+def list_(ctx: typer.Context) -> None:
+    """Список представителей."""
+    render(ctx, _delegates(ctx).list(pretty=get_state(ctx).pretty))
+
+
+@app.command("add")
+@handle_errors
+def add(
+    ctx: typer.Context,
+    user_login: str = typer.Option(..., "--user-login"),
+    perm: Optional[str] = typer.Option(None, "--perm", help="view | edit (опц.)."),
+    comment: Optional[str] = typer.Option(None, "--comment"),
+) -> None:
+    """Добавить представителя."""
+    render(
+        ctx,
+        _delegates(ctx).add(
+            user_login, perm=perm, comment=comment, pretty=get_state(ctx).pretty
+        ),
+    )
+
+
+@app.command("remove")
+@handle_errors
+def remove(
+    ctx: typer.Context, user_login: str = typer.Option(..., "--user-login")
+) -> None:
+    """Удалить представителя."""
+    render(ctx, _delegates(ctx).remove(user_login, pretty=get_state(ctx).pretty))