yandex_py 0.0.1__tar.gz

yandex_py-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: yandex_py
+Version: 0.0.1
+Summary: Yandex API wrapper for Python built on top of httpx and pydantic
+Author-email: "Fiodar Y." <hi@fiodar.dev>
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0
+
+# yandex_py
+
+Python-клиент для Yandex Direct API на базе httpx и pydantic.
+
+## Установка
+
+```bash
+pip install yandex_py
+```
+
+## Использование
+
+```python
+from yandex_py import HTTPRequestSender, YDirectReport
+from yandex_py.reports.schemas import (
+    DateRangeType, FieldName, Page,
+    ReportDefinition, ReportRequest, ReportType, SelectionCriteria,
+)
+
+sender = HTTPRequestSender(token="your_token", client_login="your_login")
+
+request = ReportRequest(
+    params=ReportDefinition(
+        selection_criteria=SelectionCriteria(),
+        field_names=[FieldName.Date, FieldName.Clicks, FieldName.Cost],
+        report_name="my-report",
+        report_type=ReportType.CUSTOM_REPORT,
+        date_range_type=DateRangeType.LAST_7_DAYS,
+        page=Page(limit=10000),
+    )
+)
+
+async with sender:
+    report = YDirectReport(request=request, sender=sender)
+    rows = await report.fetch()
+```

yandex_py-0.0.1/README.md

@@ -0,0 +1,36 @@
+# yandex_py
+
+Python-клиент для Yandex Direct API на базе httpx и pydantic.
+
+## Установка
+
+```bash
+pip install yandex_py
+```
+
+## Использование
+
+```python
+from yandex_py import HTTPRequestSender, YDirectReport
+from yandex_py.reports.schemas import (
+    DateRangeType, FieldName, Page,
+    ReportDefinition, ReportRequest, ReportType, SelectionCriteria,
+)
+
+sender = HTTPRequestSender(token="your_token", client_login="your_login")
+
+request = ReportRequest(
+    params=ReportDefinition(
+        selection_criteria=SelectionCriteria(),
+        field_names=[FieldName.Date, FieldName.Clicks, FieldName.Cost],
+        report_name="my-report",
+        report_type=ReportType.CUSTOM_REPORT,
+        date_range_type=DateRangeType.LAST_7_DAYS,
+        page=Page(limit=10000),
+    )
+)
+
+async with sender:
+    report = YDirectReport(request=request, sender=sender)
+    rows = await report.fetch()
+```

yandex_py-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "yandex_py"
+description = "Yandex API wrapper for Python built on top of httpx and pydantic"
+authors = [
+    { name = "Fiodar Y.", email = "hi@fiodar.dev" },
+]
+
+version = "0.0.1"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.0",
+]
+
+[dependency-groups]
+dev = [
+    "ruff",
+    "pytest",
+    "pytest-asyncio",
+    "model-bakery",
+]
+
+[tool.pytest.ini_options]
+addopts = "-m 'not integration'"
+asyncio_mode = "auto"
+markers = [
+    "integration: tests against real Yandex Direct sandbox API (deselected by default)",
+]
+
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"

yandex_py-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yandex_py-0.0.1/tests/test_sandbox.py

@@ -0,0 +1,64 @@
+import os
+
+import pytest
+
+from yandex_py import HTTPRequestSender, YDirectReport
+from yandex_py.constants import SANDBOX_URL
+from yandex_py.reports.schemas import (
+    DateRangeType,
+    FieldName,
+    Page,
+    ReportDefinition,
+    ReportRequest,
+    ReportType,
+    SelectionCriteria,
+)
+
+
+@pytest.fixture
+def sender():
+    token = os.environ.get("YANDEX_DIRECT_API_TOKEN")
+    client_login = os.environ.get("YANDEX_DIRECT_CLIENT_LOGIN")
+
+    if not token:
+        pytest.skip("YANDEX_DIRECT_API_TOKEN не задан")
+    if not client_login:
+        pytest.skip("YANDEX_DIRECT_CLIENT_LOGIN не задан")
+
+    return HTTPRequestSender(token=token, client_login=client_login)
+
+
+@pytest.fixture
+def basic_request():
+    return ReportRequest(
+        params=ReportDefinition(
+            selection_criteria=SelectionCriteria(),
+            field_names=[FieldName.Date, FieldName.Clicks, FieldName.Impressions, FieldName.Cost],
+            report_name="sandbox-test",
+            report_type=ReportType.CUSTOM_REPORT,
+            date_range_type=DateRangeType.LAST_7_DAYS,
+            page=Page(limit=10),
+        )
+    )
+
+
+@pytest.mark.integration
+def test_fetch_report_sync(sender, basic_request):
+    report = YDirectReport(request=basic_request, sender=sender)
+    rows = report.fetch_sync()
+
+    assert isinstance(rows, list)
+    if rows:
+        assert FieldName.Date in rows[0]
+        assert FieldName.Clicks in rows[0]
+
+
+@pytest.mark.integration
+async def test_fetch_report_async(sender, basic_request):
+    report = YDirectReport(request=basic_request, sender=sender)
+    rows = await report.fetch()
+
+    assert isinstance(rows, list)
+    if rows:
+        assert FieldName.Date in rows[0]
+        assert FieldName.Clicks in rows[0]

yandex_py-0.0.1/yandex_py/__init__.py

@@ -0,0 +1,7 @@
+from .request_sender.request_sender import HTTPRequestSender
+from .reports.report import YDirectReport
+
+__all__ = [
+    "HTTPRequestSender",
+    "YDirectReport",
+]

yandex_py-0.0.1/yandex_py/constants.py

@@ -0,0 +1,9 @@
+SANDBOX_URL = "https://api-sandbox.direct.yandex.com/json/v5"
+PRODUCTION_URL = "https://api.direct.yandex.com/json/v5"
+
+BASE_URL = PRODUCTION_URL
+
+REPORTS_SERVICE = "reports"
+
+# Значение отсутствующих данных в TSV-ответе Яндекс.Директ
+MISSING_VALUE = "--"

yandex_py-0.0.1/yandex_py/reports/__init__.py

@@ -0,0 +1,8 @@
+from .parser import ReportRow, parse_report
+from .report import YDirectReport
+
+__all__ = [
+    "YDirectReport",
+    "parse_report",
+    "ReportRow",
+]

yandex_py-0.0.1/yandex_py/reports/parser.py

@@ -0,0 +1,35 @@
+import csv
+import io
+
+from yandex_py.constants import MISSING_VALUE
+from yandex_py.reports.schemas.fields import FieldName
+
+ReportRow = dict[FieldName, str | None]
+
+
+def parse_report(tsv: str) -> list[ReportRow]:
+    """
+    Парсит TSV-ответ API Яндекс.Директ в список словарей.
+
+    Ожидает ответ с skipReportHeader=true и skipReportSummary=true.
+    Значение '--' (отсутствующие данные) преобразуется в None.
+    """
+    reader = csv.DictReader(io.StringIO(tsv.strip()), delimiter="\t")
+
+    if reader.fieldnames is None:
+        return []
+
+    unknown = [f for f in reader.fieldnames if f not in FieldName._value2member_map_]
+    if unknown:
+        raise ValueError(f"Неизвестные поля в ответе: {unknown}")
+
+    rows: list[ReportRow] = []
+    for raw_row in reader:
+        row: ReportRow = {
+            FieldName(key): (None if value == MISSING_VALUE else value)
+            for key, value in raw_row.items()
+            if key is not None
+        }
+        rows.append(row)
+
+    return rows

yandex_py-0.0.1/yandex_py/reports/report.py

@@ -0,0 +1,63 @@
+import asyncio
+import time
+
+from yandex_py.constants import REPORTS_SERVICE
+from yandex_py.reports.parser import ReportRow, parse_report
+from yandex_py.reports.schemas.headers import AcceptLanguage, ProcessingMode
+from yandex_py.reports.schemas.request import ReportRequest
+from yandex_py.request_sender.request_sender import HTTPRequestSender 
+
+
+class YDirectReport:
+    def __init__(
+        self,
+        request: ReportRequest,
+        sender: HTTPRequestSender,
+        processing_mode: ProcessingMode = ProcessingMode.auto,
+        accept_language: AcceptLanguage = AcceptLanguage.ru,
+        max_retries: int = 100,
+    ):
+        self._request = request
+        self._sender = sender
+        self._headers = {
+            "Accept-Language": accept_language.value,
+            "processingMode": processing_mode.value,
+            "returnMoneyInMicros": "false",
+            "skipReportHeader": "true",
+            "skipColumnHeader": "false",
+            "skipReportSummary": "true",
+            "Accept-Encoding": "gzip",
+        }
+        self._max_retries = max_retries
+
+    def _body(self) -> dict:
+        return self._request.model_dump(by_alias=True, exclude_none=True)
+
+    def _handle_response(self, response) -> list[ReportRow] | None:
+        if response.status_code == 200:
+            return parse_report(response.text)
+        if response.status_code in (201, 202):
+            return None
+        raise RuntimeError(f"HTTP {response.status_code}: {response.text}")
+
+    async def fetch(self) -> list[ReportRow]:
+        body = self._body()
+        for _ in range(self._max_retries):
+            response = await self._sender.post_async(REPORTS_SERVICE, body, self._headers)
+            result = self._handle_response(response)
+            if result is not None:
+                return result
+            retry_in = int(response.headers.get("retryIn", 10))
+            await asyncio.sleep(retry_in)
+        raise TimeoutError(f"Отчёт не сформирован за {self._max_retries} попыток")
+
+    def fetch_sync(self) -> list[ReportRow]:
+        body = self._body()
+        for _ in range(self._max_retries):
+            response = self._sender.post(REPORTS_SERVICE, body, self._headers)
+            result = self._handle_response(response)
+            if result is not None:
+                return result
+            retry_in = int(response.headers.get("retryIn", 10))
+            time.sleep(retry_in)
+        raise TimeoutError(f"Отчёт не сформирован за {self._max_retries} попыток")

yandex_py-0.0.1/yandex_py/reports/schemas/__init__.py

@@ -0,0 +1,36 @@
+from .fields import FieldName
+from .headers import AcceptLanguage, Headers, ProcessingMode
+from .request import (
+    AttributionModel,
+    FilterItem,
+    FilterOperator,
+    OrderBy,
+    Page,
+    ReportDefinition,
+    ReportRequest,
+    ReportType,
+    SelectionCriteria,
+    SortOrder,
+    YesNo,
+)
+from .time_period import DateRangeType, TimePeriod
+
+__all__ = [
+    "FieldName",
+    "AcceptLanguage",
+    "Headers",
+    "ProcessingMode",
+    "AttributionModel",
+    "FilterItem",
+    "FilterOperator",
+    "OrderBy",
+    "Page",
+    "ReportDefinition",
+    "ReportRequest",
+    "ReportType",
+    "SelectionCriteria",
+    "SortOrder",
+    "YesNo",
+    "DateRangeType",
+    "TimePeriod",
+]

yandex_py-0.0.1/yandex_py/reports/schemas/fields.py

@@ -0,0 +1,93 @@
+from enum import Enum
+
+
+class FieldName(str, Enum):
+    AdFormat = "AdFormat"
+    AdGroupId = "AdGroupId"
+    AdGroupName = "AdGroupName"
+    AdId = "AdId"
+    AdUrl = "AdUrl"
+    AdNetworkType = "AdNetworkType"
+    Age = "Age"
+    AudienceTargetId = "AudienceTargetId"
+    AvgClickPosition = "AvgClickPosition"
+    AvgCpc = "AvgCpc"
+    AvgCpm = "AvgCpm"
+    AvgEffectiveBid = "AvgEffectiveBid"
+    AvgImpressionFrequency = "AvgImpressionFrequency"
+    AvgImpressionPosition = "AvgImpressionPosition"
+    AvgPageviews = "AvgPageviews"
+    AvgTrafficVolume = "AvgTrafficVolume"
+    AvgVideoCompleteCost = "AvgVideoCompleteCost"
+    AutotargetingBrandOption = "AutotargetingBrandOption"
+    BounceRate = "BounceRate"
+    Bounces = "Bounces"
+    CPV = "CPV"
+    CampaignId = "CampaignId"
+    CampaignName = "CampaignName"
+    CampaignType = "CampaignType"
+    CampaignUrlPath = "CampaignUrlPath"
+    CarrierType = "CarrierType"
+    ClickType = "ClickType"
+    Clicks = "Clicks"
+    ClientLogin = "ClientLogin"
+    ConversionRate = "ConversionRate"
+    Conversions = "Conversions"
+    Cost = "Cost"
+    CostPerConversion = "CostPerConversion"
+    Criteria = "Criteria"
+    CriteriaId = "CriteriaId"
+    CriteriaType = "CriteriaType"
+    Criterion = "Criterion"
+    CriterionId = "CriterionId"
+    CriterionType = "CriterionType"
+    Ctr = "Ctr"
+    Date = "Date"
+    Device = "Device"
+    DynamicTextAdTargetId = "DynamicTextAdTargetId"
+    ExternalNetworkName = "ExternalNetworkName"
+    Gender = "Gender"
+    GoalsRoi = "GoalsRoi"
+    ImpressionReach = "ImpressionReach"
+    ImpressionShare = "ImpressionShare"
+    Impressions = "Impressions"
+    IncomeGrade = "IncomeGrade"
+    Keyword = "Keyword"
+    LocationOfPresenceId = "LocationOfPresenceId"
+    LocationOfPresenceName = "LocationOfPresenceName"
+    MatchType = "MatchType"
+    MatchedKeyword = "MatchedKeyword"
+    MobilePlatform = "MobilePlatform"
+    Month = "Month"
+    Placement = "Placement"
+    Profit = "Profit"
+    PurchaseGoals = "PurchaseGoals"
+    PurchaseGoalsRoi = "PurchaseGoalsRoi"
+    PurchaseProfit = "PurchaseProfit"
+    PurchaseRevenue = "PurchaseRevenue"
+    Quarter = "Quarter"
+    Query = "Query"
+    Revenue = "Revenue"
+    RlAdjustmentId = "RlAdjustmentId"
+    Sessions = "Sessions"
+    Slot = "Slot"
+    SmartAdTargetId = "SmartAdTargetId"
+    SmartBannerFilterId = "SmartBannerFilterId"
+    TargetingCategory = "TargetingCategory"
+    TargetingLocationId = "TargetingLocationId"
+    TargetingLocationName = "TargetingLocationName"
+    VideoComplete = "VideoComplete"
+    VideoCompleteRate = "VideoCompleteRate"
+    VideoFirstQuartile = "VideoFirstQuartile"
+    VideoFirstQuartileRate = "VideoFirstQuartileRate"
+    VideoMidpoint = "VideoMidpoint"
+    VideoMidpointRate = "VideoMidpointRate"
+    VideoThirdQuartile = "VideoThirdQuartile"
+    VideoThirdQuartileRate = "VideoThirdQuartileRate"
+    VideoViews = "VideoViews"
+    VideoViewsRate = "VideoViewsRate"
+    Views = "Views"
+    Week = "Week"
+    WeightedCtr = "WeightedCtr"
+    WeightedImpressions = "WeightedImpressions"
+    Year = "Year"

yandex_py-0.0.1/yandex_py/reports/schemas/headers.py

@@ -0,0 +1,84 @@
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ProcessingMode(str, Enum):
+    """
+    Режим обработки отчета.
+    - auto — Сервер автоматически выбирает режим формирования отчета. Если отчет успешно сформирован в режиме онлайн,
+    он будет передан в теле ответа. Если отчет не может быть сформирован в режиме онлайн,
+    он ставится в очередь на формирование в режиме офлайн. Приложение должно поддерживать оба режима.
+    Отсутствие заголовка эквивалентно значению auto.
+
+
+    - offline — Отчет ставится в очередь на формирование в режиме офлайн. Проверять готовность отчета нужно
+    с помощью повторных запросов с теми же параметрами, см. подраздел Как проверить готовность офлайн-отчета.
+    Рекомендуемый интервал проверки указан в HTTP-заголовке ответа retryIn. Если формирование отчета завершено успешно,
+    сервер возвращает отчет в теле ответа.
+
+    - online — Отчет формируется в режиме онлайн. Если отчет успешно сформирован, он будет передан в
+    теле ответа. Если отчет не может быть сформирован в режиме онлайн, возвращается ошибка.
+
+
+    """
+
+    auto = "auto"
+    offline = "offline"
+    online = "online"
+
+
+class AcceptLanguage(str, Enum):
+    """
+    Язык, на котором возвращаются названия полей в отчете. Допустимые значения: ru, en. Если заголовок не указан, названия полей возвращаются на
+    русском языке.
+    """
+
+    ru = "ru"
+    en = "en"
+
+
+class Headers(BaseModel):
+    """
+    Заголовки запроса
+
+    В дополнение к заголовкам Authorization, Accept-Language, Client-Login можно указать следующие заголовки:
+
+    authorization
+    Заголовок Authorization должен содержать строку вида Bearer <токен>, где <токен> — это токен доступа, полученный в результате аутентификации. Подробнее см. раздел Получение токена доступа.
+
+    accept_language: "en"
+    Язык, на котором возвращаются названия полей в отчете. Допустимые значения: ru, en. Если заголовок не указан, названия полей возвращаются на
+    русском языке.
+
+    client_login
+    Логин рекламодателя — клиента рекламного агентства. Обязателен, если запрос осуществляется от имени агентства.
+
+    processing_mode: "auto"
+    Режим формирования отчета: online, offline или auto. Отсутствие заголовка эквивалентно значению auto. Описание режимов приведено в разделе Онлайн- и офлайн-отчет.
+
+    return_money_in_micros
+    Если заголовок указан, денежные значения в отчете возвращаются в валюте с точностью до двух знаков после запятой. Если не указан, денежные значения возвращаются в виде целых чисел — сумм в валюте, умноженных на 1 000 000.
+
+    skup_report_header: True
+    Не выводить в отчете строку с названием отчета и диапазоном дат.
+
+    skip_column_header: False
+    Не выводить в отчете строку с названиями полей.
+
+    skip_report_summary: True
+    Не выводить в отчете строку с количеством строк статистики.
+
+    accept_encoding: "gzip"
+    Если заголовок указан, применяется сжатие gzip.
+    """
+
+    authorization: str = Field(..., alias="Authorization")
+    client_login: str = Field(..., alias="Client-Login")
+    accept_language: AcceptLanguage = Field(AcceptLanguage.ru, alias="Accept-Language")
+    processing_mode: str = Field("auto", alias="processingMode")
+    return_money_in_micros: bool = Field(False, alias="returnMoneyInMicros")
+    skip_report_header: bool = Field(True, alias="skipReportHeader")
+    skip_column_header: bool = Field(False, alias="skipColumnHeader")
+    skip_report_summary: bool = Field(True, alias="skipReportSummary")
+    accept_encoding: str = Field("gzip", alias="Accept-Encoding")

yandex_py-0.0.1/yandex_py/reports/schemas/request.py

@@ -0,0 +1,105 @@
+from enum import Enum
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from yandex_py.reports.schemas.fields import FieldName
+from yandex_py.reports.schemas.time_period import DateRangeType
+
+
+class ReportType(str, Enum):
+    ACCOUNT_PERFORMANCE_REPORT = "ACCOUNT_PERFORMANCE_REPORT"
+    ADGROUP_PERFORMANCE_REPORT = "ADGROUP_PERFORMANCE_REPORT"
+    AD_PERFORMANCE_REPORT = "AD_PERFORMANCE_REPORT"
+    CAMPAIGN_PERFORMANCE_REPORT = "CAMPAIGN_PERFORMANCE_REPORT"
+    CRITERIA_PERFORMANCE_REPORT = "CRITERIA_PERFORMANCE_REPORT"
+    CUSTOM_REPORT = "CUSTOM_REPORT"
+    REACH_AND_FREQUENCY_PERFORMANCE_REPORT = "REACH_AND_FREQUENCY_PERFORMANCE_REPORT"
+    SEARCH_QUERY_PERFORMANCE_REPORT = "SEARCH_QUERY_PERFORMANCE_REPORT"
+
+
+class FilterOperator(str, Enum):
+    EQUALS = "EQUALS"
+    NOT_EQUALS = "NOT_EQUALS"
+    IN = "IN"
+    NOT_IN = "NOT_IN"
+    LESS_THAN = "LESS_THAN"
+    GREATER_THAN = "GREATER_THAN"
+    STARTS_WITH_IGNORE_CASE = "STARTS_WITH_IGNORE_CASE"
+    DOES_NOT_START_WITH_IGNORE_CASE = "DOES_NOT_START_WITH_IGNORE_CASE"
+    STARTS_WITH_ANY_IGNORE_CASE = "STARTS_WITH_ANY_IGNORE_CASE"
+    DOES_NOT_START_WITH_ALL_IGNORE_CASE = "DOES_NOT_START_WITH_ALL_IGNORE_CASE"
+
+
+class AttributionModel(str, Enum):
+    FC = "FC"          # first click
+    LC = "LC"          # last click
+    LSC = "LSC"        # last significant click
+    LYDC = "LYDC"      # last Yandex Direct click
+    FCCD = "FCCD"      # first click cross-device
+    LSCCD = "LSCCD"    # last significant click cross-device
+    LYDCCD = "LYDCCD"  # last Yandex Direct click cross-device
+    AUTO = "AUTO"
+
+
+class SortOrder(str, Enum):
+    ASCENDING = "ASCENDING"
+    DESCENDING = "DESCENDING"
+
+
+class YesNo(str, Enum):
+    YES = "YES"
+    NO = "NO"
+
+
+class FilterItem(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    field: FieldName = Field(..., serialization_alias="Field")
+    operator: FilterOperator = Field(..., serialization_alias="Operator")
+    values: list[str] = Field(..., serialization_alias="Values")
+
+
+class SelectionCriteria(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    date_from: Optional[str] = Field(None, serialization_alias="DateFrom")
+    date_to: Optional[str] = Field(None, serialization_alias="DateTo")
+    filter: Optional[list[FilterItem]] = Field(None, serialization_alias="Filter")
+
+
+class Page(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    limit: int = Field(..., serialization_alias="Limit")
+    offset: Optional[int] = Field(None, serialization_alias="Offset")
+
+
+class OrderBy(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    field: FieldName = Field(..., serialization_alias="Field")
+    sort_order: Optional[SortOrder] = Field(None, serialization_alias="SortOrder")
+
+
+class ReportDefinition(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    selection_criteria: SelectionCriteria = Field(..., serialization_alias="SelectionCriteria")
+    field_names: list[FieldName] = Field(..., serialization_alias="FieldNames")
+    report_name: str = Field(..., serialization_alias="ReportName")
+    report_type: ReportType = Field(..., serialization_alias="ReportType")
+    date_range_type: DateRangeType = Field(..., serialization_alias="DateRangeType")
+    format: Literal["TSV"] = Field("TSV", serialization_alias="Format")
+    include_vat: YesNo = Field(YesNo.NO, serialization_alias="IncludeVAT")
+    include_discount: YesNo = Field(YesNo.NO, serialization_alias="IncludeDiscount")
+    goals: Optional[list[str]] = Field(None, serialization_alias="Goals")
+    attribution_models: Optional[list[AttributionModel]] = Field(None, serialization_alias="AttributionModels")
+    page: Optional[Page] = Field(None, serialization_alias="Page")
+    order_by: Optional[list[OrderBy]] = Field(None, serialization_alias="OrderBy")
+
+
+class ReportRequest(BaseModel):
+    """Тело запроса к API отчётов Яндекс.Директ."""
+
+    params: ReportDefinition

yandex_py-0.0.1/yandex_py/reports/schemas/time_period.py

@@ -0,0 +1,48 @@
+from enum import Enum
+from datetime import date
+from typing import Optional
+
+from pydantic import BaseModel, model_validator
+
+
+class DateRangeType(str, Enum):
+    TODAY = "TODAY"
+    YESTERDAY = "YESTERDAY"
+    LAST_3_DAYS = "LAST_3_DAYS"
+    LAST_5_DAYS = "LAST_5_DAYS"
+    LAST_7_DAYS = "LAST_7_DAYS"
+    LAST_14_DAYS = "LAST_14_DAYS"
+    LAST_30_DAYS = "LAST_30_DAYS"
+    LAST_90_DAYS = "LAST_90_DAYS"
+    LAST_365_DAYS = "LAST_365_DAYS"
+    THIS_WEEK_MON_TODAY = "THIS_WEEK_MON_TODAY"
+    THIS_WEEK_SUN_TODAY = "THIS_WEEK_SUN_TODAY"
+    LAST_WEEK = "LAST_WEEK"
+    LAST_BUSINESS_WEEK = "LAST_BUSINESS_WEEK"
+    LAST_WEEK_SUN_SAT = "LAST_WEEK_SUN_SAT"
+    THIS_MONTH = "THIS_MONTH"
+    LAST_MONTH = "LAST_MONTH"
+    ALL_TIME = "ALL_TIME"
+    CUSTOM_DATE = "CUSTOM_DATE"
+    AUTO = "AUTO"
+
+
+class TimePeriod(BaseModel):
+    """
+    Период отчета.
+
+    При DateRangeType=CUSTOM_DATE необходимо указать date_from и date_to.
+    """
+
+    date_range_type: DateRangeType
+    date_from: Optional[date] = None
+    date_to: Optional[date] = None
+
+    @model_validator(mode="after")
+    def validate_custom_date(self) -> "TimePeriod":
+        if self.date_range_type == DateRangeType.CUSTOM_DATE:
+            if self.date_from is None or self.date_to is None:
+                raise ValueError("date_from и date_to обязательны при DateRangeType=CUSTOM_DATE")
+            if self.date_from > self.date_to:
+                raise ValueError("date_from не может быть позже date_to")
+        return self

yandex_py-0.0.1/yandex_py/request_sender/__init__.py

@@ -0,0 +1,3 @@
+from .request_sender import HTTPRequestSender
+
+__all__ = ["HTTPRequestSender"]

yandex_py-0.0.1/yandex_py/request_sender/request_sender.py

@@ -0,0 +1,66 @@
+import httpx
+
+from yandex_py.constants import BASE_URL
+
+
+class HTTPRequestSender:
+    def __init__(
+        self,
+        token: str,
+        client_login: str,
+        base_url: str = BASE_URL,
+        client: httpx.Client | None = None,
+        async_client: httpx.AsyncClient | None = None,
+    ):
+        self._base_url = base_url
+        self._auth_headers = {
+            "Authorization": f"Bearer {token}",
+            "Client-Login": client_login,
+        }
+        self._client = client or httpx.Client()
+        self._async_client = async_client or httpx.AsyncClient()
+
+    def _url(self, service: str) -> str:
+        return f"{self._base_url}/{service}"
+
+    def post(
+        self,
+        service: str,
+        body: dict,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._client.post(
+            self._url(service),
+            json=body,
+            headers={**self._auth_headers, **(headers or {})},
+        )
+
+    async def post_async(
+        self,
+        service: str,
+        body: dict,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return await self._async_client.post(
+            self._url(service),
+            json=body,
+            headers={**self._auth_headers, **(headers or {})},
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    async def aclose(self) -> None:
+        await self._async_client.aclose()
+
+    def __enter__(self) -> "HTTPRequestSender":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "HTTPRequestSender":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.aclose()

yandex_py-0.0.1/yandex_py.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: yandex_py
+Version: 0.0.1
+Summary: Yandex API wrapper for Python built on top of httpx and pydantic
+Author-email: "Fiodar Y." <hi@fiodar.dev>
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0
+
+# yandex_py
+
+Python-клиент для Yandex Direct API на базе httpx и pydantic.
+
+## Установка
+
+```bash
+pip install yandex_py
+```
+
+## Использование
+
+```python
+from yandex_py import HTTPRequestSender, YDirectReport
+from yandex_py.reports.schemas import (
+    DateRangeType, FieldName, Page,
+    ReportDefinition, ReportRequest, ReportType, SelectionCriteria,
+)
+
+sender = HTTPRequestSender(token="your_token", client_login="your_login")
+
+request = ReportRequest(
+    params=ReportDefinition(
+        selection_criteria=SelectionCriteria(),
+        field_names=[FieldName.Date, FieldName.Clicks, FieldName.Cost],
+        report_name="my-report",
+        report_type=ReportType.CUSTOM_REPORT,
+        date_range_type=DateRangeType.LAST_7_DAYS,
+        page=Page(limit=10000),
+    )
+)
+
+async with sender:
+    report = YDirectReport(request=request, sender=sender)
+    rows = await report.fetch()
+```

yandex_py-0.0.1/yandex_py.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+tests/test_sandbox.py
+yandex_py/__init__.py
+yandex_py/constants.py
+yandex_py.egg-info/PKG-INFO
+yandex_py.egg-info/SOURCES.txt
+yandex_py.egg-info/dependency_links.txt
+yandex_py.egg-info/requires.txt
+yandex_py.egg-info/top_level.txt
+yandex_py/reports/__init__.py
+yandex_py/reports/parser.py
+yandex_py/reports/report.py
+yandex_py/reports/schemas/__init__.py
+yandex_py/reports/schemas/fields.py
+yandex_py/reports/schemas/headers.py
+yandex_py/reports/schemas/request.py
+yandex_py/reports/schemas/time_period.py
+yandex_py/request_sender/__init__.py
+yandex_py/request_sender/request_sender.py

yandex_py-0.0.1/yandex_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

yandex_py-0.0.1/yandex_py.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.28.1
+pydantic>=2.0

yandex_py-0.0.1/yandex_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+yandex_py