claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/utils/imports.py

@@ -0,0 +1,182 @@
+"""Import utilities for handling relative and absolute imports.
+
+This module provides utilities to handle the common pattern of trying
+relative imports first and falling back to absolute imports, which is
+used throughout the claude_mpm codebase.
+"""
+
+import importlib
+import logging
+from typing import Optional, Any, List, Union
+
+
+def safe_import(
+    module_name: str,
+    fallback_name: Optional[str] = None,
+    from_list: Optional[List[str]] = None,
+    logger: Optional[logging.Logger] = None
+) -> Optional[Any]:
+    """
+    Safely import a module with fallback support.
+    
+    Attempts to import a module using the primary module name first,
+    then falls back to the fallback name if provided. This is useful
+    for handling both relative and absolute imports.
+    
+    Args:
+        module_name: Primary module name to import (e.g., '..utils.logger')
+        fallback_name: Fallback module name if primary fails (e.g., 'utils.logger')
+        from_list: List of names to import from the module (for 'from X import Y' style)
+        logger: Optional logger for debugging import attempts
+        
+    Returns:
+        The imported module or specific attribute(s) if from_list is provided.
+        Returns None if all import attempts fail.
+        
+    Examples:
+        # Import entire module
+        logger_module = safe_import('..utils.logger', 'utils.logger')
+        
+        # Import specific function (returns the function directly)
+        get_logger = safe_import('..utils.logger', 'utils.logger', ['get_logger'])
+        
+        # Import multiple items (returns tuple)
+        logger, setup = safe_import('..utils.logger', 'utils.logger', 
+                                   ['get_logger', 'setup_logging'])
+    """
+    # Try primary import
+    try:
+        if logger:
+            logger.debug(f"Attempting import: {module_name}")
+        
+        module = importlib.import_module(module_name)
+        
+        if from_list:
+            # Handle 'from X import Y' style imports
+            results = []
+            for name in from_list:
+                if hasattr(module, name):
+                    results.append(getattr(module, name))
+                else:
+                    if logger:
+                        logger.warning(f"Module {module_name} has no attribute {name}")
+                    results.append(None)
+            
+            # Return single item if only one requested, otherwise tuple
+            if len(results) == 1:
+                return results[0]
+            return tuple(results)
+        
+        return module
+        
+    except ImportError as e:
+        if logger:
+            logger.debug(f"Primary import failed: {e}")
+        
+        # Try fallback if provided
+        if fallback_name:
+            try:
+                if logger:
+                    logger.debug(f"Attempting fallback import: {fallback_name}")
+                
+                module = importlib.import_module(fallback_name)
+                
+                if from_list:
+                    # Handle 'from X import Y' style imports
+                    results = []
+                    for name in from_list:
+                        if hasattr(module, name):
+                            results.append(getattr(module, name))
+                        else:
+                            if logger:
+                                logger.warning(f"Module {fallback_name} has no attribute {name}")
+                            results.append(None)
+                    
+                    # Return single item if only one requested, otherwise tuple
+                    if len(results) == 1:
+                        return results[0]
+                    return tuple(results)
+                
+                return module
+                
+            except ImportError as e2:
+                if logger:
+                    logger.debug(f"Fallback import also failed: {e2}")
+    
+    # All imports failed
+    if logger:
+        logger.error(f"Failed to import {module_name}" + 
+                    (f" or {fallback_name}" if fallback_name else ""))
+    
+    return None
+
+
+def safe_import_multiple(
+    imports: List[Union[tuple, dict]],
+    logger: Optional[logging.Logger] = None
+) -> dict:
+    """
+    Import multiple modules with fallback support.
+    
+    Args:
+        imports: List of import specifications. Each can be:
+            - tuple: (primary_name, fallback_name, from_list)
+            - dict: {'primary': '...', 'fallback': '...', 'from_list': [...], 'as': 'alias'}
+        logger: Optional logger for debugging
+        
+    Returns:
+        Dictionary mapping module/attribute names to imported objects
+        
+    Example:
+        imports = [
+            ('..utils.logger', 'utils.logger', ['get_logger']),
+            {'primary': '..core.agent_registry', 'fallback': 'core.agent_registry', 
+             'from_list': ['AgentRegistry'], 'as': 'registry'}
+        ]
+        
+        imported = safe_import_multiple(imports)
+        # Result: {'get_logger': <function>, 'registry': <class>}
+    """
+    results = {}
+    
+    for spec in imports:
+        if isinstance(spec, tuple):
+            primary, fallback, from_list = spec
+            imported = safe_import(primary, fallback, from_list, logger)
+            
+            if imported is not None:
+                if from_list and len(from_list) == 1:
+                    # Single import gets stored by its name
+                    results[from_list[0]] = imported
+                elif from_list and len(from_list) > 1:
+                    # Multiple imports get unpacked
+                    for i, name in enumerate(from_list):
+                        if imported[i] is not None:
+                            results[name] = imported[i]
+                else:
+                    # Module import gets stored by last part of module name
+                    module_alias = primary.split('.')[-1]
+                    results[module_alias] = imported
+                    
+        elif isinstance(spec, dict):
+            primary = spec.get('primary')
+            fallback = spec.get('fallback')
+            from_list = spec.get('from_list')
+            alias = spec.get('as')
+            
+            imported = safe_import(primary, fallback, from_list, logger)
+            
+            if imported is not None:
+                if alias:
+                    results[alias] = imported
+                elif from_list and len(from_list) == 1:
+                    results[from_list[0]] = imported
+                elif from_list and len(from_list) > 1:
+                    for i, name in enumerate(from_list):
+                        if imported[i] is not None:
+                            results[name] = imported[i]
+                else:
+                    module_alias = primary.split('.')[-1]
+                    results[module_alias] = imported
+    
+    return results

claude_mpm/utils/path_operations.py

@@ -0,0 +1,357 @@
+"""Path operations and validation utilities.
+
+This module provides a centralized PathOperations class for common path validation
+and file operations, reducing code duplication across the codebase.
+"""
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional, List, Union, Callable
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class PathOperations:
+    """Utility class for path validation and safe file operations."""
+    
+    def __init__(self, default_encoding: str = 'utf-8'):
+        """Initialize PathOperations with default encoding.
+        
+        Args:
+            default_encoding: Default encoding for file operations
+        """
+        self.default_encoding = default_encoding
+    
+    # Path Validation Methods
+    
+    def validate_exists(self, path: Union[str, Path]) -> bool:
+        """Check if path exists.
+        
+        Args:
+            path: Path to validate
+            
+        Returns:
+            True if path exists, False otherwise
+        """
+        try:
+            return Path(path).exists()
+        except Exception as e:
+            logger.error(f"Error checking path existence: {e}")
+            return False
+    
+    def validate_is_file(self, path: Union[str, Path]) -> bool:
+        """Check if path is a file.
+        
+        Args:
+            path: Path to validate
+            
+        Returns:
+            True if path is a file, False otherwise
+        """
+        try:
+            return Path(path).is_file()
+        except Exception as e:
+            logger.error(f"Error checking if path is file: {e}")
+            return False
+    
+    def validate_is_dir(self, path: Union[str, Path]) -> bool:
+        """Check if path is a directory.
+        
+        Args:
+            path: Path to validate
+            
+        Returns:
+            True if path is a directory, False otherwise
+        """
+        try:
+            return Path(path).is_dir()
+        except Exception as e:
+            logger.error(f"Error checking if path is directory: {e}")
+            return False
+    
+    def validate_readable(self, path: Union[str, Path]) -> bool:
+        """Check if path has read permissions.
+        
+        Args:
+            path: Path to validate
+            
+        Returns:
+            True if path is readable, False otherwise
+        """
+        try:
+            path_obj = Path(path)
+            if not path_obj.exists():
+                return False
+            return os.access(str(path_obj), os.R_OK)
+        except Exception as e:
+            logger.error(f"Error checking read permissions: {e}")
+            return False
+    
+    def validate_writable(self, path: Union[str, Path]) -> bool:
+        """Check if path has write permissions.
+        
+        Args:
+            path: Path to validate
+            
+        Returns:
+            True if path is writable, False otherwise
+        """
+        try:
+            path_obj = Path(path)
+            if path_obj.exists():
+                return os.access(str(path_obj), os.W_OK)
+            # Check parent directory for new files
+            parent = path_obj.parent
+            return parent.exists() and os.access(str(parent), os.W_OK)
+        except Exception as e:
+            logger.error(f"Error checking write permissions: {e}")
+            return False
+    
+    # Safe File Operations
+    
+    def safe_read(self, path: Union[str, Path], 
+                  encoding: Optional[str] = None,
+                  default: Optional[str] = None) -> Optional[str]:
+        """Read file with error handling.
+        
+        Args:
+            path: Path to read
+            encoding: File encoding (uses default if None)
+            default: Default value if read fails
+            
+        Returns:
+            File contents or default value
+        """
+        encoding = encoding or self.default_encoding
+        try:
+            path_obj = Path(path)
+            if not self.validate_readable(path_obj):
+                logger.warning(f"File not readable: {path}")
+                return default
+            
+            with open(path_obj, 'r', encoding=encoding) as f:
+                return f.read()
+        except Exception as e:
+            logger.error(f"Error reading file {path}: {e}")
+            return default
+    
+    def safe_write(self, path: Union[str, Path], 
+                   content: str,
+                   encoding: Optional[str] = None,
+                   backup: bool = False,
+                   atomic: bool = False) -> bool:
+        """Write file with error handling and optional backup.
+        
+        Args:
+            path: Path to write
+            content: Content to write
+            encoding: File encoding (uses default if None)
+            backup: Create backup before writing
+            atomic: Use atomic write (write to temp file and move)
+            
+        Returns:
+            True if write successful, False otherwise
+        """
+        encoding = encoding or self.default_encoding
+        path_obj = Path(path)
+        
+        try:
+            # Create backup if requested
+            if backup and path_obj.exists():
+                backup_path = path_obj.with_suffix(path_obj.suffix + '.bak')
+                shutil.copy2(str(path_obj), str(backup_path))
+                logger.info(f"Created backup: {backup_path}")
+            
+            # Ensure parent directory exists
+            path_obj.parent.mkdir(parents=True, exist_ok=True)
+            
+            if atomic:
+                # Atomic write: write to temp file then move
+                with tempfile.NamedTemporaryFile(
+                    mode='w',
+                    encoding=encoding,
+                    dir=path_obj.parent,
+                    delete=False
+                ) as tmp_file:
+                    tmp_file.write(content)
+                    tmp_path = tmp_file.name
+                
+                # Move temp file to target
+                shutil.move(tmp_path, str(path_obj))
+            else:
+                # Direct write
+                with open(path_obj, 'w', encoding=encoding) as f:
+                    f.write(content)
+            
+            logger.info(f"Successfully wrote to {path}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error writing file {path}: {e}")
+            return False
+    
+    def safe_delete(self, path: Union[str, Path], 
+                    confirm: Optional[Callable[[], bool]] = None) -> bool:
+        """Delete file/directory with optional confirmation.
+        
+        Args:
+            path: Path to delete
+            confirm: Optional confirmation callback
+            
+        Returns:
+            True if delete successful, False otherwise
+        """
+        try:
+            path_obj = Path(path)
+            if not path_obj.exists():
+                logger.warning(f"Path does not exist: {path}")
+                return True
+            
+            # Confirm if callback provided
+            if confirm and not confirm():
+                logger.info(f"Delete cancelled by user: {path}")
+                return False
+            
+            if path_obj.is_file():
+                path_obj.unlink()
+            else:
+                shutil.rmtree(str(path_obj))
+            
+            logger.info(f"Successfully deleted: {path}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error deleting {path}: {e}")
+            return False
+    
+    def safe_copy(self, src: Union[str, Path], 
+                  dst: Union[str, Path],
+                  overwrite: bool = False) -> bool:
+        """Copy file/directory with overwrite protection.
+        
+        Args:
+            src: Source path
+            dst: Destination path
+            overwrite: Allow overwriting existing files
+            
+        Returns:
+            True if copy successful, False otherwise
+        """
+        try:
+            src_path = Path(src)
+            dst_path = Path(dst)
+            
+            if not src_path.exists():
+                logger.error(f"Source does not exist: {src}")
+                return False
+            
+            if dst_path.exists() and not overwrite:
+                logger.error(f"Destination exists and overwrite=False: {dst}")
+                return False
+            
+            # Ensure parent directory exists
+            dst_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            if src_path.is_file():
+                shutil.copy2(str(src_path), str(dst_path))
+            else:
+                if dst_path.exists():
+                    shutil.rmtree(str(dst_path))
+                shutil.copytree(str(src_path), str(dst_path))
+            
+            logger.info(f"Successfully copied {src} to {dst}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error copying {src} to {dst}: {e}")
+            return False
+    
+    # Common Patterns
+    
+    def ensure_dir(self, path: Union[str, Path]) -> bool:
+        """Create directory if it doesn't exist.
+        
+        Args:
+            path: Directory path to ensure
+            
+        Returns:
+            True if directory exists or was created, False otherwise
+        """
+        try:
+            Path(path).mkdir(parents=True, exist_ok=True)
+            return True
+        except Exception as e:
+            logger.error(f"Error creating directory {path}: {e}")
+            return False
+    
+    def get_size(self, path: Union[str, Path]) -> int:
+        """Get size of file or directory in bytes.
+        
+        Args:
+            path: Path to measure
+            
+        Returns:
+            Size in bytes, or -1 on error
+        """
+        try:
+            path_obj = Path(path)
+            if not path_obj.exists():
+                return -1
+            
+            if path_obj.is_file():
+                return path_obj.stat().st_size
+            else:
+                # Calculate total size for directory
+                total = 0
+                for item in path_obj.rglob('*'):
+                    if item.is_file():
+                        total += item.stat().st_size
+                return total
+                
+        except Exception as e:
+            logger.error(f"Error getting size of {path}: {e}")
+            return -1
+    
+    def list_files(self, path: Union[str, Path],
+                   pattern: str = '*',
+                   recursive: bool = False,
+                   include_dirs: bool = False) -> List[Path]:
+        """List files in directory with filtering.
+        
+        Args:
+            path: Directory path
+            pattern: Glob pattern for filtering
+            recursive: Search recursively
+            include_dirs: Include directories in results
+            
+        Returns:
+            List of matching paths
+        """
+        try:
+            path_obj = Path(path)
+            if not path_obj.is_dir():
+                logger.error(f"Not a directory: {path}")
+                return []
+            
+            if recursive:
+                items = path_obj.rglob(pattern)
+            else:
+                items = path_obj.glob(pattern)
+            
+            results = []
+            for item in items:
+                if item.is_file() or (include_dirs and item.is_dir()):
+                    results.append(item)
+            
+            return sorted(results)
+            
+        except Exception as e:
+            logger.error(f"Error listing files in {path}: {e}")
+            return []
+
+
+# Convenience instance for direct imports
+path_ops = PathOperations()