google-analytics-cli 0.1.0__py3-none-any.whl

ga_cli/utils/errors.py

@@ -0,0 +1,150 @@
+"""Error handling utilities.
+
+Provides consistent error formatting for Google API errors.
+When the output format is JSON, errors are emitted as structured JSON
+to stderr with distinct exit codes for different failure categories.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import NoReturn
+
+from .output import error as print_error
+
+
+def format_api_error(err: Exception) -> str:
+    """Extract a human-readable message from a Google API error.
+
+    Handles googleapiclient.errors.HttpError and generic exceptions.
+    """
+    # google-api-python-client raises HttpError
+    from googleapiclient.errors import HttpError
+
+    if isinstance(err, HttpError):
+        try:
+            detail = json.loads(err.content.decode())
+            message = detail.get("error", {}).get("message", str(err))
+            return message
+        except (json.JSONDecodeError, AttributeError):
+            return str(err)
+
+    return str(err)
+
+
+def classify_error(err: Exception) -> tuple[int, str]:
+    """Classify an exception into (exit_code, category).
+
+    Exit codes:
+        1 — client_error: bad input, missing flags, validation failure
+        2 — auth_error: not authenticated, token expired, permission denied (401/403)
+        3 — api_error: Google returned 4xx (not auth) or 5xx
+        4 — network_error: connection timeout, DNS failure, unreachable
+
+    Returns:
+        (exit_code, category)
+    """
+    from googleapiclient.errors import HttpError
+
+    if isinstance(err, HttpError):
+        status = err.resp.status
+        if status in (401, 403):
+            return 2, "auth_error"
+        return 3, "api_error"
+
+    # Auth-specific exceptions
+    try:
+        from google.auth.exceptions import DefaultCredentialsError, RefreshError
+
+        if isinstance(err, (RefreshError, DefaultCredentialsError)):
+            return 2, "auth_error"
+    except ImportError:
+        pass
+
+    # Network errors
+    try:
+        from requests.exceptions import ConnectionError as RequestsConnectionError
+        from requests.exceptions import Timeout
+
+        if isinstance(err, (RequestsConnectionError, Timeout)):
+            return 4, "network_error"
+    except ImportError:
+        pass
+
+    try:
+        from urllib3.exceptions import NewConnectionError
+
+        if isinstance(err, NewConnectionError):
+            return 4, "network_error"
+    except ImportError:
+        pass
+
+    if isinstance(err, OSError) and _is_network_os_error(err):
+        return 4, "network_error"
+
+    # RuntimeError from our own auth code ("Not authenticated...")
+    if isinstance(err, RuntimeError) and "auth" in str(err).lower():
+        return 2, "auth_error"
+
+    return 3, "api_error"
+
+
+def _is_network_os_error(err: OSError) -> bool:
+    """Check if an OSError is network-related (vs file I/O, permissions, etc.)."""
+    import errno
+
+    network_errnos = {
+        errno.ECONNREFUSED,
+        errno.ECONNRESET,
+        errno.ECONNABORTED,
+        errno.ETIMEDOUT,
+        errno.EHOSTUNREACH,
+        errno.ENETUNREACH,
+    }
+    return err.errno in network_errnos
+
+
+def handle_error(err: Exception) -> NoReturn:
+    """Print error and exit with a classified exit code.
+
+    When output format is JSON (explicit or non-TTY), emit structured
+    JSON to stderr. Otherwise, emit human-readable Rich text.
+    """
+    from .output import get_current_output_format
+
+    exit_code, category = classify_error(err)
+    message = format_api_error(err)
+    fmt = get_current_output_format()
+
+    if fmt == "json":
+        payload: dict = {
+            "error": True,
+            "exit_code": exit_code,
+            "category": category,
+            "message": message,
+        }
+        from googleapiclient.errors import HttpError
+
+        if isinstance(err, HttpError):
+            payload["status_code"] = err.resp.status
+
+        # Write raw JSON to stderr — avoid Rich Console which may wrap lines
+        print(json.dumps(payload, default=str), file=sys.stderr)
+    else:
+        print_error(message)
+
+    sys.exit(exit_code)
+
+
+def require_options(options: dict, required: list[str]) -> None:
+    """Validate that required options are present.
+
+    Raises typer.BadParameter if any are missing.
+    """
+    import typer
+
+    missing = [k for k in required if not options.get(k)]
+    if missing:
+        formatted = [f"--{k.replace('_', '-')}" for k in missing]
+        raise typer.BadParameter(f"Missing required options: {', '.join(formatted)}")

ga_cli/utils/output.py

@@ -0,0 +1,209 @@
+"""Output formatting utilities.
+
+Supports three formats:
+- json: Machine-readable JSON (default when piping)
+- table: Human-readable Rich tables (default for TTY)
+- compact: Minimal ID + name output
+
+Equivalent to GTM CLI's utils/output.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Optional
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+err_console = Console(stderr=True)
+
+OutputFormat = str  # "json" | "table" | "compact"
+
+# Global flags set from main.py callback
+_quiet = False
+_current_output_format: str = "table"
+
+
+def set_output_format(fmt: str) -> None:
+    """Store the resolved output format for use by error handling."""
+    global _current_output_format
+    _current_output_format = fmt
+
+
+def get_current_output_format() -> str:
+    """Return the current output format. Used by errors.py for structured errors."""
+    return _current_output_format
+
+
+def set_quiet(value: bool) -> None:
+    """Enable or disable quiet mode (suppresses info/warn/success)."""
+    global _quiet
+    _quiet = value
+
+
+def set_no_color(value: bool) -> None:
+    """Enable or disable no-color mode on both consoles."""
+    global console, err_console
+    if value:
+        console = Console(no_color=True, highlight=False)
+        err_console = Console(stderr=True, no_color=True, highlight=False)
+
+
+def is_tty() -> bool:
+    """Check if stdout is a terminal."""
+    return sys.stdout.isatty()
+
+
+def get_output_format(requested: Optional[str] = None) -> str:
+    """Get effective output format. Defaults to JSON when piping."""
+    if requested:
+        return requested
+    return "table" if is_tty() else "json"
+
+
+def resolve_output_format(cli_value: Optional[str] = None) -> str:
+    """Resolve and track the output format from a subcommand's -o flag.
+
+    Replaces the common pattern:
+        effective_format = get_effective_value(output_format, "output_format") or "table"
+
+    This resolves CLI flag > config > TTY detection, then updates the
+    global format so that handle_error() uses the correct format.
+    """
+    from ..config.store import get_effective_value
+
+    fmt = get_effective_value(cli_value, "output_format") or ("table" if is_tty() else "json")
+    set_output_format(fmt)
+    return fmt
+
+
+def output(
+    data: Any,
+    fmt: str = "table",
+    columns: Optional[list[str]] = None,
+    headers: Optional[list[str]] = None,
+) -> None:
+    """Output data in the specified format.
+
+    Args:
+        data: The data to display (list of dicts, or a single dict).
+        fmt: Output format — "json", "table", or "compact".
+        columns: Which keys to show in table mode.
+        headers: Column headers for table mode.
+    """
+    effective_fmt = get_output_format(fmt)
+
+    if effective_fmt == "json":
+        print(json.dumps(data, indent=2, default=str))
+
+    elif effective_fmt == "compact":
+        if isinstance(data, list):
+            for item in data:
+                if isinstance(item, dict):
+                    name = item.get("name", item.get("displayName", ""))
+                    display = item.get("displayName", "")
+                    print(f"{name}\t{display}")
+                else:
+                    print(str(item))
+        else:
+            print(json.dumps(data, default=str))
+
+    else:  # table
+        if isinstance(data, list) and len(data) > 0:
+            _output_table(data, columns, headers)
+        elif isinstance(data, dict):
+            _output_object(data)
+        elif isinstance(data, list) and len(data) == 0:
+            console.print("No results found.")
+        else:
+            print(str(data))
+
+
+def _output_table(
+    data: list[dict],
+    columns: Optional[list[str]] = None,
+    headers: Optional[list[str]] = None,
+) -> None:
+    """Render a list of dicts as a Rich table."""
+    if not data:
+        console.print("No results found.")
+        return
+
+    cols = columns or _get_default_columns(data[0])
+    hdrs = headers or [_format_header(c) for c in cols]
+
+    table = Table(show_lines=True)
+    for h in hdrs:
+        table.add_column(h, style="bold")
+
+    for item in data:
+        row = [_format_value(item.get(c)) for c in cols]
+        table.add_row(*row)
+
+    console.print(table)
+
+
+def _output_object(data: dict) -> None:
+    """Render a single dict as key-value pairs."""
+    table = Table(show_lines=True)
+    table.add_column("Key", style="bold")
+    table.add_column("Value")
+
+    for key, value in data.items():
+        if value is not None:
+            table.add_row(_format_header(key), _format_value(value))
+
+    console.print(table)
+
+
+def _get_default_columns(item: dict) -> list[str]:
+    """Pick sensible default columns for GA resources."""
+    priority = ["name", "displayName", "type", "createTime", "updateTime"]
+    return [c for c in priority if c in item] or list(item.keys())[:5]
+
+
+def _format_header(key: str) -> str:
+    """Convert snake_case or camelCase to Title Case."""
+    import re
+    # camelCase → spaces
+    s = re.sub(r"([A-Z])", r" \1", key)
+    # snake_case → spaces
+    s = s.replace("_", " ")
+    return s.strip().title()
+
+
+def _format_value(value: Any) -> str:
+    """Format a value for table display."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "[green]Yes[/green]" if value else "[red]No[/red]"
+    if isinstance(value, list):
+        return f"[{len(value)} items]" if value else "[]"
+    if isinstance(value, dict):
+        return json.dumps(value, default=str)
+    return str(value)
+
+
+# Convenience functions for styled messages (equivalent to GTM CLI)
+def success(message: str) -> None:
+    if not _quiet:
+        err_console.print(f"[green]OK[/green] {message}")
+
+
+def error(message: str) -> None:
+    # Errors are NEVER suppressed, even in quiet mode
+    err_console.print(f"[red]Error:[/red] {message}")
+
+
+def warn(message: str) -> None:
+    if not _quiet:
+        err_console.print(f"[yellow]Warning:[/yellow] {message}")
+
+
+def info(message: str) -> None:
+    if not _quiet:
+        err_console.print(f"[blue]Info:[/blue] {message}")

ga_cli/utils/pagination.py

@@ -0,0 +1,93 @@
+"""Pagination helpers.
+
+Provides both:
+- paginate_all(): API-level pagination (fetches all pages from Google API)
+- paginate(): Client-side pagination (slices a local list for display)
+
+Equivalent to GTM CLI's pagination.ts + paginateAll() in client.ts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, TypeVar
+
+from ..config.constants import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+
+T = TypeVar("T")
+
+
+def paginate_all(
+    list_fn: Callable[..., Any],
+    result_key: str,
+    **kwargs: Any,
+) -> list:
+    """Paginate through all results from a Google API list operation.
+
+    Args:
+        list_fn: The API list method (e.g., admin.accounts().list)
+        result_key: The key in the response containing the items array
+        **kwargs: Additional arguments to pass to the list method
+
+    Returns:
+        All items across all pages.
+
+    Usage:
+        accounts = paginate_all(
+            lambda **kw: admin.accounts().list(**kw).execute(),
+            "accounts",
+            pageSize=200,
+        )
+    """
+    all_results = []
+    page_token = None
+
+    while True:
+        if page_token:
+            kwargs["pageToken"] = page_token
+
+        response = list_fn(**kwargs)
+        items = response.get(result_key, [])
+        all_results.extend(items)
+
+        page_token = response.get("nextPageToken")
+        if not page_token:
+            break
+
+    return all_results
+
+
+@dataclass
+class PaginatedResult:
+    """Result of client-side pagination."""
+    items: list
+    page: int
+    page_size: int
+    total_items: int
+    total_pages: int
+    has_next_page: bool
+    has_prev_page: bool
+
+
+def paginate(items: list, page: int = 1, page_size: int = DEFAULT_PAGE_SIZE) -> PaginatedResult:
+    """Client-side pagination of a local list.
+
+    Equivalent to GTM CLI's paginate() in pagination.ts.
+    """
+    page = max(1, page)
+    page_size = min(MAX_PAGE_SIZE, max(1, page_size))
+
+    total_items = len(items)
+    total_pages = max(1, (total_items + page_size - 1) // page_size)
+    start = (page - 1) * page_size
+    end = min(start + page_size, total_items)
+
+    return PaginatedResult(
+        items=items[start:end],
+        page=page,
+        page_size=page_size,
+        total_items=total_items,
+        total_pages=total_pages,
+        has_next_page=page < total_pages,
+        has_prev_page=page > 1,
+    )