aws-inventory-manager 0.17.12__py3-none-any.whl

src/utils/__init__.py

@@ -0,0 +1,12 @@
+"""Utility modules for AWS Baseline Snapshot tool."""
+
+from .export import export_to_csv, export_to_json
+from .hash import compute_config_hash
+from .logging import setup_logging
+
+__all__ = [
+    "setup_logging",
+    "compute_config_hash",
+    "export_to_json",
+    "export_to_csv",
+]

src/utils/export.py

@@ -0,0 +1,305 @@
+"""Export utilities for JSON and CSV formats."""
+
+import csv
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List
+
+if TYPE_CHECKING:
+    from src.models.report import DetailedResource, ResourceSummary, SnapshotMetadata
+
+logger = logging.getLogger(__name__)
+
+
+def export_to_json(data: Any, filepath: str) -> Path:
+    """Export data to JSON file.
+
+    Args:
+        data: Data to export (must be JSON-serializable)
+        filepath: Destination file path
+
+    Returns:
+        Path to exported file
+    """
+    path = Path(filepath)
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, default=str)
+
+    logger.info(f"Exported data to JSON: {path}")
+    return path
+
+
+def export_to_csv(data: List[Dict[str, Any]], filepath: str) -> Path:
+    """Export list of dictionaries to CSV file.
+
+    Args:
+        data: List of dictionaries to export
+        filepath: Destination file path
+
+    Returns:
+        Path to exported file
+
+    Raises:
+        ValueError: If data is empty or not a list of dicts
+    """
+    if not data:
+        raise ValueError("Cannot export empty data to CSV")
+
+    if not isinstance(data, list) or not isinstance(data[0], dict):
+        raise ValueError("Data must be a list of dictionaries for CSV export")
+
+    path = Path(filepath)
+
+    # Get fieldnames from first item
+    fieldnames = list(data[0].keys())
+
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(data)
+
+    logger.info(f"Exported {len(data)} rows to CSV: {path}")
+    return path
+
+
+def flatten_dict(d: Dict[str, Any], parent_key: str = "", sep: str = "_") -> Dict[str, Any]:
+    """Flatten a nested dictionary for CSV export.
+
+    Args:
+        d: Dictionary to flatten
+        parent_key: Parent key for nested items
+        sep: Separator for concatenating keys
+
+    Returns:
+        Flattened dictionary
+    """
+    from typing import Any, List, Tuple
+
+    items: List[Tuple[str, Any]] = []
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        if isinstance(v, dict):
+            items.extend(flatten_dict(v, new_key, sep=sep).items())
+        elif isinstance(v, list):
+            # Convert lists to comma-separated strings
+            items.append((new_key, ", ".join(str(x) for x in v)))
+        else:
+            items.append((new_key, v))
+    return dict(items)
+
+
+def detect_format(filepath: str) -> str:
+    """
+    Detect export format from file extension.
+
+    Args:
+        filepath: Path to file
+
+    Returns:
+        Format string: 'json', 'csv', or 'txt'
+
+    Raises:
+        ValueError: If format is not supported
+    """
+    path = Path(filepath)
+    extension = path.suffix.lower()
+
+    if extension == ".json":
+        return "json"
+    elif extension == ".csv":
+        return "csv"
+    elif extension == ".txt":
+        return "txt"
+    else:
+        raise ValueError(f"Unsupported export format '{extension}'. " f"Supported formats: .json, .csv, .txt")
+
+
+def export_report_json(
+    filepath: str,
+    metadata: "SnapshotMetadata",
+    summary: "ResourceSummary",
+    resources: List["DetailedResource"],
+) -> Path:
+    """
+    Export snapshot report to JSON format.
+
+    Args:
+        filepath: Destination file path
+        metadata: Snapshot metadata
+        summary: Resource summary
+        resources: List of detailed resources
+
+    Returns:
+        Path to exported file
+
+    Raises:
+        FileExistsError: If file already exists
+        FileNotFoundError: If parent directory doesn't exist
+    """
+    path = Path(filepath)
+
+    # Check if file already exists
+    if path.exists():
+        raise FileExistsError(f"Export file '{filepath}' already exists")
+
+    # Check if parent directory exists
+    if not path.parent.exists():
+        raise FileNotFoundError(f"Parent directory '{path.parent}' does not exist")
+
+    # Build report data structure
+    report_data = {
+        "snapshot_metadata": {
+            "name": metadata.name,
+            "created_at": metadata.created_at.isoformat(),
+            "account_id": metadata.account_id,
+            "regions": metadata.regions,
+            "inventory_name": metadata.inventory_name,
+            "total_resource_count": metadata.total_resource_count,
+        },
+        "summary": {
+            "total_count": summary.total_count,
+            "by_service": dict(summary.by_service),
+            "by_region": dict(summary.by_region),
+            "by_type": dict(summary.by_type),
+        },
+        "resources": [
+            {
+                "arn": r.arn,
+                "resource_type": r.resource_type,
+                "name": r.name,
+                "region": r.region,
+                "tags": r.tags,
+                "created_at": r.created_at.isoformat() if r.created_at else None,
+                "config_hash": r.config_hash,
+            }
+            for r in resources
+        ],
+    }
+
+    # Write to file
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(report_data, f, indent=2)
+
+    logger.info(f"Exported report to JSON: {path}")
+    return path
+
+
+def export_report_csv(filepath: str, resources: List["DetailedResource"]) -> Path:
+    """
+    Export resources to CSV format.
+
+    Args:
+        filepath: Destination file path
+        resources: List of detailed resources
+
+    Returns:
+        Path to exported file
+
+    Raises:
+        FileExistsError: If file already exists
+        FileNotFoundError: If parent directory doesn't exist
+    """
+    path = Path(filepath)
+
+    # Check if file already exists
+    if path.exists():
+        raise FileExistsError(f"Export file '{filepath}' already exists")
+
+    # Check if parent directory exists
+    if not path.parent.exists():
+        raise FileNotFoundError(f"Parent directory '{path.parent}' does not exist")
+
+    # Write CSV
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+
+        # Write header
+        writer.writerow(["ARN", "ResourceType", "Name", "Region", "CreatedAt", "Tags"])
+
+        # Write resources
+        for resource in resources:
+            writer.writerow(
+                [
+                    resource.arn,
+                    resource.resource_type,
+                    resource.name,
+                    resource.region,
+                    resource.created_at.isoformat() if resource.created_at else "",
+                    json.dumps(resource.tags) if resource.tags else "{}",
+                ]
+            )
+
+    logger.info(f"Exported {len(resources)} resources to CSV: {path}")
+    return path
+
+
+def export_report_txt(
+    filepath: str,
+    metadata: "SnapshotMetadata",
+    summary: "ResourceSummary",
+) -> Path:
+    """
+    Export report summary to plain text format.
+
+    Args:
+        filepath: Destination file path
+        metadata: Snapshot metadata
+        summary: Resource summary
+
+    Returns:
+        Path to exported file
+
+    Raises:
+        FileExistsError: If file already exists
+        FileNotFoundError: If parent directory doesn't exist
+    """
+    path = Path(filepath)
+
+    # Check if file already exists
+    if path.exists():
+        raise FileExistsError(f"Export file '{filepath}' already exists")
+
+    # Check if parent directory exists
+    if not path.parent.exists():
+        raise FileNotFoundError(f"Parent directory '{path.parent}' does not exist")
+
+    # Build text content
+    lines = []
+    lines.append("=" * 65)
+    lines.append(f"Snapshot Report: {metadata.name}")
+    lines.append("=" * 65)
+    lines.append("")
+    lines.append(f"Inventory:     {metadata.inventory_name}")
+    lines.append(f"Account ID:    {metadata.account_id}")
+    lines.append(f"Created:       {metadata.created_at.strftime('%Y-%m-%d %H:%M:%S UTC')}")
+    lines.append(f"Regions:       {metadata.region_summary}")
+    lines.append("")
+    lines.append("─" * 65)
+    lines.append("")
+    lines.append("Resource Summary")
+    lines.append("")
+    lines.append(f"Total Resources: {summary.total_count:,}")
+    lines.append("")
+
+    if summary.by_service:
+        lines.append("By Service:")
+        for service, count in summary.top_services(limit=10):
+            percentage = (count / summary.total_count) * 100 if summary.total_count > 0 else 0
+            lines.append(f"  {service:20} {count:5}  ({percentage:.1f}%)")
+        lines.append("")
+
+    if summary.by_region:
+        lines.append("By Region:")
+        for region, count in summary.top_regions(limit=10):
+            percentage = (count / summary.total_count) * 100 if summary.total_count > 0 else 0
+            lines.append(f"  {region:20} {count:5}  ({percentage:.1f}%)")
+        lines.append("")
+
+    # Write to file
+    with open(path, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines))
+
+    logger.info(f"Exported report to TXT: {path}")
+    return path

src/utils/hash.py

@@ -0,0 +1,60 @@
+"""Configuration hashing utility for change detection."""
+
+import hashlib
+import json
+from typing import Any, Dict, Set
+
+# Attributes to exclude from hashing (volatile data)
+EXCLUDE_ATTRIBUTES: Set[str] = {
+    "ResponseMetadata",
+    "LastModifiedDate",
+    "CreatedDate",
+    "CreateDate",
+    "State",
+    "Status",
+    "RequestId",
+    "VersionId",
+    "LastUpdateTime",
+    "LastUpdatedTime",
+    "ModifiedTime",
+}
+
+
+def compute_config_hash(resource_data: Dict[str, Any]) -> str:
+    """Compute stable SHA256 hash of resource configuration.
+
+    This hash is used for change detection. Volatile attributes
+    (timestamps, states, etc.) are excluded to prevent false positives.
+
+    Args:
+        resource_data: Resource configuration dictionary
+
+    Returns:
+        64-character SHA256 hex string
+    """
+    # Deep copy and remove excluded attributes
+    clean_data = _remove_volatile_attributes(resource_data, EXCLUDE_ATTRIBUTES)
+
+    # Normalize: sort keys for deterministic JSON
+    normalized = json.dumps(clean_data, sort_keys=True, default=str)
+
+    # Hash
+    return hashlib.sha256(normalized.encode()).hexdigest()
+
+
+def _remove_volatile_attributes(data: Any, exclude_set: Set[str]) -> Any:
+    """Recursively remove excluded attributes from nested dict/list.
+
+    Args:
+        data: Data structure to clean (dict, list, or primitive)
+        exclude_set: Set of attribute names to exclude
+
+    Returns:
+        Cleaned data structure
+    """
+    if isinstance(data, dict):
+        return {k: _remove_volatile_attributes(v, exclude_set) for k, v in data.items() if k not in exclude_set}
+    elif isinstance(data, list):
+        return [_remove_volatile_attributes(item, exclude_set) for item in data]
+    else:
+        return data

src/utils/logging.py

@@ -0,0 +1,63 @@
+"""Logging configuration for AWS Baseline Snapshot tool."""
+
+import logging
+import sys
+from typing import Optional
+
+
+def setup_logging(level: str = "INFO", log_file: Optional[str] = None, verbose: bool = False) -> None:
+    """Configure logging for the application.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARN, ERROR)
+        log_file: Optional log file path
+        verbose: If True, show detailed logs; if False, suppress all but critical
+    """
+    # Convert string level to logging constant
+    numeric_level = getattr(logging, level.upper(), logging.INFO)
+
+    # In non-verbose mode, suppress all logs except CRITICAL
+    # User will only see styled Rich console output
+    if not verbose:
+        numeric_level = logging.CRITICAL
+
+    # Create formatter
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(numeric_level)
+
+    # Remove existing handlers
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    # Console handler (only add if verbose or log_file specified)
+    if verbose or log_file:
+        console_handler = logging.StreamHandler(sys.stderr)
+        console_handler.setLevel(numeric_level)
+        console_handler.setFormatter(formatter)
+        root_logger.addHandler(console_handler)
+
+    # File handler (if specified)
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(logging.DEBUG)  # Always log everything to file
+        file_handler.setFormatter(formatter)
+        root_logger.addHandler(file_handler)
+
+    # Suppress noisy third-party loggers
+    logging.getLogger("boto3").setLevel(logging.CRITICAL)
+    logging.getLogger("botocore").setLevel(logging.CRITICAL)
+    logging.getLogger("urllib3").setLevel(logging.CRITICAL)
+    logging.getLogger("s3transfer").setLevel(logging.CRITICAL)
+
+    # Suppress internal module logs unless verbose
+    if not verbose:
+        logging.getLogger("src").setLevel(logging.CRITICAL)
+        logging.getLogger("src.snapshot").setLevel(logging.CRITICAL)
+        logging.getLogger("src.snapshot.resource_collectors").setLevel(logging.CRITICAL)
+        logging.getLogger("src.snapshot.capturer").setLevel(logging.CRITICAL)
+        logging.getLogger("src.snapshot.storage").setLevel(logging.CRITICAL)
+        logging.getLogger("src.aws").setLevel(logging.CRITICAL)
+        logging.getLogger("src.aws.credentials").setLevel(logging.CRITICAL)

src/utils/pagination.py

@@ -0,0 +1,41 @@
+"""
+Terminal pagination utilities for large resource lists.
+
+This module provides pagination functionality for displaying large datasets
+in the terminal with user-friendly navigation controls.
+"""
+
+from __future__ import annotations
+
+from typing import Generator, List, TypeVar
+
+T = TypeVar("T")
+
+
+def paginate_resources(items: List[T], page_size: int = 100) -> Generator[List[T], None, None]:
+    """
+    Paginate a list of items into pages of specified size.
+
+    This is a memory-efficient generator that yields pages of items
+    without loading everything into memory at once.
+
+    Args:
+        items: List of items to paginate
+        page_size: Number of items per page (default: 100)
+
+    Yields:
+        Lists of items, each containing up to page_size items
+
+    Example:
+        >>> resources = list(range(250))
+        >>> for page in paginate_resources(resources, page_size=100):
+        ...     print(f"Page has {len(page)} items")
+        Page has 100 items
+        Page has 100 items
+        Page has 50 items
+    """
+    if not items:
+        return
+
+    for i in range(0, len(items), page_size):
+        yield items[i : i + page_size]

src/utils/paths.py

@@ -0,0 +1,51 @@
+"""Path resolution utilities for snapshot storage."""
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+
+def get_snapshot_storage_path(custom_path: Optional[Union[str, Path]] = None) -> Path:
+    """Resolve snapshot storage path with precedence: parameter > env var > default.
+
+    Precedence order:
+    1. custom_path parameter (if provided)
+    2. AWS_INVENTORY_STORAGE_PATH environment variable (if set)
+    3. ~/.snapshots (default)
+
+    Args:
+        custom_path: Optional custom path override
+
+    Returns:
+        Resolved Path object for snapshot storage
+
+    Examples:
+        # Use default
+        >>> get_snapshot_storage_path()
+        Path.home() / '.snapshots'
+
+        # Use environment variable
+        >>> os.environ['AWS_INVENTORY_STORAGE_PATH'] = '/data/snapshots'
+        >>> get_snapshot_storage_path()
+        Path('/data/snapshots')
+
+        # Use parameter (highest priority)
+        >>> get_snapshot_storage_path('/custom/path')
+        Path('/custom/path')
+    """
+    # Priority 1: Custom path parameter (but not empty string)
+    if custom_path:
+        # Handle both str and Path types
+        if isinstance(custom_path, str):
+            if custom_path.strip():
+                return Path(custom_path).expanduser().resolve()
+        else:  # Path object
+            return custom_path.expanduser().resolve()
+
+    # Priority 2: Environment variable
+    env_path = os.getenv("AWS_INVENTORY_STORAGE_PATH")
+    if env_path:
+        return Path(env_path).expanduser().resolve()
+
+    # Priority 3: Default to ~/.snapshots
+    return Path.home() / ".snapshots"

src/utils/progress.py

@@ -0,0 +1,41 @@
+"""Progress indicator utilities using Rich library."""
+
+from contextlib import contextmanager
+
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeRemainingColumn,
+)
+
+
+@contextmanager
+def create_progress():
+    """Create a Rich progress context for tracking operations.
+
+    Yields:
+        Progress instance configured for multi-task tracking
+    """
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TimeRemainingColumn(),
+    ) as progress:
+        yield progress
+
+
+def create_spinner_progress():
+    """Create a simple spinner progress for indeterminate operations.
+
+    Returns:
+        Progress instance with spinner
+    """
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+    )