google-ads-cli 0.0.1__py3-none-any.whl

googleadscli/commands/mutate.py

@@ -0,0 +1,53 @@
+"""`gads mutate <resource>` -- generischer Create/Update/Remove fuer jede Ressource."""
+
+from __future__ import annotations
+
+import typer
+
+from googleadscli import formatting, proto_bridge
+from googleadscli.commands import _common
+from googleadscli.utils import load_json_arg, normalize_customer_id
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("mutate")
+    def mutate_cmd(
+        ctx: typer.Context,
+        resource: str = typer.Argument(
+            ..., help="Ressourcen-Key in snake_case, z.B. 'campaign', 'ad_group_criterion'"
+        ),
+        customer_id: str = typer.Option(..., "--customer-id", "-c"),
+        operations_json: str = typer.Option(
+            ...,
+            "--operations-json",
+            "-o",
+            help="JSON-Array von Operationen ({'create'|'update'|'remove': ...}); "
+            "mit '@pfad.json' aus Datei laden",
+        ),
+        dry_run: bool = typer.Option(
+            False, "--dry-run", help="validate_only: nur validieren, nichts aendern"
+        ),
+        partial_failure: bool = typer.Option(
+            False, "--partial-failure", help="Einzelne fehlschlagende Operationen nicht die ganze Anfrage abbrechen lassen"
+        ),
+    ) -> None:
+        """Fuehrt create/update/remove-Operationen fuer eine Ressource aus."""
+
+        def _run() -> None:
+            operations = load_json_arg(operations_json)
+            if not isinstance(operations, list):
+                raise ValueError("--operations-json muss ein JSON-Array von Operationen sein.")
+
+            client = _common.build_client(ctx)
+            result = proto_bridge.run_mutate(
+                client,
+                resource,
+                normalize_customer_id(customer_id),
+                operations,
+                partial_failure=partial_failure,
+                validate_only=dry_run,
+                version=ctx.obj["version"],
+            )
+            formatting.render(result, fmt=ctx.obj["format"])
+
+        _common.run_guarded(ctx, _run)

googleadscli/commands/query.py

@@ -0,0 +1,35 @@
+"""`gads query` -- generische GAQL-Ausfuehrung."""
+
+from __future__ import annotations
+
+import typer
+
+from googleadscli import formatting, gaql
+from googleadscli.commands import _common
+from googleadscli.utils import normalize_customer_id
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("query")
+    def query_cmd(
+        ctx: typer.Context,
+        customer_id: str = typer.Option(..., "--customer-id", "-c", help="Google Ads Customer ID (CID)"),
+        gaql_query: str = typer.Option(..., "--gaql", "-q", help="GAQL-Query-String"),
+        paged: bool = typer.Option(
+            False, "--paged", help="search/SearchPager statt search_stream verwenden"
+        ),
+    ) -> None:
+        """Fuehrt eine beliebige GAQL-Abfrage aus (Reporting/Lesen)."""
+
+        def _run() -> None:
+            client = _common.build_client(ctx)
+            rows = gaql.run_query(
+                client,
+                normalize_customer_id(customer_id),
+                gaql_query,
+                paged=paged,
+                version=ctx.obj["version"],
+            )
+            formatting.render(rows, fmt=ctx.obj["format"])
+
+        _common.run_guarded(ctx, _run)

googleadscli/config.py

@@ -0,0 +1,128 @@
+"""Konfigurations-Precedence: CLI-Flags > GOOGLE_ADS_*-Env-Vars > Config-Datei."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "google-ads-cli" / "google-ads.yaml"
+LEGACY_CONFIG_PATH = Path.home() / "google-ads.yaml"
+
+# Feldname (google-ads.yaml / GoogleAdsClient) -> Env-Var-Name
+ENV_VAR_MAP = {
+    "developer_token": "GOOGLE_ADS_DEVELOPER_TOKEN",
+    # OAuth2 Installed-App-Flow (interaktiver Consent, siehe 'gads auth login').
+    "client_id": "GOOGLE_ADS_CLIENT_ID",
+    "client_secret": "GOOGLE_ADS_CLIENT_SECRET",
+    "refresh_token": "GOOGLE_ADS_REFRESH_TOKEN",
+    # OAuth2 Service-Account-Flow: JSON-Schluesseldatei aus der Google Cloud
+    # Console, deren client_email direkt als Nutzer auf dem Google-Ads-Konto
+    # (oder MCC) hinterlegt wird -- kein interaktiver Consent noetig.
+    "json_key_file_path": "GOOGLE_ADS_JSON_KEY_FILE_PATH",
+    # Nur fuer Domain-Wide-Delegation noetig (Service Account impersoniert
+    # einen echten Workspace-Nutzer). Bei direkt freigeschaltetem Service-
+    # Account-Zugriff auf das Ads-Konto bleibt dies leer.
+    "impersonated_email": "GOOGLE_ADS_IMPERSONATED_EMAIL",
+    # Application Default Credentials (z.B. GOOGLE_APPLICATION_CREDENTIALS
+    # oder 'gcloud auth application-default login').
+    "use_application_default_credentials": "GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS",
+    "login_customer_id": "GOOGLE_ADS_LOGIN_CUSTOMER_ID",
+    "linked_customer_id": "GOOGLE_ADS_LINKED_CUSTOMER_ID",
+}
+
+CONFIG_PATH_ENV_VAR = "GOOGLE_ADS_CONFIGURATION_FILE_PATH"
+
+_TRUTHY = {"true", "1", "yes"}
+
+
+class ConfigError(Exception):
+    """Fehlerhafte oder fehlende Google-Ads-Konfiguration."""
+
+
+def _resolve_config_path(explicit_path: str | None) -> Path | None:
+    if explicit_path:
+        return Path(explicit_path).expanduser()
+    env_path = os.environ.get(CONFIG_PATH_ENV_VAR)
+    if env_path:
+        return Path(env_path).expanduser()
+    if DEFAULT_CONFIG_PATH.exists():
+        return DEFAULT_CONFIG_PATH
+    if LEGACY_CONFIG_PATH.exists():
+        return LEGACY_CONFIG_PATH
+    return None
+
+
+def _load_config_file(path: Path | None) -> dict[str, Any]:
+    if path is None or not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"Ungueltiges Format in Config-Datei: {path}")
+    return data
+
+
+def load_merged_config(
+    *,
+    config_path: str | None = None,
+    cli_overrides: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Baut das finale Config-Dict fuer GoogleAdsClient.load_from_dict.
+
+    Precedence (niedrig -> hoch): Config-Datei < Env-Vars < CLI-Flags.
+    """
+    merged: dict[str, Any] = _load_config_file(_resolve_config_path(config_path))
+
+    for field, env_var in ENV_VAR_MAP.items():
+        value = os.environ.get(env_var)
+        if value:
+            merged[field] = value
+
+    if cli_overrides:
+        merged.update({k: v for k, v in cli_overrides.items() if v is not None})
+
+    if isinstance(merged.get("use_application_default_credentials"), str):
+        merged["use_application_default_credentials"] = (
+            merged["use_application_default_credentials"].strip().lower() in _TRUTHY
+        )
+
+    # Erzwingt die Bridge-Invariante: proto-plus-Wrapper (nicht rohe Protobuf-Messages).
+    # proto-plus liefert mit .to_dict()/.from_json() und Dict-Konstruktoren eine deutlich
+    # einfachere generische JSON<->Message-Konvertierung als rohe pb2-Messages, und die
+    # GAPIC-Methodensignaturen sind ohnehin stets gegen proto-plus-Typen annotiert.
+    merged["use_proto_plus"] = True
+
+    has_installed_app = all(merged.get(f) for f in ("client_id", "client_secret", "refresh_token"))
+    has_service_account = bool(merged.get("json_key_file_path"))
+    has_adc = bool(merged.get("use_application_default_credentials"))
+
+    if not (has_installed_app or has_service_account or has_adc):
+        raise ConfigError(
+            "Keine Google-Ads-Zugangsdaten gefunden. Eine der folgenden Methoden wird benoetigt: "
+            "(1) OAuth Installed-App-Flow (client_id, client_secret, refresh_token -- via "
+            "'gads auth login' einrichten), (2) Service-Account-JSON-Schluesseldatei "
+            "(json_key_file_path, z.B. per --json-key-file-path/GOOGLE_ADS_JSON_KEY_FILE_PATH; "
+            "die client_email der Schluesseldatei muss als Nutzer auf dem Google-Ads-Konto "
+            "hinterlegt sein), oder (3) Application Default Credentials "
+            "(use_application_default_credentials=true). "
+            f"Alternativ eine Config-Datei unter {DEFAULT_CONFIG_PATH} anlegen. "
+            "'developer_token' ist optional (nicht noetig bei Cloud-managed Access ohne "
+            "klassischen Developer Token)."
+        )
+
+    return merged
+
+
+def write_config_file(data: dict[str, Any], path: Path | None = None) -> Path:
+    """Schreibt die Config-Datei mit restriktiven Dateirechten (0600)."""
+    target = path or DEFAULT_CONFIG_PATH
+    target.parent.mkdir(parents=True, exist_ok=True)
+    to_write = dict(data)
+    to_write.setdefault("use_proto_plus", True)
+    with target.open("w", encoding="utf-8") as fh:
+        yaml.safe_dump(to_write, fh, default_flow_style=False)
+    target.chmod(0o600)
+    return target

googleadscli/errors.py

@@ -0,0 +1,81 @@
+"""Strukturierte Fehlerbehandlung fuer Agenten: JSON auf stderr, klare Exit-Codes."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import NoReturn
+
+from google.ads.googleads.errors import GoogleAdsException
+
+from googleadscli.config import ConfigError
+from googleadscli.proto_bridge import BridgeError
+
+EXIT_OK = 0
+EXIT_CLI_ERROR = 1
+EXIT_API_ERROR = 2
+EXIT_INTERNAL_ERROR = 70
+
+
+def format_google_ads_exception(ex: GoogleAdsException) -> dict:
+    errors = []
+    if ex.failure is not None:
+        failure_dict = type(ex.failure).to_dict(
+            ex.failure,
+            use_integers_for_enums=False,
+            preserving_proto_field_name=True,
+            always_print_fields_with_no_presence=False,
+        )
+        for err in failure_dict.get("errors", []):
+            error_code = err.get("error_code", {}) or {}
+            code_type = next(iter(error_code), None)
+            field_path = None
+            elements = err.get("location", {}).get("field_path_elements", [])
+            if elements:
+                parts = []
+                for el in elements:
+                    part = el.get("field_name", "")
+                    if "index" in el:
+                        part += f"[{el['index']}]"
+                    parts.append(part)
+                field_path = ".".join(parts)
+            errors.append(
+                {
+                    "error_code_type": code_type,
+                    "error_code": error_code.get(code_type) if code_type else None,
+                    "message": err.get("message"),
+                    "field_path": field_path,
+                    "trigger": err.get("trigger"),
+                }
+            )
+
+    status_code = None
+    if getattr(ex, "call", None) is not None and hasattr(ex.call, "code"):
+        code = ex.call.code()
+        status_code = getattr(code, "name", str(code))
+
+    return {
+        "type": "GoogleAdsException",
+        "request_id": ex.request_id,
+        "status_code": status_code,
+        "errors": errors,
+    }
+
+
+def emit_error(payload: dict, *, exit_code: int) -> NoReturn:
+    print(json.dumps(payload, indent=2, ensure_ascii=False), file=sys.stderr)
+    raise SystemExit(exit_code)
+
+
+def handle_exception(exc: Exception, *, debug: bool = False) -> NoReturn:
+    if isinstance(exc, GoogleAdsException):
+        emit_error(format_google_ads_exception(exc), exit_code=EXIT_API_ERROR)
+    if isinstance(exc, (ConfigError, BridgeError, ValueError)):
+        emit_error({"type": type(exc).__name__, "message": str(exc)}, exit_code=EXIT_CLI_ERROR)
+
+    if debug:
+        raise exc
+    emit_error(
+        {"type": "InternalError", "message": str(exc)},
+        exit_code=EXIT_INTERNAL_ERROR,
+    )

googleadscli/formatting.py

@@ -0,0 +1,55 @@
+"""Ausgabeformatierung: json (Standard, agentenfreundlich), table, csv."""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from typing import Any
+
+
+def _flatten(d: dict, parent_key: str = "") -> dict:
+    items: dict[str, Any] = {}
+    for key, value in d.items():
+        full_key = f"{parent_key}.{key}" if parent_key else key
+        if isinstance(value, dict):
+            items.update(_flatten(value, full_key))
+        else:
+            items[full_key] = value
+    return items
+
+
+def render(data: Any, *, fmt: str = "json") -> None:
+    if fmt == "json":
+        print(json.dumps(data, indent=2, ensure_ascii=False, default=str))
+        return
+
+    rows = data if isinstance(data, list) else [data]
+    flat_rows = [_flatten(row) if isinstance(row, dict) else {"value": row} for row in rows]
+
+    if fmt == "csv":
+        if not flat_rows:
+            return
+        fieldnames = list({key for row in flat_rows for key in row})
+        writer = csv.DictWriter(sys.stdout, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(flat_rows)
+        return
+
+    if fmt == "table":
+        from rich.console import Console
+        from rich.table import Table
+
+        if not flat_rows:
+            print("(keine Ergebnisse)")
+            return
+        fieldnames = list({key for row in flat_rows for key in row})
+        table = Table(show_header=True, header_style="bold")
+        for name in fieldnames:
+            table.add_column(name)
+        for row in flat_rows:
+            table.add_row(*(str(row.get(name, "")) for name in fieldnames))
+        Console().print(table)
+        return
+
+    raise ValueError(f"Unbekanntes Ausgabeformat: {fmt}")

googleadscli/gaql.py

@@ -0,0 +1,37 @@
+"""Ausfuehrung beliebiger GAQL-Abfragen ueber GoogleAdsService."""
+
+from __future__ import annotations
+
+from googleadscli.proto_bridge import DEFAULT_VERSION, message_to_dict
+
+
+def run_query(
+    client,
+    customer_id: str,
+    gaql: str,
+    *,
+    paged: bool = False,
+    version: str = DEFAULT_VERSION,
+) -> list[dict]:
+    """Fuehrt eine GAQL-Abfrage aus und gibt eine flache Liste von Row-Dicts zurueck.
+
+    Standard: GoogleAdsService.search_stream (Batches werden zu einer flachen
+    Liste zusammengefuehrt). Mit paged=True wird stattdessen search/SearchPager
+    verwendet (Kompatibilitaets-/Debug-Option).
+    """
+    service = client.get_service("GoogleAdsService", version=version)
+    rows: list[dict] = []
+
+    if paged:
+        request_cls = type(client.get_type("SearchGoogleAdsRequest", version=version))
+        request = request_cls(customer_id=customer_id, query=gaql)
+        for row in service.search(request=request):
+            rows.append(message_to_dict(row))
+        return rows
+
+    request_cls = type(client.get_type("SearchGoogleAdsStreamRequest", version=version))
+    request = request_cls(customer_id=customer_id, query=gaql)
+    for batch in service.search_stream(request=request):
+        for row in batch.results:
+            rows.append(message_to_dict(row))
+    return rows