hatch-xclam 0.7.0__py3-none-any.whl

hatch/installers/hatch_installer.py

@@ -0,0 +1,198 @@
+"""Installer for Hatch package dependencies.
+
+Implements installation logic for Hatch packages using the HatchPackageLoader and
+integrates pre-install validation using HatchPackageValidator and PackageService.
+"""
+
+import logging
+import shutil
+from pathlib import Path
+from typing import Dict, Any, Optional, Callable, List
+
+from hatch.installers.installer_base import DependencyInstaller, InstallationContext, InstallationResult, InstallationError
+from hatch.installers.installation_context import InstallationStatus
+from hatch.package_loader import HatchPackageLoader, PackageLoaderError
+from hatch_validator.package_validator import HatchPackageValidator
+
+class HatchInstaller(DependencyInstaller):
+    """Installer for Hatch package dependencies.
+
+    Handles installation, validation, and uninstallation of Hatch packages using
+    the HatchPackageLoader and validator APIs.
+    """
+
+    def __init__(self, registry_data: Optional[Dict[str, Any]] = None):
+        """Initialize the HatchInstaller.
+
+        Args:
+            registry_data (Dict[str, Any], optional): Registry data for validation. Defaults to None.
+        """
+        self.logger = logging.getLogger("hatch.installers.hatch_installer")
+        self.package_loader = HatchPackageLoader()
+        self.validator = HatchPackageValidator(registry_data=registry_data)
+
+    @property
+    def installer_type(self) -> str:
+        """Get the type identifier for this installer.
+
+        Returns:
+            str: Unique identifier for the installer type ("hatch").
+        """
+        return "hatch"
+
+    @property
+    def supported_schemes(self) -> List[str]:
+        """Get the URI schemes this installer can handle.
+
+        Returns:
+            List[str]: List of URI schemes (e.g., ["file", "http", "https"]).
+        """
+        return ["file", "http", "https"]
+
+    def can_install(self, dependency: Dict[str, Any]) -> bool:
+        """Check if this installer can handle the given dependency.
+
+        Args:
+            dependency (Dict[str, Any]): Dependency object.
+
+        Returns:
+            bool: True if this installer can handle the dependency, False otherwise.
+        """
+        return dependency.get("type") == self.installer_type
+
+    def validate_dependency(self, dependency: Dict[str, Any]) -> bool:
+        """Validate that a dependency object has required fields and is a valid Hatch package.
+
+        Args:
+            dependency (Dict[str, Any]): Dependency object to validate.
+
+        Returns:
+            bool: True if dependency is valid, False otherwise.
+        """
+        required_fields = ["name", "version_constraint", "resolved_version", "uri"]
+        if not all(field in dependency for field in required_fields):
+            return False
+        # Optionally, perform further validation using the validator if a path is provided
+        return True
+
+    def install(self, dependency: Dict[str, Any], context: InstallationContext,
+                progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult:
+        """Install a Hatch package dependency.
+
+        Args:
+            dependency (Dict[str, Any]): Dependency object containing name, version, uri, etc.
+            context (InstallationContext): Installation context with environment info.
+            progress_callback (Callable[[str, float, str], None], optional): Progress reporting callback.
+
+        Returns:
+            InstallationResult: Result of the installation operation.
+
+        Raises:
+            InstallationError: If installation fails for any reason.
+        """
+
+        self.logger.debug(f"Installing Hatch dependency: {dependency}")
+        if not self.validate_dependency(dependency):
+            self.logger.error(f"Invalid dependency format: {dependency}")
+            raise InstallationError("Invalid dependency object",
+                                    dependency_name=dependency.get("name"),
+                                    error_code="INVALID_HATCH_DEPENDENCY_FORMAT",
+                                    )
+
+        name = dependency["name"]
+        version = dependency["resolved_version"]
+        uri = dependency["uri"]
+        target_dir = Path(context.environment_path)
+        try:
+            if progress_callback:
+                progress_callback("install", 0.0, f"Installing {name}-{version} from {uri}")
+            # Download/install the package
+            if uri and uri.startswith("file://"):
+                pkg_path = Path(uri[7:])
+                result_path = self.package_loader.install_local_package(pkg_path, target_dir, name)
+            elif uri:
+                result_path = self.package_loader.install_remote_package(uri, name, version, target_dir)
+            else:
+                raise InstallationError(f"No URI provided for dependency {name}", dependency_name=name)
+            
+            if progress_callback:
+                progress_callback("install", 1.0, f"Installed {name} to {result_path}")
+            
+            return InstallationResult(
+                dependency_name=name,
+                status=InstallationStatus.COMPLETED,
+                installed_path=result_path,
+                installed_version=version,
+                error_message=None,
+                artifacts=result_path,
+                metadata={"name": name, "version": version}
+            )
+            
+        except (PackageLoaderError, Exception) as e:
+            self.logger.error(f"Failed to install {name}: {e}")
+            raise InstallationError(f"Failed to install {name}: {e}", dependency_name=name, cause=e)
+
+    def uninstall(self, dependency: Dict[str, Any], context: InstallationContext,
+                  progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult:
+        """Uninstall a Hatch package dependency.
+
+        Args:
+            dependency (Dict[str, Any]): Dependency object to uninstall.
+            context (InstallationContext): Installation context with environment info.
+            progress_callback (Callable[[str, float, str], None], optional): Progress reporting callback.
+
+        Returns:
+            InstallationResult: Result of the uninstall operation.
+
+        Raises:
+            InstallationError: If uninstall fails for any reason.
+        """
+        if not self.validate_dependency(dependency):
+            raise InstallationError("Invalid dependency object",
+                                    dependency_name=dependency.get("name"),
+                                    error_code="INVALID_HATCH_DEPENDENCY_FORMAT",
+                                    )
+
+        name = dependency["name"]
+        target_dir = Path(context.environment_path) / name
+        try:
+            if target_dir.exists():
+                shutil.rmtree(target_dir)
+            if progress_callback:
+                progress_callback("uninstall", 1.0, f"Uninstalled {name}")
+            return InstallationResult(
+                dependency_name=name,
+                status=InstallationStatus.COMPLETED,
+                installed_path=target_dir,
+                installed_version=dependency.get("resolved_version"),
+                error_message=None,
+                artifacts=None,
+                metadata={"name": name}
+            )
+        except Exception as e:
+            self.logger.error(f"Failed to uninstall {name}: {e}")
+            raise InstallationError(f"Failed to uninstall {name}: {e}", dependency_name=name, cause=e)
+
+    def cleanup_failed_installation(self, dependency: Dict[str, Any], context: InstallationContext,
+                                   artifacts: Optional[List[Path]] = None) -> None:
+        """Clean up artifacts from a failed installation.
+
+        Args:
+            dependency (Dict[str, Any]): Dependency that failed to install.
+            context (InstallationContext): Installation context.
+            artifacts (List[Path], optional): List of files/directories to clean up.
+        """
+        if artifacts:
+            for artifact in artifacts:
+                try:
+                    if artifact.exists():
+                        if artifact.is_file():
+                            artifact.unlink()
+                        elif artifact.is_dir():
+                            shutil.rmtree(artifact)
+                except Exception:
+                    pass
+
+# Register this installer with the global registry
+from .registry import installer_registry
+installer_registry.register_installer("hatch", HatchInstaller)

hatch/installers/installation_context.py

@@ -0,0 +1,109 @@
+"""
+Defines context, status, and result data structures for dependency installation.
+
+This module provides the InstallationContext dataclass for encapsulating
+environment and configuration information required during dependency installation,
+as well as InstallationStatus and InstallationResult for representing the
+outcome and details of installation operations.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass
+from enum import Enum
+
+@dataclass
+class InstallationContext:
+    """Context information for dependency installation.
+    
+    This class encapsulates all the environment and configuration information
+    needed for installing dependencies, making the installer interface cleaner
+    and more extensible.
+    """
+    
+    environment_path: Path
+    """Path to the target environment where dependencies will be installed."""
+    
+    environment_name: str
+    """Name of the target environment."""
+    
+    temp_dir: Optional[Path] = None
+    """Temporary directory for download/build operations."""
+    
+    cache_dir: Optional[Path] = None
+    """Cache directory for reusable artifacts."""
+    
+    parallel_enabled: bool = True
+    """Whether parallel installation is enabled."""
+    
+    force_reinstall: bool = False
+    """Whether to force reinstallation of existing packages."""
+    
+    simulation_mode: bool = False
+    """Whether to run in simulation mode (no actual installation)."""
+    
+    extra_config: Optional[Dict[str, Any]] = None
+    """Additional installer-specific configuration."""
+    
+    def get_config(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value from extra_config.
+        
+        Args:
+            key (str): Configuration key to retrieve.
+            default (Any, optional): Default value if key not found.
+            
+        Returns:
+            Any: Configuration value or default.
+        """
+        if self.extra_config is None:
+            return default
+        return self.extra_config.get(key, default)
+    
+    def set_config(self, key: str, value: Any) -> None:
+        """Set a configuration value in extra_config.
+        
+        Args:
+            key (str): Configuration key to set.
+            value (Any): Value to set for the key.
+        """
+        if self.extra_config is None:
+            self.extra_config = {}
+        self.extra_config[key] = value
+
+
+class InstallationStatus(Enum):
+    """Status of an installation operation."""
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    ROLLED_BACK = "rolled_back"
+
+@dataclass
+class InstallationResult:
+    """Result of an installation operation.
+    
+    Provides detailed information about the installation outcome,
+    including status, paths, and any error information.
+    """
+    
+    dependency_name: str
+    """Name of the dependency that was installed."""
+    
+    status: InstallationStatus
+    """Final status of the installation."""
+    
+    installed_path: Optional[Path] = None
+    """Path where the dependency was installed."""
+    
+    installed_version: Optional[str] = None
+    """Actual version that was installed."""
+    
+    error_message: Optional[str] = None
+    """Error message if installation failed."""
+    
+    artifacts: Optional[List[Path]] = None
+    """List of files/directories created during installation."""
+    
+    metadata: Optional[Dict[str, Any]] = None
+    """Additional installer-specific metadata."""

hatch/installers/installer_base.py

@@ -0,0 +1,195 @@
+"""Abstract base class for dependency installers.
+
+This module defines the core installer interface that all concrete installers
+must implement, ensuring consistent behavior across different dependency types.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Dict, Any, Optional, Callable, List
+
+from .installation_context import InstallationContext, InstallationResult
+
+
+class InstallationError(Exception):
+    """Exception raised for installation-related errors.
+    
+    This exception provides structured error information that can be used
+    for error reporting and recovery strategies.
+    """
+    
+    def __init__(self, message: str, dependency_name: Optional[str] = None, 
+                 error_code: Optional[str] = None, cause: Optional[Exception] = None):
+        """Initialize the installation error.
+        
+        Args:
+            message (str): Human-readable error message.
+            dependency_name (str, optional): Name of the dependency that failed.
+            error_code (str, optional): Machine-readable error code.
+            cause (Exception, optional): Underlying exception that caused this error.
+        """
+        self.message = message
+        self.dependency_name = dependency_name
+        self.error_code = error_code
+        self.cause = cause
+
+
+class DependencyInstaller(ABC):
+    """Abstract base class for dependency installers.
+    
+    This class defines the core interface that all concrete installers must implement.
+    It provides a consistent API for installing and managing dependencies across
+    different types (Hatch packages, Python packages, system packages, Docker containers).
+    
+    The installer design follows these principles:
+    - Single responsibility: Each installer handles one dependency type
+    - Extensibility: New dependency types can be added by implementing this interface
+    - Observability: Progress reporting through callbacks
+    - Error handling: Structured exceptions and rollback support
+    - Testability: Clear interface for mocking and testing
+    """
+    
+    @property
+    @abstractmethod
+    def installer_type(self) -> str:
+        """Get the type identifier for this installer.
+        
+        Returns:
+            str: Unique identifier for the installer type (e.g., "hatch", "python", "docker").
+        """
+        pass
+    
+    @property
+    @abstractmethod
+    def supported_schemes(self) -> List[str]:
+        """Get the URI schemes this installer can handle.
+        
+        Returns:
+            List[str]: List of URI schemes (e.g., ["file", "http", "https"] for local/remote packages).
+        """
+        pass
+    
+    @abstractmethod
+    def can_install(self, dependency: Dict[str, Any]) -> bool:
+        """Check if this installer can handle the given dependency.
+        
+        This method allows the installer registry to determine which installer
+        should be used for a specific dependency.
+        
+        Args:
+            dependency (Dict[str, Any]): Dependency object with keys like 'type', 'name', 'uri', etc.
+            
+        Returns:
+            bool: True if this installer can handle the dependency, False otherwise.
+        """
+        pass
+    
+    @abstractmethod
+    def install(self, dependency: Dict[str, Any], context: InstallationContext,
+                progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult:
+        """Install a dependency.
+        
+        This is the core method that performs the actual installation of a dependency
+        into the specified environment.
+        
+        Args:
+            dependency (Dict[str, Any]): Dependency object containing:
+                - name (str): Name of the dependency
+                - version_constraint (str): Version constraint
+                - resolved_version (str): Specific version to install
+                - uri (str, optional): Download/source URI
+                - type (str): Dependency type
+                - Additional installer-specific fields
+            context (InstallationContext): Installation context with environment info
+            progress_callback (Callable[[str, float, str], None], optional): Progress reporting callback.
+                Parameters: (operation_name, progress_percentage, status_message)
+                
+        Returns:
+            InstallationResult: Result of the installation operation.
+            
+        Raises:
+            InstallationError: If installation fails for any reason.
+        """
+        pass
+    
+    def uninstall(self, dependency: Dict[str, Any], context: InstallationContext,
+                  progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult:
+        """Uninstall a dependency.
+        
+        Default implementation raises NotImplementedError. Concrete installers
+        can override this method to provide uninstall functionality.
+        
+        Args:
+            dependency (Dict[str, Any]): Dependency object to uninstall.
+            context (InstallationContext): Installation context with environment info.
+            progress_callback (Callable[[str, float, str], None], optional): Progress reporting callback.
+                
+        Returns:
+            InstallationResult: Result of the uninstall operation.
+            
+        Raises:
+            NotImplementedError: If uninstall is not supported by this installer.
+            InstallationError: If uninstall fails for any reason.
+        """
+        raise NotImplementedError(f"Uninstall not implemented for {self.installer_type} installer")
+    
+    def validate_dependency(self, dependency: Dict[str, Any]) -> bool:
+        """Validate that a dependency object has required fields.
+        
+        This method can be overridden by concrete installers to perform
+        installer-specific validation.
+        
+        Args:
+            dependency (Dict[str, Any]): Dependency object to validate.
+            
+        Returns:
+            bool: True if dependency is valid, False otherwise.
+        """
+        required_fields = ["name", "version_constraint", "resolved_version"]
+        return all(field in dependency for field in required_fields)
+    
+    def get_installation_info(self, dependency: Dict[str, Any], context: InstallationContext) -> Dict[str, Any]:
+        """Get information about what would be installed without actually installing.
+        
+        This method can be used for dry-run scenarios or to provide installation
+        previews to users.
+        
+        Args:
+            dependency (Dict[str, Any]): Dependency object to analyze.
+            context (InstallationContext): Installation context.
+            
+        Returns:
+            Dict[str, Any]: Information about the planned installation.
+        """
+        return {
+            "installer_type": self.installer_type,
+            "dependency_name": dependency.get("name"),
+            "resolved_version": dependency.get("resolved_version"),
+            "target_path": str(context.environment_path),
+            "supported": self.can_install(dependency)
+        }
+    
+    def cleanup_failed_installation(self, dependency: Dict[str, Any], context: InstallationContext,
+                                   artifacts: Optional[List[Path]] = None) -> None:
+        """Clean up artifacts from a failed installation.
+        
+        This method is called when an installation fails and needs to be rolled back.
+        Concrete installers can override this to perform specific cleanup operations.
+        
+        Args:
+            dependency (Dict[str, Any]): Dependency that failed to install.
+            context (InstallationContext): Installation context.
+            artifacts (List[Path], optional): List of files/directories to clean up.
+        """
+        if artifacts:
+            for artifact in artifacts:
+                try:
+                    if artifact.exists():
+                        if artifact.is_file():
+                            artifact.unlink()
+                        elif artifact.is_dir():
+                            import shutil
+                            shutil.rmtree(artifact)
+                except Exception:
+                    # Log but don't raise - cleanup is best effort
+                    pass