direct-cli 0.3.6__tar.gz → 0.3.7__tar.gz

{direct_cli-0.3.6 → direct_cli-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.6
+Version: 0.3.7
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -158,6 +158,24 @@ direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
 direct v4goals get-stat-goals --campaign-ids 123 --dry-run
 ```
 
+### V4 Live Tags
+
+Campaign tags are managed as `{TagID, Tag}` pairs. Use `TagID=0` to create a
+new campaign tag. Banner/ad tags are assigned by campaign tag IDs. Update
+methods replace the full tag list for the target campaign or banner, so pass
+existing tags again if they must remain assigned. Ad group tags are filter-only
+through `direct adgroups get --tag-ids/--tags`; this release does not add ad
+group tag mutation commands.
+
+```bash
+direct v4tags get-campaigns --campaign-ids 3193279,1634563
+direct v4tags get-banners --banner-ids 2571700,2571745
+direct v4tags get-banners --campaign-ids 3193279
+direct v4tags update-campaigns --campaign-id 3193279 --tag 0=akapulko --tag 16590=orange --dry-run
+direct v4tags update-banners --banner-ids 2571700,2571745 --tag-ids 16590,16734 --dry-run
+direct v4tags update-banners --banner-ids 2571700 --clear-tags --dry-run
+```
+
 ### V4 Live Events
 
 ```bash
@@ -178,6 +196,19 @@ direct v4wordstat get-report --report-id 123 --format table
 direct v4wordstat delete-report --report-id 123
 ```
 
+### V4 Live Budget Forecasts
+
+Budget forecasts are asynchronous. Direct CLI makes exactly one API call per
+command and does not poll automatically; repeat `list` or `get` yourself until
+the forecast is ready.
+
+```bash
+direct v4forecast create --phrases "buy laptop,buy desktop" --geo-ids 213 --currency RUB
+direct v4forecast list --format table
+direct v4forecast get --forecast-id 123 --format table
+direct v4forecast delete --forecast-id 123
+```
+
 ### V4 Live Finance
 
 Finance methods require an extra financial token for money operations. In the
@@ -562,9 +593,9 @@ Current command surface:
 | WSDL-backed API services | 29 |
 | Supported API services including Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups including `auth` | 39 |
-| CLI subcommands including `auth` | 130 |
-| API CLI subcommands excluding `auth` | 126 |
+| CLI groups including `auth` | 40 |
+| CLI subcommands including `auth` | 144 |
+| API CLI subcommands excluding `auth` | 140 |
 
 ### API Coverage And Drift Monitoring
 
@@ -1183,9 +1214,9 @@ YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rew
 | WSDL-backed API services | 29 |
 | API services с учётом Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups с `auth` | 39 |
-| CLI subcommands с `auth` | 130 |
-| API CLI subcommands без `auth` | 126 |
+| CLI groups с `auth` | 40 |
+| CLI subcommands с `auth` | 144 |
+| API CLI subcommands без `auth` | 140 |
 
 #### Live sandbox write smoke
 

{direct_cli-0.3.6 → direct_cli-0.3.7}/README.md

@@ -115,6 +115,24 @@ direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
 direct v4goals get-stat-goals --campaign-ids 123 --dry-run
 ```
 
+### V4 Live Tags
+
+Campaign tags are managed as `{TagID, Tag}` pairs. Use `TagID=0` to create a
+new campaign tag. Banner/ad tags are assigned by campaign tag IDs. Update
+methods replace the full tag list for the target campaign or banner, so pass
+existing tags again if they must remain assigned. Ad group tags are filter-only
+through `direct adgroups get --tag-ids/--tags`; this release does not add ad
+group tag mutation commands.
+
+```bash
+direct v4tags get-campaigns --campaign-ids 3193279,1634563
+direct v4tags get-banners --banner-ids 2571700,2571745
+direct v4tags get-banners --campaign-ids 3193279
+direct v4tags update-campaigns --campaign-id 3193279 --tag 0=akapulko --tag 16590=orange --dry-run
+direct v4tags update-banners --banner-ids 2571700,2571745 --tag-ids 16590,16734 --dry-run
+direct v4tags update-banners --banner-ids 2571700 --clear-tags --dry-run
+```
+
 ### V4 Live Events
 
 ```bash
@@ -135,6 +153,19 @@ direct v4wordstat get-report --report-id 123 --format table
 direct v4wordstat delete-report --report-id 123
 ```
 
+### V4 Live Budget Forecasts
+
+Budget forecasts are asynchronous. Direct CLI makes exactly one API call per
+command and does not poll automatically; repeat `list` or `get` yourself until
+the forecast is ready.
+
+```bash
+direct v4forecast create --phrases "buy laptop,buy desktop" --geo-ids 213 --currency RUB
+direct v4forecast list --format table
+direct v4forecast get --forecast-id 123 --format table
+direct v4forecast delete --forecast-id 123
+```
+
 ### V4 Live Finance
 
 Finance methods require an extra financial token for money operations. In the
@@ -519,9 +550,9 @@ Current command surface:
 | WSDL-backed API services | 29 |
 | Supported API services including Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups including `auth` | 39 |
-| CLI subcommands including `auth` | 130 |
-| API CLI subcommands excluding `auth` | 126 |
+| CLI groups including `auth` | 40 |
+| CLI subcommands including `auth` | 144 |
+| API CLI subcommands excluding `auth` | 140 |
 
 ### API Coverage And Drift Monitoring
 
@@ -1140,9 +1171,9 @@ YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rew
 | WSDL-backed API services | 29 |
 | API services с учётом Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups с `auth` | 39 |
-| CLI subcommands с `auth` | 130 |
-| API CLI subcommands без `auth` | 126 |
+| CLI groups с `auth` | 40 |
+| CLI subcommands с `auth` | 144 |
+| API CLI subcommands без `auth` | 140 |
 
 #### Live sandbox write smoke
 

{direct_cli-0.3.6 → direct_cli-0.3.7}/direct_cli/cli.py

@@ -43,10 +43,12 @@ from .commands.strategies import strategies
 from .commands.auth import auth
 from .commands.balance import balance
 from .commands.v4events import v4events
+from .commands.v4forecast import v4forecast
 from .commands.v4finance import v4finance
 from .commands.v4account import v4account
-from .commands.v4shells import v4forecast, v4meta
+from .commands.v4shells import v4meta
 from .commands.v4goals import v4goals
+from .commands.v4tags import v4tags
 from .commands.v4wordstat import v4wordstat
 
 # Load .env file
@@ -186,6 +188,7 @@ for command in (
     v4goals,
     v4events,
     v4wordstat,
+    v4tags,
     v4forecast,
     v4meta,
     auth,

direct_cli-0.3.7/direct_cli/commands/v4forecast.py

@@ -0,0 +1,168 @@
+"""Yandex Direct v4 Live budget forecast commands."""
+
+from typing import Optional
+
+import click
+
+from ..api import create_v4_client
+from ..output import format_output, print_error
+from ..utils import parse_csv_strings, parse_ids
+from ..v4 import build_v4_body, call_v4
+from ..v4_contracts import v4_method_contract
+from .v4shells import V4_EPILOG
+
+
+def _forecast_param(
+    phrases: str, geo_ids: Optional[str], currency: str
+) -> dict[str, object]:
+    """Build the v4 Live CreateNewForecast parameter."""
+    phrase_list = parse_csv_strings(phrases)
+    if not phrase_list:
+        raise click.UsageError("--phrases must not be empty")
+    if len(phrase_list) > 100:
+        raise click.UsageError("--phrases accepts at most 100 phrases")
+
+    param: dict[str, object] = {
+        "Phrases": phrase_list,
+        "Currency": currency,
+    }
+    if geo_ids:
+        try:
+            parsed_geo_ids = parse_ids(geo_ids)
+        except ValueError as exc:
+            raise click.UsageError(str(exc)) from exc
+        if parsed_geo_ids:
+            param["GeoID"] = parsed_geo_ids
+    return param
+
+
+def _call_forecast(
+    ctx,
+    method: str,
+    param,
+    output_format: str,
+    output: Optional[str],
+) -> None:
+    """Call one v4 Live budget forecast method and print formatted output."""
+    try:
+        client = create_v4_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            profile=ctx.obj.get("profile"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+        data = call_v4(client, method, param)
+        format_output(data, output_format, output)
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@click.group(epilog=V4_EPILOG)
+def v4forecast():
+    """Yandex Direct v4 Live budget forecast commands."""
+
+
+@v4_method_contract("CreateNewForecast")
+@v4forecast.command()
+@click.option("--phrases", required=True, help="Comma-separated phrases, up to 100")
+@click.option("--geo-ids", help="Comma-separated geo region IDs")
+@click.option(
+    "--currency",
+    default="RUB",
+    show_default=True,
+    help="Forecast currency",
+)
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def create(ctx, phrases, geo_ids, currency, output_format, output, dry_run):
+    """Create a v4 Live budget forecast."""
+    param = _forecast_param(phrases, geo_ids, currency)
+    if dry_run:
+        format_output(build_v4_body("CreateNewForecast", param), "json", None)
+        return
+
+    _call_forecast(ctx, "CreateNewForecast", param, output_format, output)
+
+
+@v4_method_contract("GetForecastList")
+@v4forecast.command(name="list")
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def list_forecasts(ctx, output_format, output, dry_run):
+    """List v4 Live budget forecasts."""
+    if dry_run:
+        format_output(build_v4_body("GetForecastList"), "json", None)
+        return
+
+    _call_forecast(ctx, "GetForecastList", None, output_format, output)
+
+
+@v4_method_contract("GetForecast")
+@v4forecast.command()
+@click.option(
+    "--forecast-id",
+    required=True,
+    type=click.IntRange(min=1),
+    help="Forecast ID",
+)
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def get(ctx, forecast_id, output_format, output, dry_run):
+    """Get a ready v4 Live budget forecast."""
+    if dry_run:
+        format_output(build_v4_body("GetForecast", forecast_id), "json", None)
+        return
+
+    _call_forecast(ctx, "GetForecast", forecast_id, output_format, output)
+
+
+@v4_method_contract("DeleteForecastReport")
+@v4forecast.command()
+@click.option(
+    "--forecast-id",
+    required=True,
+    type=click.IntRange(min=1),
+    help="Forecast ID",
+)
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def delete(ctx, forecast_id, output_format, output, dry_run):
+    """Delete a v4 Live budget forecast."""
+    if dry_run:
+        format_output(build_v4_body("DeleteForecastReport", forecast_id), "json", None)
+        return
+
+    _call_forecast(ctx, "DeleteForecastReport", forecast_id, output_format, output)

{direct_cli-0.3.6 → direct_cli-0.3.7}/direct_cli/commands/v4shells.py

@@ -15,11 +15,6 @@ def v4wordstat():
     """Yandex Direct v4 Live wordstat commands."""
 
 
-@click.group(epilog=V4_EPILOG)
-def v4forecast():
-    """Yandex Direct v4 Live forecast commands."""
-
-
 @click.group(epilog=V4_EPILOG)
 def v4meta():
     """Yandex Direct v4 Live metadata commands."""

direct_cli-0.3.7/direct_cli/commands/v4tags.py

@@ -0,0 +1,263 @@
+"""Yandex Direct v4 Live tag commands."""
+
+from typing import Optional
+
+import click
+
+from ..api import create_v4_client
+from ..output import format_output, print_error
+from ..utils import parse_ids
+from ..v4 import build_v4_body, call_v4
+from ..v4_contracts import v4_method_contract
+from .v4shells import V4_EPILOG
+
+
+def _positive_ids_param(value: str, option_name: str) -> list[int]:
+    """Parse a required comma-separated positive integer list."""
+    try:
+        ids = parse_ids(value)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
+    if not ids:
+        raise click.UsageError(f"{option_name} must not be empty")
+    if any(item <= 0 for item in ids):
+        raise click.UsageError(f"{option_name} must contain only positive integers")
+    return ids
+
+
+def _tag_ids_param(tag_ids: str) -> list[int]:
+    """Parse v4 banner tag IDs."""
+    parsed = _positive_ids_param(tag_ids, "--tag-ids")
+    if len(parsed) > 30:
+        raise click.UsageError("--tag-ids accepts at most 30 tag IDs")
+    return parsed
+
+
+def _get_campaigns_tags_param(campaign_ids: str) -> dict:
+    """Build the v4 Live GetCampaignsTags parameter."""
+    return {"CampaignIDS": _positive_ids_param(campaign_ids, "--campaign-ids")}
+
+
+def _get_banners_tags_param(
+    campaign_ids: Optional[str], banner_ids: Optional[str]
+) -> dict:
+    """Build the v4 Live GetBannersTags parameter."""
+    if (campaign_ids is not None) == (banner_ids is not None):
+        raise click.UsageError("Use exactly one of --campaign-ids or --banner-ids")
+    if campaign_ids is not None:
+        ids = _positive_ids_param(campaign_ids, "--campaign-ids")
+        if len(ids) > 10:
+            raise click.UsageError("--campaign-ids accepts at most 10 campaign IDs")
+        return {"CampaignIDS": ids}
+
+    ids = _positive_ids_param(banner_ids or "", "--banner-ids")
+    if len(ids) > 2000:
+        raise click.UsageError("--banner-ids accepts at most 2000 banner IDs")
+    return {"BannerIDS": ids}
+
+
+def _campaign_tag_param(tag_specs: tuple[str, ...], clear_tags: bool) -> list[dict]:
+    """Build campaign TagInfo objects from repeated TAG_ID=TEXT specs."""
+    if clear_tags:
+        if tag_specs:
+            raise click.UsageError("Use either --tag or --clear-tags, not both")
+        return []
+    if not tag_specs:
+        raise click.UsageError("--tag is required unless --clear-tags is used")
+
+    tags = []
+    seen_texts = set()
+    seen_existing_ids = set()
+    for spec in tag_specs:
+        text = (spec or "").strip()
+        tag_id_text, separator, tag_text = text.partition("=")
+        if not separator:
+            raise click.UsageError("--tag must use TAG_ID=TEXT")
+        tag_id_text = tag_id_text.strip()
+        tag_text = tag_text.strip()
+        try:
+            tag_id = int(tag_id_text)
+        except ValueError as exc:
+            raise click.UsageError("--tag ID must be a non-negative integer") from exc
+        if tag_id < 0:
+            raise click.UsageError("--tag ID must be a non-negative integer")
+        if tag_id > 0:
+            if tag_id in seen_existing_ids:
+                raise click.UsageError("--tag IDs must be unique")
+            seen_existing_ids.add(tag_id)
+        if not tag_text:
+            raise click.UsageError("--tag text must not be empty")
+        if len(tag_text) > 25:
+            raise click.UsageError("--tag text must be 25 characters or fewer")
+        normalized_text = tag_text.casefold()
+        if normalized_text in seen_texts:
+            raise click.UsageError("--tag texts must be unique ignoring case")
+        seen_texts.add(normalized_text)
+        tags.append({"TagID": tag_id, "Tag": tag_text})
+
+    if len(tags) > 200:
+        raise click.UsageError("--tag accepts at most 200 campaign tags")
+    return tags
+
+
+def _update_campaigns_tags_param(
+    campaign_id: int, tag_specs: tuple[str, ...], clear_tags: bool
+) -> list[dict]:
+    """Build the v4 Live UpdateCampaignsTags parameter."""
+    return [
+        {
+            "CampaignID": campaign_id,
+            "Tags": _campaign_tag_param(tag_specs, clear_tags),
+        }
+    ]
+
+
+def _update_banners_tags_param(
+    banner_ids: str, tag_ids: Optional[str], clear_tags: bool
+) -> list[dict]:
+    """Build the v4 Live UpdateBannersTags parameter."""
+    parsed_banner_ids = _positive_ids_param(banner_ids, "--banner-ids")
+    if clear_tags:
+        if tag_ids is not None:
+            raise click.UsageError("Use either --tag-ids or --clear-tags, not both")
+        parsed_tag_ids: list[int] = []
+    else:
+        if tag_ids is None:
+            raise click.UsageError("--tag-ids is required unless --clear-tags is used")
+        parsed_tag_ids = _tag_ids_param(tag_ids)
+    return [
+        {"BannerID": banner_id, "TagIDS": parsed_tag_ids}
+        for banner_id in parsed_banner_ids
+    ]
+
+
+def _call_v4tags(ctx, method: str, param, output_format: str, output: str) -> None:
+    """Call one v4 Live tag method and print formatted output."""
+    try:
+        client = create_v4_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            profile=ctx.obj.get("profile"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+        data = call_v4(client, method, param)
+        format_output(data, output_format, output)
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@click.group(epilog=V4_EPILOG)
+def v4tags():
+    """Yandex Direct v4 Live tag commands."""
+
+
+@v4_method_contract("GetCampaignsTags")
+@v4tags.command(name="get-campaigns")
+@click.option("--campaign-ids", required=True, help="Comma-separated campaign IDs")
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def get_campaigns(ctx, campaign_ids, output_format, output, dry_run):
+    """Get campaign tags."""
+    param = _get_campaigns_tags_param(campaign_ids)
+    if dry_run:
+        format_output(build_v4_body("GetCampaignsTags", param), "json", None)
+        return
+
+    _call_v4tags(ctx, "GetCampaignsTags", param, output_format, output)
+
+
+@v4_method_contract("GetBannersTags")
+@v4tags.command(name="get-banners")
+@click.option("--campaign-ids", help="Comma-separated campaign IDs, up to 10")
+@click.option("--banner-ids", help="Comma-separated banner IDs, up to 2000")
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def get_banners(ctx, campaign_ids, banner_ids, output_format, output, dry_run):
+    """Get banner tag IDs."""
+    param = _get_banners_tags_param(campaign_ids, banner_ids)
+    if dry_run:
+        format_output(build_v4_body("GetBannersTags", param), "json", None)
+        return
+
+    _call_v4tags(ctx, "GetBannersTags", param, output_format, output)
+
+
+@v4_method_contract("UpdateCampaignsTags")
+@v4tags.command(name="update-campaigns")
+@click.option(
+    "--campaign-id",
+    required=True,
+    type=click.IntRange(min=1),
+    help="Campaign ID",
+)
+@click.option(
+    "--tag",
+    "tag_specs",
+    multiple=True,
+    help="Campaign tag as TAG_ID=TEXT; use 0 for a new tag",
+)
+@click.option("--clear-tags", is_flag=True, help="Remove all campaign tags")
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def update_campaigns(
+    ctx, campaign_id, tag_specs, clear_tags, output_format, output, dry_run
+):
+    """Replace the campaign tag list."""
+    param = _update_campaigns_tags_param(campaign_id, tag_specs, clear_tags)
+    if dry_run:
+        format_output(build_v4_body("UpdateCampaignsTags", param), "json", None)
+        return
+
+    _call_v4tags(ctx, "UpdateCampaignsTags", param, output_format, output)
+
+
+@v4_method_contract("UpdateBannersTags")
+@v4tags.command(name="update-banners")
+@click.option("--banner-ids", required=True, help="Comma-separated banner IDs")
+@click.option("--tag-ids", help="Comma-separated campaign tag IDs, up to 30")
+@click.option("--clear-tags", is_flag=True, help="Remove all banner tags")
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def update_banners(
+    ctx, banner_ids, tag_ids, clear_tags, output_format, output, dry_run
+):
+    """Replace banner tag assignments."""
+    param = _update_banners_tags_param(banner_ids, tag_ids, clear_tags)
+    if dry_run:
+        format_output(build_v4_body("UpdateBannersTags", param), "json", None)
+        return
+
+    _call_v4tags(ctx, "UpdateBannersTags", param, output_format, output)

{direct_cli-0.3.6 → direct_cli-0.3.7}/direct_cli/smoke_matrix.py

@@ -58,11 +58,15 @@ SMOKE_MATRIX = {
         "strategies.get",
         "turbopages.get",
         "v4events.get-events-log",
+        "v4forecast.get",
+        "v4forecast.list",
         "v4finance.check-payment",
         "v4finance.get-clients-units",
         "v4finance.get-credit-limits",
         "v4goals.get-retargeting-goals",
         "v4goals.get-stat-goals",
+        "v4tags.get-banners",
+        "v4tags.get-campaigns",
         "v4wordstat.get-report",
         "v4wordstat.list-reports",
         "vcards.get",
@@ -143,6 +147,10 @@ SMOKE_MATRIX = {
         "strategies.update",
         "v4account.account-management",
         "v4account.enable-shared-account",
+        "v4forecast.create",
+        "v4forecast.delete",
+        "v4tags.update-banners",
+        "v4tags.update-campaigns",
         "v4wordstat.create-report",
         "v4wordstat.delete-report",
         "vcards.add",