Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,27 @@ jobs:
run: |
python -m pip install --upgrade pip
pip install -e ".[dev]"
- name: Version matches swagger
# Версия пакета == info.version из openapi.json == avito_ads.API_VERSION == __version__.
run: |
python - <<'EOF'
import json
import sys
from importlib.metadata import version

import avito_ads

versions = {
"package metadata": version("avito-ads"),
"avito_ads.__version__": avito_ads.__version__,
"avito_ads.API_VERSION": avito_ads.API_VERSION,
"openapi.json info.version": json.load(open("openapi.json", encoding="utf-8"))["info"]["version"],
}
for name, value in versions.items():
print(f"{name}: {value}")
if len(set(versions.values())) != 1:
sys.exit("Версии расходятся")
EOF
- name: Ruff
run: ruff check .
- name: Pytest
Expand Down
57 changes: 56 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,62 @@
Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.0.0/),
проект придерживается [семантического версионирования](https://semver.org/lang/ru/).

## [1.0.0]
## [1.4.0] — 2026-11-13

Синхронизация с публичным swagger 1.4.0. С этой версии **версия SDK = версия публичного API (swagger)**.

### Breaking
- Пользовательский User-Agent теперь дополняется меткой SDK, а не заменяет её:
`with_user_agent("my-app/1.0")` даёт `my-app/1.0 avito-ads-sdk-python3/1.4.0`. Метка по
умолчанию сменилась с `avito-ads-python/0.1.0` на `avito-ads-sdk-python3/<версия>`.
- `account.create_sandbox_account`: `legal_type` (`"ul"`/`"ip"`) обязателен по swagger — без него
или с неизвестным значением бросается `ValidationError` до запроса.
- Изменения swagger, ломающие клиентов API: значение `weekly` у `budgetFrequency` группы удалено;
входные `frequencyCount`/`frequencyPeriod` при создании группы заменены на `frequencyRules`
(метода создания группы в SDK нет, в ответе группы старые поля сохранены).

### Added
- Константы `avito_ads.API_VERSION` (`"1.4.0"`), `avito_ads.__version__`, `avito_ads.DEFAULT_USER_AGENT`;
`Configuration.effective_user_agent`. `openapi.json` (swagger 1.4.0) в корне репозитория, проверка в CI:
версия пакета == `info.version` == `API_VERSION`.
- `ConflictError` (HTTP 409, наследник `ApiError`) — конфликт версий группы в `groups.change_budget` и
`groups.change_price`.
- Денежные поля в копейках: `Balance.balance_kopeks`, `bonus_balance_kopeks`; `StatsData.spend_kopeks`,
`spend_bonus_kopeks`; `Campaign.budget_kopeks`; `Group.budget_kopeks`, `price_kopeks`.
- Кампания: `budget_frequency` (`daily`/`entirePeriod`/`mixed`), `performance_additional_agreement_id`.
- `status_reasons` (список кодов, `[]` без причин) и `top_status_reason` (`""` без причины) у кампании,
группы и креатива.
- Статусы кампании `will_launch_soon`, `partially_active`, `will_stop_soon`, `pausing`, `unpausing`;
статусы креатива `will_launch_soon`, `pausing`, `unpausing`.
- Группа: `frequency_rules` (`FrequencyRule.count`/`period`), `budget_frequency`, `actions`,
`activity_schedule`, `audience_type`, `format`, `pace`, `period_start_at`, `period_end_at`,
`period_timezone`, `price_control`, `schedule_type`, `start_asap`, `user_id`, `targeting_*_ids` (8 полей).
- Креатив: `kktu_fields` (`KKTUFieldValue.key`/`value`), `landing_id`, `origin_url`, `preview_url`, `user_id`.
- Договор: `is_agent_acting_for_publisher`, `is_creative_reporter`.
- Sandbox: `CreatedAccount.warnings`; ответ `207` (аккаунт создан частично) — успех.
- Перечисления `CampaignBudgetFrequency`, `BudgetFrequency`, `FrequencyPeriod`, `GroupFormat`,
`AudienceType`, `Paces`, `GroupPriceControl`, `ScheduleType`.
- Типы статистики `CampaignStatistic`, `GroupStatistic`, `CreativeStatistic` (наследники `EntityStatistic`).

### Changed
- Явная политика неизвестных значений: статусы, `budget_frequency`, коды причин и прочие значения
перечислений в ответах возвращаются строками как есть; enum проверяются только на входе.
- `statistics.groups()`/`creatives()` возвращают `GroupStatistic`/`CreativeStatistic`,
`CampaignStatisticResult.campaign` — `CampaignStatistic`.
- `Campaign.budget`/`budget_kopeks` по swagger nullable: тип `Optional[int]` прежний, теперь задокументировано,
что `None` у mixed-кампании (бюджета нет) не равен `0` у пустой кампании.
- `create_sandbox_account`: `actual_address` может быть `None` (API возьмёт юридический адрес).
- Исправлена ошибка mypy в `auth/storage.py` (импорт `Protocol` напрямую из `typing`).

### Deprecated
- `Creative.legal_info` — используйте `kktu_fields` (swagger 1.2.0).
- `Group.frequency_count`/`frequency_period` — используйте `frequency_rules`.
- `EntityStatistic.payment_model`/`campaign_type` (только у `CampaignStatistic`) и
`EntityStatistic.group_id` (только у `CreativeStatistic`).

Устаревшие поля не удалены: при чтении выдаётся `DeprecationWarning`.

## [0.1.0]

### Added
- Python SDK для API Авито Реклама в **двух режимах работы**: синхронном
Expand Down
110 changes: 107 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,20 @@ Python SDK для API **Авито Реклама** (Avito Ads API).

Библиотека закрывает все основные методы API: аккаунт и баланс, дочерние аккаунты и переводы средств, рекламодателей, договоры, кампании, группы объявлений, креативы, статистику и управление пользователями. Поддерживаются **два режима работы — синхронный и асинхронный** — с одинаковым набором методов. Транспорт построен на [httpx](https://www.python-httpx.org/), авторизация — OAuth2 `client_credentials` с автоматическим обновлением и кэшированием токена, а также повторными попытками при ошибках `429` и `5xx`.

## Версия SDK и API

Версия SDK = версия публичного API (swagger), под которую он собран. Текущая — **1.4.0**:

```python
import avito_ads

print(avito_ads.__version__) # "1.4.0" — версия пакета
print(avito_ads.API_VERSION) # "1.4.0" — версия swagger (info.version в openapi.json)
```

Спецификация лежит в корне репозитория (`openapi.json`); CI проверяет, что версия пакета,
`API_VERSION` и `info.version` совпадают.

## Возможности

- Поддержка **Python 3.8+**.
Expand Down Expand Up @@ -108,7 +122,7 @@ config = (
.with_max_retries(4) # макс. число повторов при 429/5xx
.with_retry_base_delay(1000) # базовая задержка повтора, мс
.with_token_leeway(60) # запас на досрочное обновление токена, сек
.with_user_agent("my-app/1.0") # значение заголовка User-Agent
.with_user_agent("my-app/1.0") # свой User-Agent; метка SDK дописывается
)
```

Expand All @@ -123,6 +137,21 @@ config = config.with_http_client(httpx.Client(http2=True))
config = config.with_async_client(httpx.AsyncClient(http2=True))
```

### User-Agent

По умолчанию SDK отправляет `User-Agent: avito-ads-sdk-python3/<версия>` — и в запросах к API, и в
запросе токена. По этой метке Авито видит, что запрос пришёл из Python SDK.

Свой `User-Agent` не заменяет метку, а дополняется ею через пробел:

```python
config = config.with_user_agent("my-app/1.0")
print(config.effective_user_agent) # my-app/1.0 avito-ads-sdk-python3/1.4.0
```

Если в вашем значении метка `avito-ads-sdk-python3/` уже есть (без учёта регистра), второй раз она
не дописывается.

### Окружения

| Окружение | Базовый адрес API |
Expand Down Expand Up @@ -248,6 +277,68 @@ client.groups.change_budget(group_id=555, budget=100000)
client.groups.change_price(group_id=555, price=25)
```

#### Причины статуса

У кампании, группы и креатива есть `status_reasons` — все коды причин текущего статуса (`[]`, если
причин нет) и `top_status_reason` — главная причина (`""`, если не определена). API может добавлять
новые коды, поэтому обрабатывайте неизвестные значения:

```python
from avito_ads import CampaignStatus

for campaign in client.campaigns.iterate():
if campaign.status == CampaignStatus.PAUSED and campaign.top_status_reason:
print(campaign.id, "на паузе:", campaign.top_status_reason, campaign.status_reasons)
```

Статусы, `budget_frequency` и другие значения перечислений модели возвращают **строкой как есть**:
новое значение, появившееся в API, не вызывает ошибку. Перечисления из `avito_ads.enums` нужны для
сравнения и для проверки входных значений.

#### Бюджет кампании (может отсутствовать)

`Campaign.budget` и `budget_kopeks` — сумма бюджетов групп, `Optional[int]`. Если в кампании есть
группы и с дневным бюджетом, и с бюджетом на весь период (`budget_frequency == "mixed"`), бюджета
нет и поле равно `None`; у пустой кампании — `0`. Не подменяйте `None` нулём:

```python
from avito_ads import CampaignBudgetFrequency

if campaign.budget_kopeks is None:
print("Бюджет не суммируется:", campaign.budget_frequency) # mixed
else:
print("Бюджет:", campaign.budget_kopeks / 100, "₽")
```

Денежные поля в копейках есть также у баланса (`balance_kopeks`, `bonus_balance_kopeks`),
статистики (`spend_kopeks`, `spend_bonus_kopeks`) и группы (`budget_kopeks`, `price_kopeks`).

#### Частотные ограничения группы

```python
for group in client.groups.iterate():
for rule in group.frequency_rules: # FrequencyRule: count показов за period
print(group.id, rule.count, rule.period) # period: no_limit / day / week / month
```

`Group.frequency_count`/`frequency_period` оставлены для совместимости (соответствуют первому
правилу) и помечены устаревшими: при чтении выдаётся `DeprecationWarning`. Так же помечен
`Creative.legal_info` — используйте `Creative.kktu_fields`.

#### Конфликт при изменении группы (409)

Если группу изменили параллельно, `change_budget`/`change_price` бросают `ConflictError`
(наследник `ApiError`). Перечитайте группу и повторите изменение:

```python
from avito_ads.exceptions import ConflictError

try:
client.groups.change_budget(group_id=555, budget=100000)
except ConflictError:
... # перечитать группу и повторить
```

### Статистика

Период не может превышать 100 дней; даты — в формате `YYYY-MM-DD`. Эти ограничения проверяются на стороне клиента.
Expand Down Expand Up @@ -313,14 +404,17 @@ from avito_ads.enums import CampaignStatus

f = (
CampaignsFilter()
.statuses([CampaignStatus.ACTIVE.value])
.statuses([CampaignStatus.ACTIVE.value, CampaignStatus.WILL_STOP_SOON.value])
.contract_ids([10, 20])
.created_at(DateRange("2025-01-01", "2025-01-31"))
)

campaigns = client.campaigns.list(f)
```

Значения `statuses` передаются в API без проверки на клиенте — доступны все статусы swagger 1.4.0,
включая `will_launch_soon`, `partially_active`, `will_stop_soon`, `pausing`, `unpausing`.

Пустой фильтр корректно сериализуется в JSON-объект `{}`, как того требует API.

## Обработка ошибок
Expand All @@ -333,6 +427,7 @@ campaigns = client.campaigns.list(f)
| 401 | `AuthenticationError` |
| 403 | `AccessDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` (конфликт версий группы в `change_budget`/`change_price`) |
| 429 | `RateLimitError` (атрибут `retry_after`) |
| 5xx | `ServerError` |
| сеть/таймаут | `NetworkError` |
Expand Down Expand Up @@ -435,6 +530,8 @@ async def balance(client: AsyncClient = Depends(avito)):
Создание тестового аккаунта доступно только в песочнице:

```python
from avito_ads.enums import LegalType

config = Configuration.create(client_id, client_secret, account_id).sandbox()

with Client(config) as client:
Expand All @@ -444,11 +541,18 @@ with Client(config) as client:
long_name="Полное наименование",
ogrn="1177746123456",
legal_address="г. Москва, ул. Примерная, д. 1",
actual_address="г. Москва, ул. Примерная, д. 1",
actual_address=None, # None — возьмётся юридический адрес
contact={"name": "Иван Иванов", "phone": "+79001234567"},
legal_type=LegalType.UL, # обязателен: "ul" или "ip"
)
print(created.account_id)
for warning in created.warnings: # ответ 207: аккаунт создан, но не всё подготовлено
print("Предупреждение:", warning)
```

Ответ `207` считается успехом: аккаунт создан, а что не подготовилось — в `created.warnings`
(пустой список — аккаунт подготовлен полностью).

## Разработка и тестирование

```bash
Expand Down
23 changes: 21 additions & 2 deletions avito_ads/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ async def main() -> None:

from ._async import AsyncClient
from ._sync import Client
from ._version import API_VERSION, DEFAULT_USER_AGENT, __version__
from .auth import (
AsyncTokenStorage,
InMemoryAsyncTokenStorage,
Expand All @@ -39,6 +40,9 @@ async def main() -> None:
from .configuration import Configuration
from .contract_builder import ContractBuilder
from .enums import (
AudienceType,
BudgetFrequency,
CampaignBudgetFrequency,
CampaignPaymentModel,
CampaignStatus,
CampaignType,
Expand All @@ -47,9 +51,14 @@ async def main() -> None:
ContractSubject,
ContractType,
CreativesStatus,
FrequencyPeriod,
GroupFormat,
GroupPriceControl,
GroupsStatus,
LegalRole,
LegalType,
Paces,
ScheduleType,
UserRole,
)
from .exceptions import (
Expand All @@ -59,6 +68,7 @@ async def main() -> None:
AvitoAdsError,
BadRequestError,
ConfigurationError,
ConflictError,
NetworkError,
NotFoundError,
RateLimitError,
Expand All @@ -75,10 +85,10 @@ async def main() -> None:
)
from .pagination import ListRequest, PaginatedResult

__version__ = "0.1.0"

__all__ = [
"__version__",
"API_VERSION",
"DEFAULT_USER_AGENT",
# clients
"Client",
"AsyncClient",
Expand All @@ -102,6 +112,14 @@ async def main() -> None:
"CampaignStatus",
"GroupsStatus",
"CreativesStatus",
"CampaignBudgetFrequency",
"BudgetFrequency",
"FrequencyPeriod",
"GroupFormat",
"AudienceType",
"Paces",
"GroupPriceControl",
"ScheduleType",
# exceptions
"AvitoAdsError",
"ConfigurationError",
Expand All @@ -111,6 +129,7 @@ async def main() -> None:
"AuthenticationError",
"AccessDeniedError",
"NotFoundError",
"ConflictError",
"RateLimitError",
"ServerError",
"NetworkError",
Expand Down
Loading
Loading