direct-cli 0.0.0__py3-none-any.whl

direct_cli/utils.py

@@ -0,0 +1,120 @@
+"""
+Utilities for Direct CLI
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+
+
+def parse_ids(ids_str: Optional[str]) -> Optional[List[int]]:
+    """Parse comma-separated IDs"""
+    if not ids_str:
+        return None
+    result = []
+    for x in ids_str.split(","):
+        x = x.strip()
+        try:
+            result.append(int(x))
+        except ValueError:
+            raise ValueError(f"Invalid ID: '{x}'. IDs must be integers.")
+    return result
+
+
+def parse_json(json_str: Optional[str]) -> Optional[Dict[str, Any]]:
+    """Parse JSON string"""
+    if not json_str:
+        return None
+    try:
+        return json.loads(json_str)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON: {e}")
+
+
+def build_selection_criteria(
+    ids: Optional[List[int]] = None,
+    status: Optional[str] = None,
+    types: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Build SelectionCriteria from parameters"""
+    criteria = {}
+
+    if ids:
+        criteria["Ids"] = ids
+    if status:
+        criteria["Statuses"] = [status]
+    if types:
+        criteria["Types"] = types.split(",")
+
+    return criteria if criteria else None
+
+
+def build_common_params(
+    criteria: Optional[Dict[str, Any]] = None,
+    field_names: Optional[List[str]] = None,
+    limit: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Build common params for get requests"""
+    params = {}
+
+    if criteria:
+        params["SelectionCriteria"] = criteria
+    if field_names:
+        params["FieldNames"] = field_names
+    if limit:
+        params["Page"] = {"Limit": limit}
+
+    return params
+
+
+def parse_date(date_str: str) -> str:
+    """Parse and validate date string"""
+    try:
+        datetime.strptime(date_str, "%Y-%m-%d")
+        return date_str
+    except ValueError:
+        raise ValueError(f"Invalid date format: {date_str}. Expected: YYYY-MM-DD")
+
+
+COMMON_FIELDS = {
+    "campaigns": [
+        "Id",
+        "Name",
+        "Status",
+        "State",
+        "StartDate",
+        "EndDate",
+        "Type",
+        "DailyBudget",
+        "ClientInfo",
+    ],
+    "adgroups": ["Id", "Name", "CampaignId", "Status", "Type", "RegionIds"],
+    "ads": ["Id", "CampaignId", "AdGroupId", "Status", "State", "Type"],
+    "keywords": [
+        "Id",
+        "Keyword",
+        "CampaignId",
+        "AdGroupId",
+        "Status",
+        "ServingStatus",
+        "Bid",
+        "ContextBid",
+    ],
+    "clients": ["ClientId", "Login", "CountryId", "Currency"],
+    "creatives": ["Id", "Name", "Type"],
+    "adimages": ["AdImageHash", "Name"],
+    "adextensions": ["Id", "Type", "Status"],
+    "sitelinks": ["Id", "Sitelinks"],
+    "vcards": ["Id", "CampaignId", "Country", "City", "CompanyName"],
+    "leads": ["Date", "LeadId", "CampaignId", "AdGroupId", "AdId"],
+    "turbopages": ["Id", "Name", "Status", "Href"],
+    "feeds": ["Id", "Name", "Source", "Status"],
+    "smartadtargets": ["Id", "CampaignId", "AdGroupId", "Status", "ServingStatus"],
+    "businesses": ["Id", "Name", "Url"],
+    "retargetinglists": ["Id", "Name", "Type", "Scope"],
+}
+
+
+def get_default_fields(resource: str) -> List[str]:
+    """Get default field names for resource"""
+    return COMMON_FIELDS.get(resource, ["Id", "Name"])

direct_cli-0.0.0.dist-info/METADATA

@@ -0,0 +1,393 @@
+Metadata-Version: 2.4
+Name: direct-cli
+Version: 0.0.0
+Summary: Command-line interface for Yandex Direct API
+Home-page: https://github.com/pavelmaksimov/direct-cli
+Author: Pavel Maksimov
+Author-email: Pavel Maksimov <vur21@ya.ru>
+License: MIT
+Project-URL: Homepage, https://github.com/pavelmaksimov/direct-cli
+Project-URL: Repository, https://github.com/pavelmaksimov/direct-cli
+Keywords: yandex,direct,cli,api,advertising
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: tapi-yandex-direct>=2021.5.29
+Requires-Dist: click>=8.0.0
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: tabulate>=0.8.0
+Requires-Dist: colorama>=0.4.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Direct CLI
+
+[English](#english) | [Русский](#русский)
+
+---
+
+## English
+
+Command-line interface for the Yandex Direct API.
+
+### Installation
+
+```bash
+pip install direct-cli
+```
+
+### Configuration
+
+Create a `.env` file in your working directory:
+
+```env
+YANDEX_DIRECT_TOKEN=your_access_token
+YANDEX_DIRECT_LOGIN=your_yandex_login
+```
+
+Or pass credentials directly per command:
+
+```bash
+direct-cli --token YOUR_TOKEN --login YOUR_LOGIN campaigns get
+```
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--token` | API access token |
+| `--login` | Yandex advertiser login |
+| `--sandbox` | Use sandbox API |
+
+### Usage
+
+All commands follow the pattern: `direct-cli <resource> <action> [options]`
+
+#### Campaigns
+
+```bash
+# Get campaigns
+direct-cli campaigns get
+direct-cli campaigns get --status ACTIVE
+direct-cli campaigns get --ids 1,2,3 --format table
+direct-cli campaigns get --fetch-all --format csv --output campaigns.csv
+
+# Create (use --dry-run to preview the request)
+direct-cli campaigns add --name "My Campaign" --start-date 2024-02-01 --type TEXT_CAMPAIGN --budget 1000
+direct-cli campaigns add --name "My Campaign" --start-date 2024-02-01 --dry-run
+
+# Update / lifecycle
+direct-cli campaigns update --id 12345 --name "New Name"
+direct-cli campaigns suspend --id 12345
+direct-cli campaigns resume  --id 12345
+direct-cli campaigns archive --id 12345
+direct-cli campaigns unarchive --id 12345
+direct-cli campaigns delete  --id 12345
+```
+
+#### Ad Groups
+
+```bash
+direct-cli adgroups get --campaign-ids 1,2,3 --limit 50
+direct-cli adgroups add --name "Group 1" --campaign-id 12345 --dry-run
+direct-cli adgroups update --id 67890 --name "New Name"
+direct-cli adgroups delete --id 67890
+```
+
+#### Ads
+
+```bash
+direct-cli ads get --campaign-ids 1,2,3
+direct-cli ads get --adgroup-ids 45678 --format table
+direct-cli ads add --adgroup-id 12345 --type TEXT_AD --title "Title" --text "Ad text" --href "https://example.com" --dry-run
+direct-cli ads update --id 99999 --status PAUSED
+direct-cli ads delete --id 99999
+```
+
+#### Keywords
+
+```bash
+direct-cli keywords get --campaign-ids 1,2,3
+direct-cli keywords add --adgroup-id 12345 --keyword "buy laptop" --bid 10.50 --dry-run
+direct-cli keywords update --id 88888 --bid 15.00
+direct-cli keywords delete --id 88888
+```
+
+#### Reports
+
+```bash
+# Get a report (saved to file)
+direct-cli reports get \
+  --type CAMPAIGN_PERFORMANCE_REPORT \
+  --from 2024-01-01 --to 2024-01-31 \
+  --name "January Report" \
+  --fields "Date,CampaignId,Clicks,Cost" \
+  --format csv --output report.csv
+
+# List available report types
+direct-cli reports list-types
+```
+
+Available report types: `CAMPAIGN_PERFORMANCE_REPORT`, `ADGROUP_PERFORMANCE_REPORT`, `AD_PERFORMANCE_REPORT`, `CRITERIA_PERFORMANCE_REPORT`, `CUSTOM_REPORT`, `REACH_AND_FREQUENCY_CAMPAIGN_REPORT`, `SEARCH_QUERY_PERFORMANCE_REPORT`
+
+#### Other Resources
+
+```bash
+# Reference dictionaries
+direct-cli dictionaries get --names Currencies,GeoRegions
+
+# Client info
+direct-cli clients get --fields ClientId,Login,Currency
+
+# Changes feed
+direct-cli changes get --campaign-ids 1,2,3
+
+# Retargeting lists
+direct-cli retargeting get --limit 10
+
+# Ad extensions, sitelinks, vCards, images, creatives, feeds, bids, etc.
+direct-cli adextensions get
+direct-cli sitelinks get --ids 1,2,3
+direct-cli bids get --campaign-ids 1,2,3
+```
+
+### Output Formats
+
+All `get` commands support `--format`:
+
+| Format | Description |
+|--------|-------------|
+| `json` | JSON (default) |
+| `table` | Formatted table |
+| `csv` | CSV |
+| `tsv` | TSV |
+
+```bash
+direct-cli campaigns get --format table
+direct-cli campaigns get --format csv --output campaigns.csv
+```
+
+### Pagination
+
+```bash
+direct-cli campaigns get --limit 10        # first 10 results
+direct-cli campaigns get --fetch-all       # all pages
+```
+
+### ⚠️ Destructive Commands
+
+The following commands make **irreversible changes** — use with caution:
+
+| Command | Effect |
+|---------|--------|
+| `campaigns delete --id` | Permanently deletes a campaign and all its contents |
+| `adgroups delete --id` | Permanently deletes an ad group |
+| `ads delete --id` | Permanently deletes an ad |
+| `keywords delete --id` | Permanently deletes a keyword |
+| `audiencetargets delete --id` | Permanently deletes an audience target |
+
+Commands that affect live ad delivery: `suspend`, `resume`, `archive`, `unarchive` (available on `campaigns`, `ads`, `keywords`).
+
+Commands that affect bids and spending: `bids set`, `keywordbids set`, `bidmodifiers set`.
+
+Use `--dry-run` on `add` / `update` commands to preview the API request before sending:
+
+```bash
+direct-cli campaigns add --name "Test" --start-date 2024-01-01 --dry-run
+```
+
+### License
+
+MIT
+
+---
+
+## Русский
+
+Интерфейс командной строки для Яндекс.Директ API.
+
+### Установка
+
+```bash
+pip install direct-cli
+```
+
+### Настройка
+
+Создайте файл `.env` в рабочей директории:
+
+```env
+YANDEX_DIRECT_TOKEN=ваш_токен
+YANDEX_DIRECT_LOGIN=ваш_логин_на_яндексе
+```
+
+Или передавайте credentials напрямую в команду:
+
+```bash
+direct-cli --token ВАШ_ТОКЕН --login ВАШ_ЛОГИН campaigns get
+```
+
+### Глобальные опции
+
+| Опция | Описание |
+|-------|----------|
+| `--token` | OAuth-токен доступа к API |
+| `--login` | Логин рекламодателя на Яндексе |
+| `--sandbox` | Использовать тестовое API (песочница) |
+
+### Использование
+
+Все команды следуют шаблону: `direct-cli <ресурс> <действие> [опции]`
+
+#### Кампании
+
+```bash
+# Получить кампании
+direct-cli campaigns get
+direct-cli campaigns get --status ACTIVE
+direct-cli campaigns get --ids 1,2,3 --format table
+direct-cli campaigns get --fetch-all --format csv --output campaigns.csv
+
+# Создать (--dry-run покажет запрос без отправки)
+direct-cli campaigns add --name "Моя кампания" --start-date 2024-02-01 --type TEXT_CAMPAIGN --budget 1000
+direct-cli campaigns add --name "Моя кампания" --start-date 2024-02-01 --dry-run
+
+# Обновление и управление статусом
+direct-cli campaigns update   --id 12345 --name "Новое название"
+direct-cli campaigns suspend  --id 12345
+direct-cli campaigns resume   --id 12345
+direct-cli campaigns archive  --id 12345
+direct-cli campaigns unarchive --id 12345
+direct-cli campaigns delete   --id 12345
+```
+
+#### Группы объявлений
+
+```bash
+direct-cli adgroups get --campaign-ids 1,2,3 --limit 50
+direct-cli adgroups add --name "Группа 1" --campaign-id 12345 --dry-run
+direct-cli adgroups update --id 67890 --name "Новое название"
+direct-cli adgroups delete --id 67890
+```
+
+#### Объявления
+
+```bash
+direct-cli ads get --campaign-ids 1,2,3
+direct-cli ads get --adgroup-ids 45678 --format table
+direct-cli ads add --adgroup-id 12345 --type TEXT_AD --title "Заголовок" --text "Текст объявления" --href "https://example.com" --dry-run
+direct-cli ads update --id 99999 --status PAUSED
+direct-cli ads delete --id 99999
+```
+
+#### Ключевые слова
+
+```bash
+direct-cli keywords get --campaign-ids 1,2,3
+direct-cli keywords add --adgroup-id 12345 --keyword "купить ноутбук" --bid 10.50 --dry-run
+direct-cli keywords update --id 88888 --bid 15.00
+direct-cli keywords delete --id 88888
+```
+
+#### Отчёты
+
+```bash
+# Сформировать отчёт (сохраняется в файл)
+direct-cli reports get \
+  --type CAMPAIGN_PERFORMANCE_REPORT \
+  --from 2024-01-01 --to 2024-01-31 \
+  --name "Отчёт за январь" \
+  --fields "Date,CampaignId,Clicks,Cost" \
+  --format csv --output report.csv
+
+# Список доступных типов отчётов
+direct-cli reports list-types
+```
+
+Доступные типы: `CAMPAIGN_PERFORMANCE_REPORT`, `ADGROUP_PERFORMANCE_REPORT`, `AD_PERFORMANCE_REPORT`, `CRITERIA_PERFORMANCE_REPORT`, `CUSTOM_REPORT`, `REACH_AND_FREQUENCY_CAMPAIGN_REPORT`, `SEARCH_QUERY_PERFORMANCE_REPORT`
+
+#### Другие ресурсы
+
+```bash
+# Справочники
+direct-cli dictionaries get --names Currencies,GeoRegions
+
+# Информация о клиенте
+direct-cli clients get --fields ClientId,Login,Currency
+
+# Лента изменений
+direct-cli changes get --campaign-ids 1,2,3
+
+# Списки ретаргетинга
+direct-cli retargeting get --limit 10
+
+# Расширения объявлений, быстрые ссылки, визитки, изображения, ставки и т.д.
+direct-cli adextensions get
+direct-cli sitelinks get --ids 1,2,3
+direct-cli bids get --campaign-ids 1,2,3
+```
+
+### Форматы вывода
+
+Все команды `get` поддерживают `--format`:
+
+| Формат | Описание |
+|--------|----------|
+| `json` | JSON (по умолчанию) |
+| `table` | Таблица |
+| `csv` | CSV |
+| `tsv` | TSV |
+
+```bash
+direct-cli campaigns get --format table
+direct-cli campaigns get --format csv --output campaigns.csv
+```
+
+### Пагинация
+
+```bash
+direct-cli campaigns get --limit 10    # первые 10 результатов
+direct-cli campaigns get --fetch-all   # все страницы
+```
+
+### ⚠️ Опасные команды
+
+Следующие команды вносят **необратимые изменения** — используйте осторожно:
+
+| Команда | Эффект |
+|---------|--------|
+| `campaigns delete --id` | Безвозвратно удаляет кампанию и весь её контент |
+| `adgroups delete --id` | Безвозвратно удаляет группу объявлений |
+| `ads delete --id` | Безвозвратно удаляет объявление |
+| `keywords delete --id` | Безвозвратно удаляет ключевое слово |
+| `audiencetargets delete --id` | Безвозвратно удаляет условие подбора аудитории |
+
+Команды, влияющие на показ рекламы: `suspend`, `resume`, `archive`, `unarchive` (доступны для `campaigns`, `ads`, `keywords`).
+
+Команды, влияющие на ставки и расходы: `bids set`, `keywordbids set`, `bidmodifiers set`.
+
+Используйте `--dry-run` в командах `add` / `update`, чтобы увидеть тело запроса до отправки:
+
+```bash
+direct-cli campaigns add --name "Тест" --start-date 2024-01-01 --dry-run
+```
+
+### Лицензия
+
+MIT

direct_cli-0.0.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+direct_cli/__init__.py,sha256=eABq4p8Yh-Ia1sfr6tvAalkJnY6SRRHmugJ8X2s-7QA,320
+direct_cli/api.py,sha256=Dbyi_9F1WnwDOMAmPeUOajL0bQffAR1s5qYwsMioWR4,2272
+direct_cli/auth.py,sha256=83w9InfmOqZa0mPbtwkf4pS8BPn-fDJCDhjZWNKwUkM,1371
+direct_cli/cli.py,sha256=AOQf48jkR_0yU2ubAy5Bv_bw_GQblFEOevjC0FtpRDc,2632
+direct_cli/output.py,sha256=aA8-BS6OjzMplRjhqDiHfEUZBa1USfE2-dAJezQI5yQ,4118
+direct_cli/utils.py,sha256=lES9tvDTWdhS10KsU74tazwbPIcEZN8mMKKlnBXJQ_c,3261
+direct_cli/commands/__init__.py,sha256=WHvXUd_dgpx1VR91T3dBWp2BCIEwdh17txYjNQTGrmM,1475
+direct_cli/commands/adextensions.py,sha256=41UOK8bwwkIaZ5XV_qbzmHZl9-tDoHmrjaLVF3GXGI4,2830
+direct_cli/commands/adgroups.py,sha256=HPcClDcrUwpe7sZeDXwWRoBOGbamZA69w1f9gRxmlE8,5518
+direct_cli/commands/adimages.py,sha256=Wl4d5BVBM4arxrlmWuetgqBHbrsKd8uuBUNcAAmP62M,1734
+direct_cli/commands/ads.py,sha256=USazYe8aXEPuji5py2HxUUGRvQ_2ajBv7eU7v4dmcNA,8509
+direct_cli/commands/agencyclients.py,sha256=ZW35X3reash0cpp0TWFjoVJ1HXWN-IVyaNigic2rDdY,1799
+direct_cli/commands/audiencetargets.py,sha256=tLOP-xFIbwzoU6UOkA3ocF2GYrnrfpUGWm1_80Eqnms,5447
+direct_cli/commands/bidmodifiers.py,sha256=Neg2cBTvDOdcuiBbnS5DfW3-jaaPI8eOUa7zJ7bBRZM,3233
+direct_cli/commands/bids.py,sha256=HFbROs7XGl0W8oZEdqjuizFK9VqBxnxB-ef-LnSmXWo,3105
+direct_cli/commands/businesses.py,sha256=qlltQOLco5nkflSJkQoLvRb2APBsvi4ImKjRnes8gwE,1705
+direct_cli/commands/campaigns.py,sha256=Za3CRSthI5-jRinIw3gJJcrQUmfNI_B-VAdTpi4gmyg,9016
+direct_cli/commands/changes.py,sha256=WuxrXjW2V7RTGgOZea4VeErJOmRrPN6u8c9685rF4K4,2745
+direct_cli/commands/clients.py,sha256=JQgqmXWQh-zDKlKOVe9dtetALFy90L7NaelWLsJaiH0,2773
+direct_cli/commands/creatives.py,sha256=NHKjcw_XyiQhc1X2dbCCDdJ361FcEEs9IGpXkrfjYX0,1942
+direct_cli/commands/dictionaries.py,sha256=q_dLWJ2IN51qGVRl1-HitK6uxb-44gmKb19odoy2E7Y,1475
+direct_cli/commands/dynamicads.py,sha256=AXQIOD6mPFzAP6MYAyFzwqAycURenO5_LiSJR-1WgmY,3117
+direct_cli/commands/feeds.py,sha256=MmUAjrWCZ7NociDrQRoMA5JtSfg2RSsYOFDXuTmxTw4,2759
+direct_cli/commands/keywordbids.py,sha256=2WZ3_xtsHZXP3ECcIljTh55WTWnq6kCM22zCOIX05SY,3385
+direct_cli/commands/keywords.py,sha256=qZlZypAkXSbVDlyKume9OhiJ7AHWkWkbw40BshIkuKI,8795
+direct_cli/commands/keywordsresearch.py,sha256=n-YyFHF5Cc51F0nGNqk8XrIDZHsZwuq9c18ImqF4lMc,2065
+direct_cli/commands/leads.py,sha256=QOIb6CCFOQUx1mHOxCqyPIdFwL82mazaM6YXZH-fiPI,1799
+direct_cli/commands/negativekeywordsharedsets.py,sha256=9kusSNcQ_Yt8UYJyZZI6GC2P4seXQTz00ThrfYWbB08,2906
+direct_cli/commands/reports.py,sha256=vKlQ2yNAveJETe86qNse48gh3P8ybVS0x7F9f4B9rGs,3592
+direct_cli/commands/retargeting.py,sha256=lnHa4M5tlmCxu9W2dZcj6MrqWb7sOm6vO8hjI4numfc,3054
+direct_cli/commands/sitelinks.py,sha256=sdL9PPrWCyHs7UMlETKv7IemohbsM8HPym9b8llsVAc,2548
+direct_cli/commands/smartadtargets.py,sha256=tt910yiDjcYuWmNTf6rBhJxEJfq8j0ErP3HOz4qsTuM,3146
+direct_cli/commands/turbopages.py,sha256=NnwXYGQu0h9rwbUNExxIu1jr8QaiNCmCymmiiYBlyuE,2790
+direct_cli/commands/vcards.py,sha256=E_zeg7VadIp1iAeMaLCQsI81ebGJSY_gVBW_XB9hAzc,2557
+direct_cli-0.0.0.dist-info/METADATA,sha256=pnRdEw9eVXUjmQSB8adw9YeyorxThhj6JmEuYSfWFh0,12174
+direct_cli-0.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+direct_cli-0.0.0.dist-info/entry_points.txt,sha256=yzCDa9Tum04gxxdx5DkyX1ArWrXWrr4PAclLQOmA_54,50
+direct_cli-0.0.0.dist-info/top_level.txt,sha256=M8w4K7buiy4QuvlN4gU2c47HAO0zPmuTGIoWk0kWEEM,11
+direct_cli-0.0.0.dist-info/RECORD,,

direct_cli-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

direct_cli-0.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+direct-cli = direct_cli.cli:cli

direct_cli-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+direct_cli