eeroctl 1.7.1__py3-none-any.whl

eeroctl/errors.py

@@ -0,0 +1,156 @@
+"""Centralized error handling for the Eero CLI.
+
+This module provides utilities for translating exceptions to user-friendly
+error messages and appropriate exit codes.
+"""
+
+from typing import Optional, TypeVar
+
+from eero.exceptions import (
+    EeroAPIException,
+    EeroAuthenticationException,
+    EeroException,
+    EeroFeatureUnavailableException,
+    EeroNotFoundException,
+    EeroPremiumRequiredException,
+    EeroRateLimitException,
+    EeroTimeoutException,
+    EeroValidationException,
+)
+from rich.console import Console
+
+from .exit_codes import ExitCode
+
+T = TypeVar("T")
+
+
+def handle_cli_error(
+    e: Exception,
+    console: Console,
+    renderer: Optional[object] = None,
+    context: str = "",
+) -> int:
+    """Handle an exception and return the appropriate exit code.
+
+    This function translates exceptions into user-friendly error messages
+    and determines the correct exit code.
+
+    Args:
+        e: The exception to handle
+        console: Rich console for output
+        renderer: Optional OutputRenderer for JSON output
+        context: Optional context string for better error messages
+
+    Returns:
+        The exit code to use
+    """
+    prefix = f"{context}: " if context else ""
+
+    if isinstance(e, EeroAuthenticationException):
+        console.print(f"[red]{prefix}Authentication required. Run 'eero auth login' first.[/red]")
+        return ExitCode.AUTH_REQUIRED
+
+    elif isinstance(e, EeroNotFoundException):
+        console.print(f"[red]{prefix}{e.resource_type} '{e.resource_id}' not found[/red]")
+        return ExitCode.NOT_FOUND
+
+    elif isinstance(e, EeroPremiumRequiredException):
+        console.print(f"[yellow]{prefix}{e.feature} requires Eero Plus subscription[/yellow]")
+        return ExitCode.PREMIUM_REQUIRED
+
+    elif isinstance(e, EeroFeatureUnavailableException):
+        console.print(f"[yellow]{prefix}{e.feature} is {e.reason}[/yellow]")
+        return ExitCode.FEATURE_UNAVAILABLE
+
+    elif isinstance(e, EeroRateLimitException):
+        console.print(f"[yellow]{prefix}Rate limited. Please wait and try again.[/yellow]")
+        return ExitCode.TIMEOUT
+
+    elif isinstance(e, EeroTimeoutException):
+        console.print(f"[red]{prefix}Request timed out. Check your connection and try again.[/red]")
+        return ExitCode.TIMEOUT
+
+    elif isinstance(e, EeroValidationException):
+        console.print(f"[red]{prefix}Invalid input for '{e.field}': {e.message}[/red]")
+        return ExitCode.USAGE_ERROR
+
+    elif isinstance(e, EeroAPIException):
+        # Map HTTP status codes to exit codes
+        if e.status_code == 401:
+            console.print(
+                f"[red]{prefix}Session expired. Run 'eero auth login' to re-authenticate.[/red]"
+            )
+            return ExitCode.AUTH_REQUIRED
+        elif e.status_code == 403:
+            console.print(f"[red]{prefix}Permission denied: {e.message}[/red]")
+            return ExitCode.FORBIDDEN
+        elif e.status_code == 404:
+            console.print(f"[red]{prefix}Resource not found: {e.message}[/red]")
+            return ExitCode.NOT_FOUND
+        elif e.status_code == 409:
+            console.print(f"[yellow]{prefix}Conflict: {e.message}[/yellow]")
+            return ExitCode.CONFLICT
+        elif e.status_code == 429:
+            console.print(f"[yellow]{prefix}Rate limited. Please wait and try again.[/yellow]")
+            return ExitCode.TIMEOUT
+        else:
+            console.print(f"[red]{prefix}API error ({e.status_code}): {e.message}[/red]")
+            return ExitCode.GENERIC_ERROR
+
+    elif isinstance(e, EeroException):
+        # Generic Eero exception
+        console.print(f"[red]{prefix}{e.message}[/red]")
+        return ExitCode.GENERIC_ERROR
+
+    else:
+        # Unknown exception
+        console.print(f"[red]{prefix}Unexpected error: {e}[/red]")
+        return ExitCode.GENERIC_ERROR
+
+
+def is_premium_error(e: Exception) -> bool:
+    """Check if an exception indicates a premium feature requirement.
+
+    Args:
+        e: Exception to check
+
+    Returns:
+        True if this is a premium-required error
+    """
+    if isinstance(e, EeroPremiumRequiredException):
+        return True
+    # Fallback string matching for generic exceptions
+    error_str = str(e).lower()
+    return "premium" in error_str or "plus" in error_str or "subscription" in error_str
+
+
+def is_feature_unavailable_error(e: Exception, feature_keyword: str) -> bool:
+    """Check if an exception indicates a feature is unavailable.
+
+    Args:
+        e: Exception to check
+        feature_keyword: Keyword to look for in error message
+
+    Returns:
+        True if this is a feature-unavailable error
+    """
+    if isinstance(e, EeroFeatureUnavailableException):
+        return True
+    # Fallback string matching for generic exceptions
+    return feature_keyword.lower() in str(e).lower()
+
+
+def is_not_found_error(e: Exception) -> bool:
+    """Check if an exception indicates a resource was not found.
+
+    Args:
+        e: Exception to check
+
+    Returns:
+        True if this is a not-found error
+    """
+    if isinstance(e, EeroNotFoundException):
+        return True
+    if isinstance(e, EeroAPIException) and e.status_code == 404:
+        return True
+    return "not found" in str(e).lower()

eeroctl/exit_codes.py

@@ -0,0 +1,68 @@
+"""Exit codes for the Eero CLI.
+
+Standard exit codes for consistent behavior across all commands.
+"""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Standard exit codes for the CLI.
+
+    Exit codes must be consistent across all commands for scripting.
+    """
+
+    SUCCESS = 0
+    """Command completed successfully."""
+
+    GENERIC_ERROR = 1
+    """Generic/unexpected error."""
+
+    USAGE_ERROR = 2
+    """Invalid arguments or command usage."""
+
+    AUTH_REQUIRED = 3
+    """Authentication required or session expired."""
+
+    FORBIDDEN = 4
+    """Permission denied/forbidden operation."""
+
+    NOT_FOUND = 5
+    """Resource not found (ID, name, MAC address)."""
+
+    CONFLICT = 6
+    """Conflict or invalid state (e.g., already enabled)."""
+
+    TIMEOUT = 7
+    """Request or operation timed out."""
+
+    SAFETY_RAIL = 8
+    """Safety rail triggered - needs --force or confirmation."""
+
+    # Reserved: 9
+
+    PARTIAL_SUCCESS = 10
+    """Multi-target operation had partial success."""
+
+    PREMIUM_REQUIRED = 11
+    """Feature requires Eero Plus subscription."""
+
+    FEATURE_UNAVAILABLE = 12
+    """Feature is not available on this device or network."""
+
+
+# Exit code descriptions for help text
+EXIT_CODE_DESCRIPTIONS = {
+    ExitCode.SUCCESS: "Operation completed successfully",
+    ExitCode.GENERIC_ERROR: "An unexpected error occurred",
+    ExitCode.USAGE_ERROR: "Invalid command usage or arguments",
+    ExitCode.AUTH_REQUIRED: "Authentication required or session expired",
+    ExitCode.FORBIDDEN: "Permission denied for this operation",
+    ExitCode.NOT_FOUND: "Requested resource not found",
+    ExitCode.CONFLICT: "Operation conflicts with current state",
+    ExitCode.TIMEOUT: "Operation timed out",
+    ExitCode.SAFETY_RAIL: "Safety confirmation required (use --force)",
+    ExitCode.PARTIAL_SUCCESS: "Operation partially completed",
+    ExitCode.PREMIUM_REQUIRED: "Feature requires Eero Plus subscription",
+    ExitCode.FEATURE_UNAVAILABLE: "Feature not available on this device",
+}

eeroctl/formatting/__init__.py

@@ -0,0 +1,90 @@
+"""Formatting utilities for the Eero CLI.
+
+This module provides reusable formatting functions for displaying
+Eero network data using Rich panels and tables.
+
+This __init__.py re-exports all public functions from submodules
+for backward compatibility with existing imports.
+"""
+
+# Base utilities
+from .base import (
+    DetailLevel,
+    build_panel,
+    console,
+    field,
+    field_bool,
+    field_status,
+    format_bool,
+    format_datetime,
+    format_device_status,
+    format_eero_status,
+    format_enabled,
+    format_network_status,
+    get_network_status_value,
+)
+
+# Device formatting
+from .device import (
+    create_devices_table,
+    print_device_details,
+)
+
+# Eero device formatting
+from .eero import (
+    create_eeros_table,
+    print_eero_details,
+)
+
+# Miscellaneous formatting
+from .misc import (
+    create_blacklist_table,
+    print_speedtest_results,
+)
+
+# Network formatting
+from .network import (
+    create_network_table,
+    print_network_details,
+)
+
+# Profile formatting
+from .profile import (
+    create_profile_devices_table,
+    create_profiles_table,
+    print_profile_details,
+)
+
+# Re-export all public names
+__all__ = [
+    # Base
+    "console",
+    "DetailLevel",
+    "get_network_status_value",
+    "format_network_status",
+    "format_device_status",
+    "format_eero_status",
+    "format_bool",
+    "format_enabled",
+    "build_panel",
+    "field",
+    "field_bool",
+    "field_status",
+    "format_datetime",
+    # Network
+    "create_network_table",
+    "print_network_details",
+    # Eero
+    "create_eeros_table",
+    "print_eero_details",
+    # Device
+    "create_devices_table",
+    "print_device_details",
+    # Profile
+    "create_profiles_table",
+    "create_profile_devices_table",
+    "print_profile_details",
+    # Misc
+    "print_speedtest_results",
+    "create_blacklist_table",
+]

eeroctl/formatting/base.py

@@ -0,0 +1,181 @@
+"""Base formatting utilities for the Eero CLI.
+
+This module provides shared formatting functions, constants, and helpers
+used across all formatting modules.
+"""
+
+from typing import Any, List, Literal, Optional
+
+from eero.const import EeroDeviceStatus
+from eero.models.network import Network
+from rich.console import Console
+from rich.panel import Panel
+
+# Create console for rich output
+console = Console()
+
+# Type alias for detail level
+DetailLevel = Literal["brief", "full"]
+
+
+# ==================== Status Formatting Helpers ====================
+
+
+def get_network_status_value(network: Network) -> str:
+    """Extract the status value from a network, handling both enum and string types.
+
+    Args:
+        network: Network model instance
+
+    Returns:
+        Status string value (e.g., "online", "offline")
+    """
+    if not network.status:
+        return "unknown"
+    # Handle both enum (has .value) and string types
+    if hasattr(network.status, "value"):
+        return str(network.status.value)
+    return str(network.status)
+
+
+def format_network_status(status_value: str) -> tuple[str, str]:
+    """Format network status into display text and style.
+
+    Args:
+        status_value: Clean status string (e.g., "online", "offline", "updating")
+
+    Returns:
+        Tuple of (display_text, style)
+    """
+    status_lower = status_value.lower()
+    if status_lower in ("online", "connected"):
+        return "online", "green"
+    elif status_lower == "offline":
+        return "offline", "red"
+    elif status_lower == "updating":
+        return "updating", "yellow"
+    return status_value or "unknown", "dim"
+
+
+def format_device_status(status: EeroDeviceStatus) -> tuple[str, str]:
+    """Format device status into display text and style.
+
+    Args:
+        status: Device status enum
+
+    Returns:
+        Tuple of (display_text, style)
+    """
+    if status == EeroDeviceStatus.CONNECTED:
+        return "connected", "green"
+    elif status == EeroDeviceStatus.BLOCKED:
+        return "blocked", "red"
+    elif status == EeroDeviceStatus.DISCONNECTED:
+        return "disconnected", "yellow"
+    return "unknown", "dim"
+
+
+def format_eero_status(status: str) -> tuple[str, str]:
+    """Format eero status into display text and style.
+
+    Args:
+        status: Eero status string
+
+    Returns:
+        Tuple of (display_text, style)
+    """
+    if status == "green":
+        return status, "green"
+    return status, "red"
+
+
+def format_bool(value: bool, true_text: str = "Yes", false_text: str = "No") -> str:
+    """Format a boolean value with color coding.
+
+    Args:
+        value: Boolean value
+        true_text: Text to display when True
+        false_text: Text to display when False
+
+    Returns:
+        Formatted string
+    """
+    if value:
+        return f"[green]{true_text}[/green]"
+    return f"[dim]{false_text}[/dim]"
+
+
+def format_enabled(value: bool) -> str:
+    """Format an enabled/disabled value."""
+    return format_bool(value, "Enabled", "Disabled")
+
+
+# ==================== Panel Building Helpers ====================
+
+
+def build_panel(lines: List[str], title: str, border_style: str = "blue") -> Panel:
+    """Build a panel from a list of formatted lines.
+
+    Args:
+        lines: List of formatted text lines
+        title: Panel title
+        border_style: Rich border style
+
+    Returns:
+        Rich Panel object
+    """
+    # Filter out None and empty lines
+    content = "\n".join(line for line in lines if line)
+    return Panel(content, title=title, border_style=border_style)
+
+
+def field(label: str, value: Any, default: str = "Unknown") -> str:
+    """Format a single field line.
+
+    Args:
+        label: Field label
+        value: Field value
+        default: Default value if value is None/empty
+
+    Returns:
+        Formatted line string
+    """
+    display_value = value if value is not None else default
+    if display_value == "":
+        display_value = default
+    return f"[bold]{label}:[/bold] {display_value}"
+
+
+def field_bool(label: str, value: Optional[bool]) -> str:
+    """Format a boolean field line."""
+    return f"[bold]{label}:[/bold] {format_enabled(bool(value)) if value is not None else '[dim]Unknown[/dim]'}"
+
+
+def field_status(label: str, text: str, style: str) -> str:
+    """Format a status field line with color."""
+    return f"[bold]{label}:[/bold] [{style}]{text}[/{style}]"
+
+
+# ==================== Date/Time Formatting ====================
+
+
+def format_datetime(dt: Any, include_time: bool = True) -> str:
+    """Format a datetime value for display.
+
+    Args:
+        dt: Datetime object or string
+        include_time: Whether to include time component
+
+    Returns:
+        Formatted datetime string
+    """
+    if dt is None:
+        return "Unknown"
+    if hasattr(dt, "strftime"):
+        fmt = "%Y-%m-%d %H:%M:%S" if include_time else "%Y-%m-%d"
+        return dt.strftime(fmt)
+    # Handle string datetime
+    dt_str = str(dt)
+    if include_time:
+        return dt_str[:19].replace("T", " ")
+    return dt_str[:10]