direct-cli 0.3.9__tar.gz → 0.3.10__tar.gz

{direct_cli-0.3.9 → direct_cli-0.3.10}/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.3.10
+
+**Added:**
+
+- `direct changes check` now exposes all three mutually-exclusive ID
+  filters from the WSDL — `--campaign-ids` (≤3000), `--ad-group-ids`
+  (≤10 000) and `--ad-ids` (≤50 000); exactly one is required and the
+  mutex is enforced via `click.UsageError` (exit code 2) before any
+  request is built. `--fields` is now validated against the
+  `CheckFieldEnum` (`CampaignIds`, `AdGroupIds`, `AdIds`,
+  `CampaignsStat`); unknown values, empty / comma-only inputs and the
+  WSDL `minOccurs=1` violation are caught up-front. Refs: Closes #228.
+- `direct sitelinks add` accepts `\|` as a literal pipe inside
+  `--sitelink` spec strings, so UTM templates like
+  `cid|{campaign_id}|gid|{gbid}` survive parsing. Two new structural
+  sources mirror the `keywords.add` #218 pattern:
+  `--sitelink-json '<JSON-array>'` (inline) and
+  `--sitelinks-from-file <path.jsonl>` (one object per line); sources
+  are mutually exclusive. Unknown JSON keys are rejected with the
+  offending key surfaced (no silent data loss), and missing
+  `Title`/`Href` rows are rejected with the row index. Refs:
+  Closes #221, Closes #220.
+- `direct v4 *` commands now validate request body shape against
+  `V4_METHOD_CONTRACTS` before sending. Documented param shapes
+  (`PARAM_ARRAY` / `PARAM_OBJECT` / `PARAM_OPTIONAL_OBJECT` /
+  `PARAM_SCALAR`) raise `click.UsageError` on mismatch — the request
+  never reaches the network. Undocumented-shape methods are split by
+  contract safety: `SAFETY_READ` (e.g. `GetKeywordsSuggestion`)
+  emits a stderr warning and proceeds; `SAFETY_WRITE` /
+  `SAFETY_DANGEROUS` (e.g. `PayCampaignsByCard`) fail-closed with a
+  remediation pointer to `V4_METHOD_CONTRACTS`. Refs: Closes #182.
+- Regression tests that lock down subtype validation invariants from
+  the `#210` umbrella repro matrix. Nine new `SILENT_LOSS_PROBES` in
+  `tests/test_wsdl_parity_gate.py` cover per-type rejection across
+  `campaigns add`, `adgroups add`, `ads add`, `bidmodifiers add` and
+  `strategies add` (test-only — the corrected rejection behavior was
+  shipped earlier in 0.3.9 via #198 audit follow-up PRs). Three new
+  non-regression tests in `tests/test_dry_run.py` lock down
+  `strategies update` field aliases (`AverageCpcPerFilter →
+  FilterAverageCpc`, `PayForConversion → Cpa`) and confirm that
+  `AverageCpa` update without `--goal-id` stays WSDL-valid
+  (`GoalId` is `minOccurs=0` on update). Refs: Closes #210.
+
+**Fixed:**
+
+- `direct keywords add` in bulk mode (`--from-file` / `--keywords-json`,
+  shipped in 0.3.9 / #218) now surfaces per-item `Errors` instead of
+  swallowing them and exiting 0 with raw JSON. The per-chunk loop now
+  calls `raise_for_api_result_errors` and the final response goes
+  through `format_output`, so the 8800 Client-Login guidance and the
+  full `Errors` payload propagate through the existing exception
+  handler. The partial-success diagnostic ("these keywords were
+  already created in Yandex Direct") only lists items Yandex actually
+  accepted. Refs: Closes #211.
+- `direct_cli/auth.py::_write_json` no longer leaks a file descriptor
+  when `chmod` fails between `tempfile.mkstemp` and `os.fdopen`.
+  Descriptor ownership is now tracked via a sentinel; cleanup errors
+  in `os.close` / `os.unlink` use `contextlib.suppress(OSError)` so
+  the original exception is preserved. Refs: Closes #154.
+
 ## 0.3.9
 
 **Added:**

{direct_cli-0.3.9 → direct_cli-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.9
+Version: 0.3.10
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT

{direct_cli-0.3.9 → direct_cli-0.3.10}/direct_cli/auth.py

@@ -3,6 +3,7 @@ Authentication module for Direct CLI
 """
 
 import base64
+import contextlib
 import hashlib
 import json
 import logging
@@ -148,10 +149,15 @@ def _write_json(path: Path, payload: Dict[str, Any]) -> None:
     try:
         os.chmod(tmp, 0o600)
         with os.fdopen(fd, "w", encoding="utf-8") as f:
+            fd = -1  # ownership transferred to the file object
             f.write(json.dumps(payload, ensure_ascii=False, indent=2))
         os.replace(tmp, path)
     except Exception:
-        os.unlink(tmp)
+        if fd != -1:
+            with contextlib.suppress(OSError):
+                os.close(fd)
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
         raise
 
 

direct_cli-0.3.10/direct_cli/commands/changes.py

@@ -0,0 +1,175 @@
+"""
+Changes commands
+"""
+
+import click
+
+from ..api import create_client
+from ..output import format_output, print_error
+from ..utils import get_default_fields, parse_datetime, parse_ids
+
+
+@click.group()
+def changes():
+    """Check for changes"""
+
+
+_CHECK_FIELD_NAMES = frozenset({"CampaignIds", "AdGroupIds", "AdIds", "CampaignsStat"})
+
+
+@changes.command()
+@click.option(
+    "--campaign-ids",
+    help="Comma-separated campaign IDs (up to 3000). Mutually exclusive with "
+    "--ad-group-ids and --ad-ids.",
+)
+@click.option(
+    "--ad-group-ids",
+    help="Comma-separated ad group IDs (up to 10000). Mutually exclusive with "
+    "--campaign-ids and --ad-ids.",
+)
+@click.option(
+    "--ad-ids",
+    help="Comma-separated ad IDs (up to 50000). Mutually exclusive with "
+    "--campaign-ids and --ad-group-ids.",
+)
+@click.option(
+    "--timestamp",
+    required=True,
+    help="Timestamp for changes check (YYYY-MM-DDTHH:MM:SS)",
+)
+@click.option(
+    "--fields",
+    help="Comma-separated FieldNames; allowed values: "
+    "CampaignIds, AdGroupIds, AdIds, CampaignsStat. "
+    "Defaults to all four when omitted.",
+)
+@click.option("--format", "output_format", default="json", help="Output format")
+@click.option("--output", help="Output file")
+@click.pass_context
+def check(
+    ctx, campaign_ids, ad_group_ids, ad_ids, timestamp, fields, output_format, output
+):
+    """Check changes for campaigns, ad groups, or ads.
+
+    Exactly one of --campaign-ids, --ad-group-ids, --ad-ids must be provided —
+    the Yandex Direct ``Changes.check`` method declares these three filters as
+    mutually exclusive.
+    """
+    sources_used = (
+        (1 if campaign_ids else 0) + (1 if ad_group_ids else 0) + (1 if ad_ids else 0)
+    )
+    if sources_used == 0:
+        raise click.UsageError(
+            "Provide exactly one of: --campaign-ids, --ad-group-ids, --ad-ids."
+        )
+    if sources_used > 1:
+        raise click.UsageError(
+            "--campaign-ids, --ad-group-ids, and --ad-ids are mutually "
+            "exclusive — provide exactly one."
+        )
+
+    if fields:
+        field_names = [f.strip() for f in fields.split(",") if f.strip()]
+        if not field_names:
+            raise click.UsageError(
+                "--fields produced an empty list; provide at least one of: "
+                f"{', '.join(sorted(_CHECK_FIELD_NAMES))}."
+            )
+        unknown = [f for f in field_names if f not in _CHECK_FIELD_NAMES]
+        if unknown:
+            raise click.UsageError(
+                "Unknown --fields value(s): "
+                f"{', '.join(unknown)}. Allowed: "
+                f"{', '.join(sorted(_CHECK_FIELD_NAMES))}."
+            )
+    else:
+        field_names = get_default_fields("changes")
+
+    if campaign_ids:
+        id_field, id_flag, id_raw = "CampaignIds", "--campaign-ids", campaign_ids
+    elif ad_group_ids:
+        id_field, id_flag, id_raw = "AdGroupIds", "--ad-group-ids", ad_group_ids
+    else:
+        id_field, id_flag, id_raw = "AdIds", "--ad-ids", ad_ids
+    try:
+        id_value = parse_ids(id_raw)
+    except ValueError as exc:
+        raise click.UsageError(f"{id_flag}: {exc}")
+    if not id_value:
+        raise click.UsageError(f"{id_flag} produced no valid IDs.")
+
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        params = {
+            id_field: id_value,
+            "Timestamp": parse_datetime(timestamp),
+            "FieldNames": field_names,
+        }
+
+        body = {"method": "check", "params": params}
+
+        result = client.changes().post(data=body)
+        format_output(result.data, output_format, output)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@changes.command()
+@click.option(
+    "--timestamp",
+    required=True,
+    help="Timestamp for changes check (YYYY-MM-DDTHH:MM:SS)",
+)
+@click.option("--format", "output_format", default="json", help="Output format")
+@click.option("--output", help="Output file")
+@click.pass_context
+def check_campaigns(ctx, timestamp, output_format, output):
+    """Check campaigns changes"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        params = {"Timestamp": parse_datetime(timestamp)}
+
+        body = {"method": "checkCampaigns", "params": params}
+
+        result = client.changes().post(data=body)
+        format_output(result.data, output_format, output)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@changes.command()
+@click.option("--format", "output_format", default="json", help="Output format")
+@click.option("--output", help="Output file")
+@click.pass_context
+def check_dictionaries(ctx, output_format, output):
+    """Check dictionaries changes"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+
+        body = {"method": "checkDictionaries", "params": {}}
+
+        result = client.changes().post(data=body)
+        format_output(result.data, output_format, output)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()

{direct_cli-0.3.9 → direct_cli-0.3.10}/direct_cli/commands/keywords.py

@@ -9,7 +9,12 @@ from typing import Any, Dict, Iterator, List, Optional
 import click
 
 from ..api import create_client
-from ..output import format_json, format_output, print_error
+from ..output import (
+    format_json,
+    format_output,
+    print_error,
+    raise_for_api_result_errors,
+)
 from ..utils import add_criteria_csv, parse_ids, get_default_fields, MICRO_RUBLES
 
 # Yandex Direct API "keywords.add" caps a single AddItems request at 10
@@ -434,9 +439,17 @@ def _bulk_add(
             )
             body = {"method": "add", "params": {"Keywords": chunk}}
             response = client.keywords().post(data=body)
-            all_results.extend(_normalize_add_results(response().extract()))
+            chunk_results = _normalize_add_results(response().extract())
+            # Only items without per-item Errors are "already created" — the
+            # partial-success diagnostic must not lie about failed items.
+            all_results.extend(
+                item
+                for item in chunk_results
+                if not (isinstance(item, dict) and item.get("Errors"))
+            )
+            raise_for_api_result_errors(chunk_results)
 
-        print(format_json({"AddResults": all_results}, indent=2))
+        format_output({"AddResults": all_results}, "json", None)
     except click.UsageError:
         raise
     except Exception as e:

direct_cli-0.3.10/direct_cli/commands/sitelinks.py

@@ -0,0 +1,249 @@
+"""
+Sitelinks commands
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+import click
+
+from ..api import create_client
+from ..output import format_output, print_error
+from ..utils import get_default_fields, parse_ids, parse_sitelink_specs
+
+_SITELINK_FIELDS = ("Title", "Href", "Description")
+
+
+def _normalize_sitelink_row(row: Any, index: int) -> Dict[str, str]:
+    if not isinstance(row, dict):
+        raise click.UsageError(
+            f"Sitelink #{index}: expected a JSON object, got {type(row).__name__}"
+        )
+
+    unknown = sorted(set(row) - set(_SITELINK_FIELDS))
+    if unknown:
+        allowed = ", ".join(_SITELINK_FIELDS)
+        raise click.UsageError(
+            f"Unknown field {unknown[0]!r} in sitelink #{index}; allowed: {allowed}"
+        )
+
+    if "Title" not in row or not str(row.get("Title") or "").strip():
+        raise click.UsageError(f"Sitelink #{index}: missing required field 'Title'")
+    if "Href" not in row or not str(row.get("Href") or "").strip():
+        raise click.UsageError(f"Sitelink #{index}: missing required field 'Href'")
+
+    item: Dict[str, str] = {
+        "Title": str(row["Title"]).strip(),
+        "Href": str(row["Href"]).strip(),
+    }
+    description = row.get("Description")
+    if description is not None and str(description).strip():
+        item["Description"] = str(description).strip()
+    return item
+
+
+def _load_sitelinks_from_inline(json_str: str) -> List[Any]:
+    try:
+        decoded = json.loads(json_str)
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(f"--sitelink-json: invalid JSON: {exc.msg}")
+    if not isinstance(decoded, list):
+        raise click.UsageError(
+            "--sitelink-json must be a JSON array of sitelink objects"
+        )
+    return decoded
+
+
+def _load_sitelinks_from_file(path: str) -> List[Any]:
+    file_path = Path(path)
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise click.UsageError(f"Cannot read --sitelinks-from-file {path!r}: {exc}")
+
+    rows: List[Any] = []
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError as exc:
+            raise click.UsageError(
+                f"--sitelinks-from-file line {line_number}: invalid JSON: {exc.msg}"
+            )
+    return rows
+
+
+@click.group()
+def sitelinks():
+    """Manage sitelinks"""
+
+
+@sitelinks.command()
+@click.option("--ids", help="Comma-separated sitelink 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.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def get(ctx, ids, limit, fetch_all, output_format, output, fields, dry_run):
+    """Get sitelinks"""
+    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("sitelinks")
+
+        criteria = {}
+        if ids:
+            criteria["Ids"] = parse_ids(ids)
+
+        params = {"FieldNames": field_names}
+        if criteria:
+            params["SelectionCriteria"] = criteria
+
+        if limit:
+            params["Page"] = {"Limit": limit}
+
+        body = {"method": "get", "params": params}
+
+        if dry_run:
+            format_output(body, "json", None)
+            return
+
+        result = client.sitelinks().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()
+
+
+@sitelinks.command()
+@click.option(
+    "--sitelink",
+    "sitelinks_specs",
+    multiple=True,
+    help="Sitelink spec: TITLE|HREF[|DESCRIPTION]. Escape literal '|' as '\\|'.",
+)
+@click.option(
+    "--sitelink-json",
+    "sitelinks_json",
+    help="Inline JSON array of sitelink objects: "
+    '[{"Title":"...","Href":"...","Description":"..."}]',
+)
+@click.option(
+    "--sitelinks-from-file",
+    "sitelinks_from_file",
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    help="JSONL file with one sitelink object per line",
+)
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def add(ctx, sitelinks_specs, sitelinks_json, sitelinks_from_file, dry_run):
+    """Add sitelinks set.
+
+    Provide exactly one source: --sitelink (repeatable), --sitelink-json,
+    or --sitelinks-from-file.
+    """
+    sources_used = (
+        (1 if sitelinks_specs else 0)
+        + (1 if sitelinks_json is not None else 0)
+        + (1 if sitelinks_from_file is not None else 0)
+    )
+    if sources_used == 0:
+        raise click.UsageError(
+            "Provide exactly one of: --sitelink (repeatable), "
+            "--sitelink-json (inline JSON array), or --sitelinks-from-file (JSONL)."
+        )
+    if sources_used > 1:
+        raise click.UsageError(
+            "--sitelink, --sitelink-json, and --sitelinks-from-file are "
+            "mutually exclusive — provide exactly one."
+        )
+
+    try:
+        if sitelinks_specs:
+            try:
+                sitelinks_payload = parse_sitelink_specs(list(sitelinks_specs))
+            except ValueError as exc:
+                raise click.UsageError(str(exc))
+        else:
+            if sitelinks_json is not None:
+                raw_rows = _load_sitelinks_from_inline(sitelinks_json)
+            else:
+                raw_rows = _load_sitelinks_from_file(sitelinks_from_file)
+
+            if not raw_rows:
+                raise click.UsageError("Input contains no sitelink rows.")
+
+            sitelinks_payload = [
+                _normalize_sitelink_row(row, idx)
+                for idx, row in enumerate(raw_rows, start=1)
+            ]
+
+        body = {
+            "method": "add",
+            "params": {"SitelinksSets": [{"Sitelinks": sitelinks_payload}]},
+        }
+
+        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.sitelinks().post(data=body)
+        format_output(result().extract(), "json", None)
+
+    except click.UsageError:
+        raise
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@sitelinks.command()
+@click.option("--id", "set_id", required=True, type=int, help="Sitelinks set ID")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def delete(ctx, set_id, dry_run):
+    """Delete sitelinks set"""
+    try:
+        body = {"method": "delete", "params": {"SelectionCriteria": {"Ids": [set_id]}}}
+
+        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.sitelinks().post(data=body)
+        format_output(result().extract(), "json", None)
+
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()

{direct_cli-0.3.9 → direct_cli-0.3.10}/direct_cli/utils.py

@@ -457,18 +457,48 @@ def parse_retargeting_rule_specs(
     return rules
 
 
+def _split_sitelink_spec(spec: str) -> List[str]:
+    """Split a sitelink spec by '|', treating '\\|' as a literal pipe.
+
+    UTM templates in Yandex Direct use literal '|' inside URLs
+    (e.g. cid|{campaign_id}|gid|{gbid}); allow users to escape it as '\\|'.
+    """
+    parts: List[str] = []
+    current: List[str] = []
+    i = 0
+    while i < len(spec):
+        ch = spec[i]
+        if ch == "\\" and i + 1 < len(spec) and spec[i + 1] == "|":
+            current.append("|")
+            i += 2
+            continue
+        if ch == "|":
+            parts.append("".join(current))
+            current = []
+            i += 1
+            continue
+        current.append(ch)
+        i += 1
+    parts.append("".join(current))
+    return parts
+
+
 def parse_sitelink_specs(specs: Optional[List[str]]) -> Optional[List[Dict[str, str]]]:
-    """Parse repeated TITLE|HREF[|DESCRIPTION] sitelink specs."""
+    """Parse repeated TITLE|HREF[|DESCRIPTION] sitelink specs.
+
+    Literal '|' characters inside any field can be escaped as '\\|'.
+    """
     if not specs:
         return None
 
     sitelinks = []
     for spec in specs:
-        parts = [part.strip() for part in spec.split("|")]
+        parts = [part.strip() for part in _split_sitelink_spec(spec)]
         if len(parts) not in (2, 3):
             raise ValueError(
                 "Invalid sitelink: "
-                f"'{spec}'. Expected format: TITLE|HREF[|DESCRIPTION]"
+                f"'{spec}'. Expected format: TITLE|HREF[|DESCRIPTION]. "
+                "Escape a literal '|' inside a field as '\\|'."
             )
 
         sitelink = {"Title": parts[0], "Href": parts[1]}

direct_cli-0.3.10/direct_cli/v4/__init__.py

@@ -0,0 +1,57 @@
+"""Shared helpers for Yandex Direct v4 Live commands."""
+
+from typing import Any, Optional
+
+import click
+
+from direct_cli.v4_contracts import (
+    PARAM_UNDOCUMENTED_SHAPE_MSG,
+    SAFETY_DANGEROUS,
+    SAFETY_WRITE,
+    get_v4_contract,
+    validate_v4_body_shape,
+)
+
+_UNSAFE_SAFETY_LEVELS = frozenset({SAFETY_WRITE, SAFETY_DANGEROUS})
+
+
+def build_v4_body(method: str, param: Optional[Any] = None) -> dict:
+    """Build a v4 Live request body."""
+    body = {"method": method}
+    if param is not None:
+        body["param"] = param
+    return body
+
+
+def call_v4(client: Any, method: str, param: Optional[Any] = None) -> Any:
+    """Call one v4 Live method and return the extracted response payload."""
+    body = build_v4_body(method, param)
+
+    errors = validate_v4_body_shape(method, body)
+    # Hard errors (shape mismatch, method mismatch) always block.
+    hard_errors = [e for e in errors if PARAM_UNDOCUMENTED_SHAPE_MSG not in e]
+    if hard_errors:
+        raise click.UsageError("; ".join(hard_errors))
+
+    if errors:
+        # Only undocumented-shape errors remain. Fail-closed when the
+        # contract is write/dangerous — we will not blindly post a
+        # financial or write operation whose payload shape we cannot
+        # verify. For read-class undocumented methods (e.g.
+        # GetKeywordsSuggestion) a soft warning is acceptable.
+        safety = get_v4_contract(method).safety
+        if safety in _UNSAFE_SAFETY_LEVELS:
+            raise click.UsageError(
+                f"refusing to send v4 method {method!r}: param shape is "
+                f"undocumented and safety is {safety!r}. "
+                "Add a documented param_shape to V4_METHOD_CONTRACTS "
+                "before exposing this method through the CLI."
+            )
+        click.echo(
+            f"warning: v4 method {method!r} has an undocumented param "
+            "shape; sending request as-is.",
+            err=True,
+        )
+
+    result = client.v4live().post(data=body)
+    return result().extract()