direct-cli 0.0.0__py3-none-any.whl

direct_cli/__init__.py

@@ -0,0 +1,14 @@
+"""
+Direct CLI - Command-line interface for Yandex Direct API
+"""
+
+__author__ = "Pavel Maksimov"
+__email__ = "vur21@ya.ru"
+
+# Version will be set by setuptools_scm
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+__all__ = ["__version__", "__author__", "__email__"]

direct_cli/api.py

@@ -0,0 +1,94 @@
+"""
+API client wrapper for Direct CLI
+"""
+
+from typing import Optional, Dict, Any, List
+
+from tapi_yandex_direct import YandexDirect
+from .auth import get_credentials
+
+
+def create_client(
+    token: Optional[str] = None,
+    login: Optional[str] = None,
+    sandbox: bool = False,
+) -> YandexDirect:
+    """
+    Create YandexDirect client
+
+    Args:
+        token: API access token
+        login: Client login (for agency accounts)
+        sandbox: Use sandbox API
+
+    Returns:
+        YandexDirect client instance
+    """
+    final_token, final_login = get_credentials(token, login)
+
+    return YandexDirect(
+        access_token=final_token,
+        login=final_login,
+        is_sandbox=sandbox,
+        retry_if_exceeded_limit=True,
+        retries_if_server_error=5,
+        # Report settings
+        processing_mode="auto",
+        wait_report=True,
+        return_money_in_micros=False,
+        skip_report_header=True,
+        skip_column_header=False,
+        skip_report_summary=True,
+    )
+
+
+def fetch_all_pages(
+    client: YandexDirect,
+    resource_name: str,
+    method: str = "get",
+    params: Dict[str, Any] = None,
+    field_names: Optional[List[str]] = None,
+    progress: bool = False,
+) -> List[Dict[str, Any]]:
+    """
+    Fetch all pages of results
+
+    Args:
+        client: YandexDirect client
+        resource_name: Resource name (e.g., 'campaigns', 'adgroups')
+        method: API method ('get')
+        params: Request params
+        field_names: Field names to include
+        progress: Show progress bar
+
+    Returns:
+        List of all items from all pages
+    """
+    if params is None:
+        params = {}
+
+    body = {
+        "method": method,
+        "params": params,
+    }
+
+    if field_names:
+        body["params"]["FieldNames"] = field_names
+
+    resource = getattr(client, resource_name)()
+    result = resource.post(data=body)
+
+    # Get items from first page
+    items = result().extract()
+
+    # Check if there are more pages
+    if hasattr(result, "iter_items") and callable(result().iter_items):
+        all_items = []
+
+        # Use iter_items for pagination
+        for item in result().iter_items():
+            all_items.append(item)
+
+        return all_items
+
+    return items if isinstance(items, list) else [items]

direct_cli/auth.py

@@ -0,0 +1,58 @@
+"""
+Authentication module for Direct CLI
+"""
+
+import os
+from typing import Optional, Tuple
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = lambda: None
+
+
+def load_env_file(env_path: Optional[str] = None) -> None:
+    """Load environment variables from .env file"""
+    if load_dotenv:
+        if env_path:
+            load_dotenv(env_path)
+        else:
+            load_dotenv()
+
+
+def get_credentials(
+    token: Optional[str] = None,
+    login: Optional[str] = None,
+    env_path: Optional[str] = None,
+) -> Tuple[str, Optional[str]]:
+    """
+    Get credentials with priority:
+    1. Direct arguments
+    2. Environment variables
+    3. .env file
+
+    Args:
+        token: API access token
+        login: Client login (for agency accounts)
+        env_path: Path to .env file
+
+    Returns:
+        Tuple of (token, login)
+
+    Raises:
+        ValueError: If token is not provided
+    """
+    # Load .env file first
+    load_env_file(env_path)
+
+    # Priority: arguments > env vars
+    final_token = token or os.getenv("YANDEX_DIRECT_TOKEN")
+    final_login = login or os.getenv("YANDEX_DIRECT_LOGIN")
+
+    if not final_token:
+        raise ValueError(
+            "API token required. Set YANDEX_DIRECT_TOKEN environment variable "
+            "or create .env file, or use --token option."
+        )
+
+    return final_token, final_login

direct_cli/cli.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python
+"""
+Direct CLI - Command-line interface for Yandex Direct API
+"""
+
+import click
+from dotenv import load_dotenv
+
+from .commands.campaigns import campaigns
+from .commands.adgroups import adgroups
+from .commands.ads import ads
+from .commands.keywords import keywords
+from .commands.keywordbids import keywordbids
+from .commands.bids import bids
+from .commands.bidmodifiers import bidmodifiers
+from .commands.audiencetargets import audiencetargets
+from .commands.retargeting import retargeting
+from .commands.creatives import creatives
+from .commands.adimages import adimages
+from .commands.adextensions import adextensions
+from .commands.sitelinks import sitelinks
+from .commands.vcards import vcards
+from .commands.leads import leads
+from .commands.clients import clients
+from .commands.agencyclients import agencyclients
+from .commands.dictionaries import dictionaries
+from .commands.changes import changes
+from .commands.reports import reports
+from .commands.turbopages import turbopages
+from .commands.negativekeywordsharedsets import negativekeywordsharedsets
+from .commands.feeds import feeds
+from .commands.smartadtargets import smartadtargets
+from .commands.businesses import businesses
+from .commands.keywordsresearch import keywordsresearch
+from .commands.dynamicads import dynamicads
+
+# Load .env file
+load_dotenv()
+
+
+@click.group()
+@click.option("--token", envvar="YANDEX_DIRECT_TOKEN", help="API access token")
+@click.option("--login", envvar="YANDEX_DIRECT_LOGIN", help="Client login")
+@click.option("--sandbox", is_flag=True, help="Use sandbox API")
+@click.pass_context
+def cli(ctx, token, login, sandbox):
+    """Command-line interface for Yandex Direct API"""
+    ctx.ensure_object(dict)
+    ctx.obj["token"] = token
+    ctx.obj["login"] = login
+    ctx.obj["sandbox"] = sandbox
+
+
+# Register all commands
+cli.add_command(campaigns)
+cli.add_command(adgroups)
+cli.add_command(ads)
+cli.add_command(keywords)
+cli.add_command(keywordbids)
+cli.add_command(bids)
+cli.add_command(bidmodifiers)
+cli.add_command(audiencetargets)
+cli.add_command(retargeting)
+cli.add_command(creatives)
+cli.add_command(adimages)
+cli.add_command(adextensions)
+cli.add_command(sitelinks)
+cli.add_command(vcards)
+cli.add_command(leads)
+cli.add_command(clients)
+cli.add_command(agencyclients)
+cli.add_command(dictionaries)
+cli.add_command(changes)
+cli.add_command(reports)
+cli.add_command(turbopages)
+cli.add_command(negativekeywordsharedsets)
+cli.add_command(feeds)
+cli.add_command(smartadtargets)
+cli.add_command(businesses)
+cli.add_command(keywordsresearch)
+cli.add_command(dynamicads)
+
+
+if __name__ == "__main__":
+    cli()

direct_cli/commands/__init__.py

@@ -0,0 +1,61 @@
+"""
+Command handlers for Direct CLI
+"""
+
+from .campaigns import campaigns
+from .adgroups import adgroups
+from .ads import ads
+from .keywords import keywords
+from .keywordbids import keywordbids
+from .bids import bids
+from .bidmodifiers import bidmodifiers
+from .audiencetargets import audiencetargets
+from .retargeting import retargeting
+from .creatives import creatives
+from .adimages import adimages
+from .adextensions import adextensions
+from .sitelinks import sitelinks
+from .vcards import vcards
+from .leads import leads
+from .clients import clients
+from .agencyclients import agencyclients
+from .dictionaries import dictionaries
+from .changes import changes
+from .reports import reports
+from .turbopages import turbopages
+from .negativekeywordsharedsets import negativekeywordsharedsets
+from .feeds import feeds
+from .smartadtargets import smartadtargets
+from .businesses import businesses
+from .keywordsresearch import keywordsresearch
+from .dynamicads import dynamicads
+
+__all__ = [
+    "campaigns",
+    "adgroups",
+    "ads",
+    "keywords",
+    "keywordbids",
+    "bids",
+    "bidmodifiers",
+    "audiencetargets",
+    "retargeting",
+    "creatives",
+    "adimages",
+    "adextensions",
+    "sitelinks",
+    "vcards",
+    "leads",
+    "clients",
+    "agencyclients",
+    "dictionaries",
+    "changes",
+    "reports",
+    "turbopages",
+    "negativekeywordsharedsets",
+    "feeds",
+    "smartadtargets",
+    "businesses",
+    "keywordsresearch",
+    "dynamicads",
+]

direct_cli/commands/adextensions.py

@@ -0,0 +1,96 @@
+"""
+AdExtensions commands
+"""
+
+import json
+import click
+
+from ..api import create_client
+from ..output import format_output, print_error
+from ..utils import parse_ids
+
+
+@click.group()
+def adextensions():
+    """Manage ad extensions"""
+    pass
+
+
+@adextensions.command()
+@click.option("--ids", help="Comma-separated extension IDs")
+@click.option("--types", help="Filter by types")
+@click.option("--limit", type=int, help="Limit number of results")
+@click.option("--fetch-all", is_flag=True, help="Fetch all pages")
+@click.option("--format", "output_format", default="json", help="Output format")
+@click.option("--output", help="Output file")
+@click.option("--fields", help="Comma-separated field names")
+@click.pass_context
+def get(ctx, ids, types, limit, fetch_all, output_format, output, fields):
+    """Get ad extensions"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        field_names = fields.split(",") if fields else ["Id", "Type", "Status"]
+
+        criteria = {}
+        if ids:
+            criteria["Ids"] = parse_ids(ids)
+        if types:
+            criteria["Types"] = types.split(",")
+
+        params = {"SelectionCriteria": criteria, "FieldNames": field_names}
+
+        if limit:
+            params["Page"] = {"Limit": limit}
+
+        body = {"method": "get", "params": params}
+
+        result = client.adextensions().post(data=body)
+
+        if fetch_all:
+            items = []
+            for item in result().iter_items():
+                items.append(item)
+            format_output(items, output_format, output)
+        else:
+            data = result().extract()
+            format_output(data, output_format, output)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@adextensions.command()
+@click.option("--type", "ext_type", required=True, help="Extension type")
+@click.option("--json", "extra_json", required=True, help="Extension data in JSON")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def add(ctx, ext_type, extra_json, dry_run):
+    """Add ad extension"""
+    try:
+        ext_data = {"Type": ext_type}
+        ext_data.update(json.loads(extra_json))
+
+        body = {"method": "add", "params": {"AdExtensions": [ext_data]}}
+
+        if dry_run:
+            format_output(body, "json", None)
+            return
+
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        result = client.adextensions().post(data=body)
+        format_output(result().extract(), "json", None)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()

direct_cli/commands/adgroups.py

@@ -0,0 +1,189 @@
+"""
+Ad Groups commands
+"""
+
+import json
+import click
+
+from ..api import create_client
+from ..output import format_output, print_error
+from ..utils import parse_ids, get_default_fields
+
+
+@click.group()
+def adgroups():
+    """Manage ad groups"""
+    pass
+
+
+@adgroups.command()
+@click.option("--ids", help="Comma-separated ad group IDs")
+@click.option("--campaign-ids", help="Comma-separated campaign IDs")
+@click.option("--status", help="Filter by status")
+@click.option("--types", help="Filter by types")
+@click.option("--limit", type=int, help="Limit number of results")
+@click.option("--fetch-all", is_flag=True, help="Fetch all pages")
+@click.option("--format", "output_format", default="json", help="Output format")
+@click.option("--output", help="Output file")
+@click.option("--fields", help="Comma-separated field names")
+@click.pass_context
+def get(
+    ctx,
+    ids,
+    campaign_ids,
+    status,
+    types,
+    limit,
+    fetch_all,
+    output_format,
+    output,
+    fields,
+):
+    """Get ad groups"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        field_names = fields.split(",") if fields else get_default_fields("adgroups")
+
+        criteria = {}
+        if ids:
+            criteria["Ids"] = parse_ids(ids)
+        if campaign_ids:
+            criteria["CampaignIds"] = parse_ids(campaign_ids)
+        if status:
+            criteria["Statuses"] = [status]
+        if types:
+            criteria["Types"] = types.split(",")
+
+        params = {"SelectionCriteria": criteria, "FieldNames": field_names}
+
+        if limit:
+            params["Page"] = {"Limit": limit}
+
+        body = {"method": "get", "params": params}
+
+        result = client.adgroups().post(data=body)
+
+        if fetch_all:
+            items = []
+            for item in result().iter_items():
+                items.append(item)
+            format_output(items, output_format, output)
+        else:
+            data = result().extract()
+            format_output(data, output_format, output)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@adgroups.command()
+@click.option("--name", required=True, help="Ad group name")
+@click.option("--campaign-id", required=True, type=int, help="Campaign ID")
+@click.option("--type", "group_type", default="TEXT_AD_GROUP", help="Ad group type")
+@click.option("--region-ids", help="Comma-separated region IDs")
+@click.option("--json", "extra_json", help="Additional JSON parameters")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def add(ctx, name, campaign_id, group_type, region_ids, extra_json, dry_run):
+    """Add new ad group"""
+    try:
+        adgroup_data = {"Name": name, "CampaignId": campaign_id, "Type": group_type}
+
+        if region_ids:
+            adgroup_data["RegionIds"] = parse_ids(region_ids)
+
+        if extra_json:
+            extra = json.loads(extra_json)
+            adgroup_data.update(extra)
+
+        body = {"method": "add", "params": {"AdGroups": [adgroup_data]}}
+
+        if dry_run:
+            format_output(body, "json", None)
+            return
+
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        result = client.adgroups().post(data=body)
+        format_output(result().extract(), "json", None)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@adgroups.command()
+@click.option("--id", "adgroup_id", required=True, type=int, help="Ad group ID")
+@click.option("--name", help="New ad group name")
+@click.option("--status", help="New status")
+@click.option("--json", "extra_json", help="Additional JSON parameters")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def update(ctx, adgroup_id, name, status, extra_json, dry_run):
+    """Update ad group"""
+    try:
+        adgroup_data = {"Id": adgroup_id}
+
+        if name:
+            adgroup_data["Name"] = name
+
+        if status:
+            adgroup_data["Status"] = status
+
+        if extra_json:
+            extra = json.loads(extra_json)
+            adgroup_data.update(extra)
+
+        body = {"method": "update", "params": {"AdGroups": [adgroup_data]}}
+
+        if dry_run:
+            format_output(body, "json", None)
+            return
+
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        result = client.adgroups().post(data=body)
+        format_output(result().extract(), "json", None)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@adgroups.command()
+@click.option("--id", "adgroup_id", required=True, type=int, help="Ad group ID")
+@click.pass_context
+def delete(ctx, adgroup_id):
+    """Delete ad group"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        body = {
+            "method": "delete",
+            "params": {"SelectionCriteria": {"Ids": [adgroup_id]}},
+        }
+
+        result = client.adgroups().post(data=body)
+        format_output(result().extract(), "json", None)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()

direct_cli/commands/adimages.py

@@ -0,0 +1,63 @@
+"""
+AdImages commands
+"""
+
+import click
+
+from ..api import create_client
+from ..output import format_output, print_error
+from ..utils import parse_ids
+
+
+@click.group()
+def adimages():
+    """Manage ad images"""
+    pass
+
+
+@adimages.command()
+@click.option("--ids", help="Comma-separated image IDs")
+@click.option("--limit", type=int, help="Limit number of results")
+@click.option("--fetch-all", is_flag=True, help="Fetch all pages")
+@click.option("--format", "output_format", default="json", help="Output format")
+@click.option("--output", help="Output file")
+@click.option("--fields", help="Comma-separated field names")
+@click.pass_context
+def get(ctx, ids, limit, fetch_all, output_format, output, fields):
+    """Get ad images"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        field_names = (
+            fields.split(",") if fields else ["Id", "Name", "Status", "AdImageHash"]
+        )
+
+        criteria = {}
+        if ids:
+            criteria["Ids"] = parse_ids(ids)
+
+        params = {"SelectionCriteria": criteria, "FieldNames": field_names}
+
+        if limit:
+            params["Page"] = {"Limit": limit}
+
+        body = {"method": "get", "params": params}
+
+        result = client.adimages().post(data=body)
+
+        if fetch_all:
+            items = []
+            for item in result().iter_items():
+                items.append(item)
+            format_output(items, output_format, output)
+        else:
+            data = result().extract()
+            format_output(data, output_format, output)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()