max-cli 0.2.0__py3-none-any.whl

max_cli/common/cache.py

@@ -0,0 +1,145 @@
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+
+class Cache:
+    """Simple file-based cache with TTL support."""
+
+    def __init__(self, cache_dir: Optional[Path] = None, ttl: int = 3600):
+        """Initialize cache.
+
+        Args:
+            cache_dir: Directory for cache files. Defaults to ~/.max_cli/cache
+            ttl: Time-to-live in seconds for cached items. Default 1 hour.
+        """
+        self.cache_dir = cache_dir or Path.home() / ".max_cli" / "cache"
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.ttl = ttl
+
+    def get(self, key: str) -> Optional[Any]:
+        """Retrieve value from cache if not expired.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        cache_file = self.cache_dir / f"{self._hash(key)}.json"
+        if not cache_file.exists():
+            return None
+
+        try:
+            data = json.loads(cache_file.read_text())
+            if data.get("expires", 0) < time.time():
+                cache_file.unlink()
+                return None
+            return data.get("value")
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Store value in cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Optional TTL override in seconds
+        """
+        cache_file = self.cache_dir / f"{self._hash(key)}.json"
+        expires = time.time() + (ttl if ttl is not None else self.ttl)
+        data = {"value": value, "expires": expires}
+        cache_file.write_text(json.dumps(data))
+
+    def delete(self, key: str) -> bool:
+        """Delete a cached item.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if deleted, False if not found
+        """
+        cache_file = self.cache_dir / f"{self._hash(key)}.json"
+        if cache_file.exists():
+            cache_file.unlink()
+            return True
+        return False
+
+    def clear(self) -> int:
+        """Clear all cache entries.
+
+        Returns:
+            Number of entries cleared
+        """
+        count = 0
+        for f in self.cache_dir.glob("*.json"):
+            f.unlink()
+            count += 1
+        return count
+
+    def clear_expired(self) -> int:
+        """Clear only expired cache entries.
+
+        Returns:
+            Number of expired entries cleared
+        """
+        count = 0
+        now = time.time()
+        for f in self.cache_dir.glob("*.json"):
+            try:
+                data = json.loads(f.read_text())
+                if data.get("expires", 0) < now:
+                    f.unlink()
+                    count += 1
+            except (json.JSONDecodeError, OSError):
+                f.unlink()
+                count += 1
+        return count
+
+    def _hash(self, key: str) -> str:
+        """Generate hash for cache key."""
+        return hashlib.md5(key.encode()).hexdigest()
+
+
+_default_cache: Optional[Cache] = None
+
+
+def get_default_cache() -> Cache:
+    """Get the default cache instance."""
+    global _default_cache
+    if _default_cache is None:
+        _default_cache = Cache()
+    return _default_cache
+
+
+def cached(key_prefix: str, ttl: Optional[int] = None):
+    """Decorator for caching function results.
+
+    Args:
+        key_prefix: Prefix for cache key
+        ttl: Optional TTL override in seconds
+    """
+
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            cache = get_default_cache()
+            key_parts = [key_prefix]
+            key_parts.extend(str(arg) for arg in args if not isinstance(arg, Path))
+            key_parts.extend(f"{k}={v}" for k, v in sorted(kwargs.items()))
+            cache_key = ":".join(key_parts)
+
+            result = cache.get(cache_key)
+            if result is not None:
+                return result
+
+            result = func(*args, **kwargs)
+            cache.set(cache_key, result, ttl)
+            return result
+
+        return wrapper
+
+    return decorator

max_cli/common/concurrent.py

@@ -0,0 +1,83 @@
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+from rich.progress import Progress, TaskID
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+def process_batch_parallel(
+    items: List[T],
+    processor: Callable[[T], R],
+    max_workers: int = 4,
+    progress: Optional[Progress] = None,
+    task_id: Optional[TaskID] = None,
+) -> List[Dict[str, Any]]:
+    """Process items in parallel with optional progress tracking.
+
+    Args:
+        items: List of items to process
+        processor: Function to apply to each item
+        max_workers: Maximum number of parallel workers
+        progress: Optional Rich Progress instance
+        task_id: Optional Rich TaskID for progress tracking
+
+    Returns:
+        List of results, including errors for failed items
+    """
+    results: List[Dict[str, Any]] = []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {executor.submit(processor, item): item for item in items}
+
+        for future in as_completed(futures):
+            item = futures[future]
+            try:
+                result = future.result()
+                if isinstance(result, dict):
+                    results.append(result)
+                else:
+                    results.append({"result": result, "item": item})
+            except Exception as e:
+                results.append({"error": str(e), "item": item, "success": False})
+
+            if progress is not None and task_id is not None:
+                progress.advance(task_id)
+
+    return results
+
+
+def process_batch_sequential(
+    items: List[T],
+    processor: Callable[[T], R],
+    progress: Optional[Progress] = None,
+    task_id: Optional[TaskID] = None,
+) -> List[Dict[str, Any]]:
+    """Process items sequentially with optional progress tracking.
+
+    Args:
+        items: List of items to process
+        processor: Function to apply to each item
+        progress: Optional Rich Progress instance
+        task_id: Optional Rich TaskID for progress tracking
+
+    Returns:
+        List of results, including errors for failed items
+    """
+    results: List[Dict[str, Any]] = []
+
+    for item in items:
+        try:
+            result = processor(item)
+            if isinstance(result, dict):
+                results.append(result)
+            else:
+                results.append({"result": result, "item": item})
+        except Exception as e:
+            results.append({"error": str(e), "item": item, "success": False})
+
+        if progress is not None and task_id is not None:
+            progress.advance(task_id)
+
+    return results

max_cli/common/exceptions.py

@@ -0,0 +1,40 @@
+class MaxError(Exception):
+    """Base class for expected errors in the CLI."""
+
+    pass
+
+
+class ResourceNotFoundError(MaxError):
+    """Raised when a file or folder is missing."""
+
+    pass
+
+
+class ValidationError(MaxError):
+    """Raised when input arguments are invalid."""
+
+    pass
+
+
+class ConfigurationError(MaxError):
+    """Raised when configuration is invalid or missing."""
+
+    pass
+
+
+class ProcessingError(MaxError):
+    """Raised when file processing fails."""
+
+    pass
+
+
+class NetworkError(MaxError):
+    """Raised when network operations fail."""
+
+    pass
+
+
+class AIError(MaxError):
+    """Raised when AI operations fail."""
+
+    pass

max_cli/common/logger.py

@@ -0,0 +1,22 @@
+from rich.console import Console
+from rich.theme import Theme
+
+# Define a custom theme for consistent coloring
+custom_theme = Theme(
+    {
+        "info": "cyan",
+        "warning": "yellow",
+        "error": "bold red",
+        "success": "bold green",
+    }
+)
+
+console = Console(theme=custom_theme)
+
+
+def log_error(message: str):
+    console.print(f"[error]✖ Error:[/error] {message}")
+
+
+def log_success(message: str):
+    console.print(f"[success]✔ Success:[/success] {message}")

max_cli/common/logging.py

@@ -0,0 +1,24 @@
+import logging
+from pathlib import Path
+from typing import Optional
+
+
+def setup_logging(log_level: str = "INFO", log_file: Optional[Path] = None) -> None:
+    """Configure logging for the application."""
+    format_str = "%(asctime)s | %(name)-20s | %(levelname)-8s | %(message)s"
+
+    handlers = [logging.StreamHandler()]
+
+    if log_file:
+        handlers.append(logging.FileHandler(log_file))
+
+    logging.basicConfig(
+        level=getattr(logging, log_level.upper()),
+        format=format_str,
+        handlers=handlers,
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance with the given name."""
+    return logging.getLogger(name)

max_cli/common/retry.py

@@ -0,0 +1,51 @@
+import logging
+import time
+from functools import wraps
+from typing import Any, Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    exceptions: tuple = (Exception,),
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator for retrying failed operations with exponential backoff.
+
+    Args:
+        max_attempts: Maximum number of retry attempts
+        delay: Initial delay between retries in seconds
+        backoff: Multiplier for delay after each retry
+        exceptions: Tuple of exceptions to catch and retry
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            current_delay = delay
+            last_exception = None
+
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt == max_attempts:
+                        logger.error(f"Failed after {max_attempts} attempts: {e}")
+                        raise
+                    logger.warning(
+                        f"Attempt {attempt}/{max_attempts} failed: {e}. "
+                        f"Retrying in {current_delay:.1f}s..."
+                    )
+                    time.sleep(current_delay)
+                    current_delay *= backoff
+
+            raise last_exception  # type: ignore[arg-type]
+
+        return wrapper
+
+    return decorator

max_cli/common/utils.py

@@ -0,0 +1,40 @@
+import re
+import base64
+from pathlib import Path
+
+
+def natural_sort_key(s: str) -> list:
+    """
+    Splits a string into a list of integers and text chunks.
+    Used for sorting ["1_doc", "10_doc", "2_doc"] -> ["1_doc", "2_doc", "10_doc"]
+    """
+    return [
+        int(text) if text.isdigit() else text.lower() for text in re.split(r"(\d+)", s)
+    ]
+
+
+def format_size(size_in_bytes: float) -> str:
+    """Returns a human-readable file size string, handling negative values (growth)."""
+    is_negative = size_in_bytes < 0
+    size = abs(size_in_bytes)
+
+    final_unit = "B"
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        final_unit = unit
+        if size < 1024.0:
+            break
+        size /= 1024.0
+
+    prefix = "-" if is_negative else ""
+    return f"{prefix}{size:.2f} {final_unit}"
+
+
+def encode_image_to_base64(image_path: Path) -> str:
+    """
+    Reads a file and returns a base64 string for AI consumption.
+    """
+    if not image_path.exists():
+        raise FileNotFoundError(f"Image not found: {image_path}")
+
+    with open(image_path, "rb") as image_file:
+        return base64.b64encode(image_file.read()).decode("utf-8")

max_cli/config.py

@@ -0,0 +1,43 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings
+from typing import Optional
+from pathlib import Path
+
+
+class Settings(BaseSettings):
+    APP_NAME: str = "Max CLI"
+    DEFAULT_QUALITY: int = 85
+
+    MAX_WORKERS: int = Field(default=4, ge=1, le=16)
+    BATCH_SIZE: int = Field(default=10, ge=1)
+
+    DOWNLOAD_TIMEOUT: int = Field(default=300, ge=30)
+    MAX_RETRIES: int = Field(default=3, ge=0)
+
+    PROGRESS_BAR: bool = True
+    VERBOSE: bool = False
+    CONFIRM_DESTRUCTIVE: bool = True
+
+    # AI Configuration
+    # If using OpenAI, leave BASE_URL as None.
+    # If using Gemini, set to: https://generativelanguage.googleapis.com/v1beta/openai/
+    OPENAI_API_KEY: Optional[str] = None
+    OPENAI_BASE_URL: Optional[str] = None
+    # Models
+    AI_MODEL: str = "gpt-5-nano"  # For 'ask', 'chat', 'analyze'
+    AI_IMAGE_MODEL: str = "gemini-2.5-flash-image"  # For 'create', 'edit'
+
+    # --- GRAB (DOWNLOADER) DEFAULTS ---
+    # These save your preferences
+    GRAB_QUALITY: str = "h"  # s, m, h, x
+    GRAB_AUDIO_FORMAT: str = "mp3"  # mp3, m4a, wav
+    GRAB_STRIP_PLAYLIST: bool = True  # If True, removes '&list=...' from video URLs
+    GRAB_INCLUDE_METADATA: bool = True  # If True, embeds tags/thumbnails
+
+    class Config:
+        env_file = [str(Path.home() / ".max_config.env"), ".env"]
+        env_file_encoding = "utf-8"
+        extra = "ignore"
+
+
+settings = Settings()