direct-cli 0.2.4__tar.gz → 0.2.6__tar.gz

direct_cli-0.2.6/.github/workflows/api-coverage.yml

@@ -0,0 +1,153 @@
+name: API Coverage
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  test-and-report:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run fast coverage suites
+        run: |
+          pytest -q tests/test_api_coverage.py tests/test_dry_run.py tests/test_cli.py tests/test_comprehensive.py tests/test_reports_drift.py
+
+      - name: Build API coverage report
+        run: |
+          python scripts/build_api_coverage_report.py > api_coverage_report.json
+
+      - name: Publish API coverage summary
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("api_coverage_report.json").read_text())
+          summary = report["summary"]
+          print("## API coverage summary")
+          print()
+          print(f"- Services checked: {summary['services_checked']}")
+          print(f"- Missing methods: {summary['missing_service_methods']}")
+          print(f"- Unexpected methods: {summary['unexpected_service_methods']}")
+          print(f"- Strict parity OK: {summary['strict_parity_ok']}")
+          print(f"- Alias groups: {len(report['aliases'])}")
+          print(f"- Non-WSDL services: {len(report['non_wsdl_services'])}")
+          print(f"- CLI helpers: {len(report['cli_helpers'])}")
+          PY
+
+      - name: Upload API coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-coverage-report-py${{ matrix.python-version }}
+          path: api_coverage_report.json
+
+  monitor-live-wsdl:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check live WSDL drift
+        run: |
+          python scripts/check_wsdl_drift.py > wsdl_drift_report.json
+
+      - name: Publish WSDL drift summary
+        if: always()
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("wsdl_drift_report.json").read_text())
+          print("## WSDL drift summary")
+          print()
+          print(f"- Services checked: {report['services_checked']}")
+          print(f"- Missing cache files: {report['missing_cache_count']}")
+          print(f"- Drifted services: {report['drift_count']}")
+          for item in report["drift"][:10]:
+              print(f"- Drift: {item['service']}")
+          PY
+
+      - name: Upload WSDL drift report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: wsdl-drift-report
+          path: wsdl_drift_report.json
+
+  monitor-live-reports:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check live reports drift
+        run: |
+          python scripts/check_reports_drift.py > reports_drift_report.json
+
+      - name: Publish reports drift summary
+        if: always()
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("reports_drift_report.json").read_text())
+          print("## Reports drift summary")
+          print()
+          print(f"- Sources checked: {report.get('sources_checked', 0)}")
+          print(f"- Missing cache files: {report.get('missing_cache_count', 0)}")
+          print(f"- Drifted sections: {report.get('drift_count', 0)}")
+          for item in report.get("drift", [])[:10]:
+              print(f"- Drift: {item['section']}")
+          PY
+
+      - name: Upload reports drift report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: reports-drift-report
+          path: reports_drift_report.json

{direct_cli-0.2.4 → direct_cli-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.2.4
+Version: 0.2.6
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -31,6 +31,9 @@ Requires-Dist: pytest-recording>=0.13; extra == "dev"
 Requires-Dist: vcrpy>=6.0; extra == "dev"
 Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: flake8>=4.0; extra == "dev"
+Requires-Dist: requests>=2.0; extra == "dev"
+Requires-Dist: beautifulsoup4>=4.12; extra == "dev"
+Requires-Dist: lxml>=4.9; extra == "dev"
 
 # Direct CLI
 
@@ -231,6 +234,34 @@ pytest -m integration -v            # read-only integration tests (needs token)
 pytest -m integration_write -v      # write cassette replay (no token needed)
 ```
 
+### API Coverage And Drift Monitoring
+
+The project now distinguishes four surfaces:
+
+| Surface | Coverage strategy |
+|---|---|
+| Canonical WSDL-backed SOAP services | `tests/test_api_coverage.py` verifies strict service/method parity and dry-run request-schema coverage or explicit exclusions |
+| Non-WSDL services (`reports`) | Explicit contract tests |
+| Canonical CLI aliases | Checked as aliases, not counted as separate API surface |
+| Intentional CLI-only helpers | Explicitly allowlisted with reasons in `direct_cli/wsdl_coverage.py` |
+
+`100% coverage` in this project means full coverage of the supported
+**canonical API surface**. Alias groups and CLI-only helpers remain supported,
+but they are tracked outside the strict parity metric.
+
+Useful maintenance commands:
+
+```bash
+python scripts/build_api_coverage_report.py
+python scripts/refresh_wsdl_cache.py
+python scripts/check_wsdl_drift.py
+```
+
+CI runs a scheduled API coverage workflow that:
+- runs the fast coverage suites;
+- uploads a machine-readable API coverage report artifact;
+- checks the cached WSDL files against the live Yandex Direct API on schedule.
+
 #### Re-recording write cassettes
 
 The write tests replay HTTP traffic captured from the Yandex Direct **sandbox**

{direct_cli-0.2.4 → direct_cli-0.2.6}/README.md

@@ -197,6 +197,34 @@ pytest -m integration -v            # read-only integration tests (needs token)
 pytest -m integration_write -v      # write cassette replay (no token needed)
 ```
 
+### API Coverage And Drift Monitoring
+
+The project now distinguishes four surfaces:
+
+| Surface | Coverage strategy |
+|---|---|
+| Canonical WSDL-backed SOAP services | `tests/test_api_coverage.py` verifies strict service/method parity and dry-run request-schema coverage or explicit exclusions |
+| Non-WSDL services (`reports`) | Explicit contract tests |
+| Canonical CLI aliases | Checked as aliases, not counted as separate API surface |
+| Intentional CLI-only helpers | Explicitly allowlisted with reasons in `direct_cli/wsdl_coverage.py` |
+
+`100% coverage` in this project means full coverage of the supported
+**canonical API surface**. Alias groups and CLI-only helpers remain supported,
+but they are tracked outside the strict parity metric.
+
+Useful maintenance commands:
+
+```bash
+python scripts/build_api_coverage_report.py
+python scripts/refresh_wsdl_cache.py
+python scripts/check_wsdl_drift.py
+```
+
+CI runs a scheduled API coverage workflow that:
+- runs the fast coverage suites;
+- uploads a machine-readable API coverage report artifact;
+- checks the cached WSDL files against the live Yandex Direct API on schedule.
+
 #### Re-recording write cassettes
 
 The write tests replay HTTP traffic captured from the Yandex Direct **sandbox**

{direct_cli-0.2.4 → direct_cli-0.2.6}/direct_cli/api.py

@@ -14,6 +14,12 @@ def create_client(
     sandbox: bool = False,
     op_token_ref: Optional[str] = None,
     op_login_ref: Optional[str] = None,
+    processing_mode: str = "auto",
+    return_money_in_micros: bool = False,
+    skip_report_header: bool = True,
+    skip_column_header: bool = False,
+    skip_report_summary: bool = True,
+    language: Optional[str] = None,
 ) -> YandexDirect:
     """
     Create YandexDirect client
@@ -24,6 +30,12 @@ def create_client(
         sandbox: Use sandbox API
         op_token_ref: 1Password secret reference for token
         op_login_ref: 1Password secret reference for login
+        processing_mode: Report processing mode (auto/online/offline)
+        return_money_in_micros: Return monetary values in micros
+        skip_report_header: Omit report header row
+        skip_column_header: Omit column header row
+        skip_report_summary: Omit report summary row
+        language: Accept-Language for report (ru/en)
 
     Returns:
         YandexDirect client instance
@@ -39,12 +51,13 @@ def create_client(
         retry_if_exceeded_limit=True,
         retries_if_server_error=5,
         # Report settings
-        processing_mode="auto",
+        processing_mode=processing_mode,
         wait_report=True,
-        return_money_in_micros=False,
-        skip_report_header=True,
-        skip_column_header=False,
-        skip_report_summary=True,
+        return_money_in_micros=return_money_in_micros,
+        skip_report_header=skip_report_header,
+        skip_column_header=skip_column_header,
+        skip_report_summary=skip_report_summary,
+        language=language,
     )
 
 

{direct_cli-0.2.4 → direct_cli-0.2.6}/direct_cli/cli.py

@@ -35,6 +35,7 @@ from .commands.smartadtargets import smartadtargets
 from .commands.businesses import businesses
 from .commands.keywordsresearch import keywordsresearch
 from .commands.dynamicads import dynamicads
+from .commands.advideos import advideos
 
 # Load .env file
 load_dotenv()
@@ -133,6 +134,7 @@ cli.add_command(smartadtargets)
 cli.add_command(businesses)
 cli.add_command(keywordsresearch)
 cli.add_command(dynamicads)
+cli.add_command(advideos)
 
 # Canonical aliases expected by external integrations.
 cli.add_command(dynamicads, name="dynamictargets")

{direct_cli-0.2.4 → direct_cli-0.2.6}/direct_cli/commands/adextensions.py

@@ -68,11 +68,14 @@ def get(ctx, ids, types, limit, fetch_all, output_format, output, fields):
 @click.option(
     "--type",
     "ext_type",
-    required=True,
     help=(
-        "Extension type (UX hint — Callout, Sitelinks, Vcard, …). "
-        "Not sent to the API; the API derives the type from the nested "
-        "field name inside --json."
+        "Legacy UX hint; NOT forwarded to the API. The Yandex Direct "
+        "API derives the extension type from the nested field name "
+        "inside --json (Callout / Sitelinks / Vcard / ...), so the "
+        "only flag that actually matters is --json.  Previously this "
+        "option was required=True but silently discarded, which "
+        "forced every caller to pass a value that did nothing.  See "
+        "axisrow/direct-cli#25."
     ),
 )
 @click.option("--json", "extra_json", required=True, help="Extension data in JSON")
@@ -88,7 +91,7 @@ def add(ctx, ext_type, extra_json, dry_run):
     ``{"Type": ext_type, ...}`` and the sandbox rejected the extra
     key as ``unknown parameter Type``.
     """
-    _ = ext_type  # consumed only for argument validation / UX clarity
+    _ = ext_type  # intentionally unused — kept as UX hint only
     try:
         ext_data = json.loads(extra_json)
 
@@ -114,21 +117,26 @@ def add(ctx, ext_type, extra_json, dry_run):
 
 @adextensions.command()
 @click.option("--id", "extension_id", required=True, type=int, help="Extension ID")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
-def delete(ctx, extension_id):
+def delete(ctx, extension_id, dry_run):
     """Delete ad extension"""
     try:
+        body = {
+            "method": "delete",
+            "params": {"SelectionCriteria": {"Ids": [extension_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"),
         )
 
-        body = {
-            "method": "delete",
-            "params": {"SelectionCriteria": {"Ids": [extension_id]}},
-        }
-
         result = client.adextensions().post(data=body)
         format_output(result().extract(), "json", None)
 

{direct_cli-0.2.4 → direct_cli-0.2.6}/direct_cli/commands/adgroups.py

@@ -84,7 +84,18 @@ def get(
 @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(
+    "--type",
+    "group_type",
+    default="TEXT_AD_GROUP",
+    help=(
+        "Ad group type (case-insensitive). The Yandex Direct API derives "
+        "the group type from nested objects (MobileAppAdGroup / "
+        "DynamicTextAdGroup / SmartAdGroup / ...), not from a top-level "
+        "Type discriminator. Convenience flags only build a TEXT_AD_GROUP; "
+        "for other types pass the matching nested object via --json."
+    ),
+)
 @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")
@@ -96,12 +107,21 @@ def add(ctx, name, campaign_id, group_type, region_ids, extra_json, dry_run):
         # AdGroupAddItem — the group type is inferred from the presence of
         # MobileAppAdGroup / DynamicTextAdGroup / SmartAdGroup / etc.
         # sub-objects, exactly like Ads (see fix in commands/ads.py).
-        # The --type CLI option is preserved for backward compatibility but
-        # is no longer forwarded to the API; users wanting non-text group
-        # types must pass the matching sub-object via --json.
+        # Previously --type was accepted but silently discarded — users
+        # passing --type MOBILE_APP_AD_GROUP got a TEXT_AD_GROUP with no
+        # warning.  Now we normalize case and fail loudly if the caller
+        # asks for anything except TEXT_AD_GROUP.  See axisrow/direct-cli#23.
         # Refs: https://yandex.ru/dev/direct/doc/ref-v5/adgroups/add.html
+        group_type_norm = (group_type or "TEXT_AD_GROUP").upper().replace("-", "_")
+
+        if group_type_norm != "TEXT_AD_GROUP" and not extra_json:
+            raise click.UsageError(
+                f"--type {group_type} requires --json with the "
+                f"ad-group-type-specific nested object "
+                f"(e.g. DynamicTextAdGroup, SmartAdGroup, MobileAppAdGroup)."
+            )
+
         adgroup_data = {"Name": name, "CampaignId": campaign_id}
-        _ = group_type  # acknowledged-but-unused
 
         if region_ids:
             adgroup_data["RegionIds"] = parse_ids(region_ids)
@@ -125,6 +145,8 @@ def add(ctx, name, campaign_id, group_type, region_ids, extra_json, dry_run):
         result = client.adgroups().post(data=body)
         format_output(result().extract(), "json", None)
 
+    except click.UsageError:
+        raise
     except Exception as e:
         print_error(str(e))
         raise click.Abort()
@@ -174,21 +196,26 @@ def update(ctx, adgroup_id, name, status, extra_json, dry_run):
 
 @adgroups.command()
 @click.option("--id", "adgroup_id", required=True, type=int, help="Ad group ID")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
-def delete(ctx, adgroup_id):
+def delete(ctx, adgroup_id, dry_run):
     """Delete ad group"""
     try:
+        body = {
+            "method": "delete",
+            "params": {"SelectionCriteria": {"Ids": [adgroup_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"),
         )
 
-        body = {
-            "method": "delete",
-            "params": {"SelectionCriteria": {"Ids": [adgroup_id]}},
-        }
-
         result = client.adgroups().post(data=body)
         format_output(result().extract(), "json", None)
 

{direct_cli-0.2.4 → direct_cli-0.2.6}/direct_cli/commands/adimages.py

@@ -92,21 +92,26 @@ def add(ctx, image_json, dry_run):
 
 @adimages.command()
 @click.option("--hash", "image_hash", required=True, help="Ad image hash")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
-def delete(ctx, image_hash):
+def delete(ctx, image_hash, dry_run):
     """Delete ad image"""
     try:
+        body = {
+            "method": "delete",
+            "params": {"SelectionCriteria": {"AdImageHashes": [image_hash]}},
+        }
+
+        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"),
         )
 
-        body = {
-            "method": "delete",
-            "params": {"SelectionCriteria": {"AdImageHashes": [image_hash]}},
-        }
-
         result = client.adimages().post(data=body)
         format_output(result().extract(), "json", None)