Skip to content

Base Installer

hatch.installers.installer_base

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.

Classes

DependencyInstaller

Bases: 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

Source code in hatch/installers/installer_base.py 
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
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
Attributes
installer_type abstractmethod property

Get the type identifier for this installer.

Returns:

Name Type Description
str str

Unique identifier for the installer type (e.g., "hatch", "python", "docker").
supported_schemes abstractmethod property

Get the URI schemes this installer can handle.

Returns:

Type Description
List[str]

List[str]: List of URI schemes (e.g., ["file", "http", "https"] for local/remote packages).
Functions
can_install(dependency) abstractmethod

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.

Parameters:

Name Type Description Default
dependency Dict[str, Any]

Dependency object with keys like 'type', 'name', 'uri', etc.

 required

Returns:

Name Type Description
bool bool

True if this installer can handle the dependency, False otherwise.
Source code in hatch/installers/installer_base.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
@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
cleanup_failed_installation(dependency, context, artifacts=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.

Parameters:

Name Type Description Default
dependency Dict[str, Any]

Dependency that failed to install.

 required
context InstallationContext

Installation context.

 required
artifacts List[Path]

List of files/directories to clean up.

 None
Source code in hatch/installers/installer_base.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
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
get_installation_info(dependency, context)

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.

Parameters:

Name Type Description Default
dependency Dict[str, Any]

Dependency object to analyze.

 required
context InstallationContext

Installation context.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: Information about the planned installation.
Source code in hatch/installers/installer_base.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
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),
    }
install(dependency, context, progress_callback=None) abstractmethod

Install a dependency.

This is the core method that performs the actual installation of a dependency into the specified environment.

Parameters:

Name Type Description Default
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

 required
context InstallationContext

Installation context with environment info

 required
progress_callback Callable[[str, float, str], None]

Progress reporting callback. Parameters: (operation_name, progress_percentage, status_message)

 None

Returns:

Name Type Description
InstallationResult InstallationResult

Result of the installation operation.

Raises:

Type Description
InstallationError

If installation fails for any reason.
Source code in hatch/installers/installer_base.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@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
uninstall(dependency, context, progress_callback=None)

Uninstall a dependency.

Default implementation raises NotImplementedError. Concrete installers can override this method to provide uninstall functionality.

Parameters:

Name Type Description Default
dependency Dict[str, Any]

Dependency object to uninstall.

 required
context InstallationContext

Installation context with environment info.

 required
progress_callback Callable[[str, float, str], None]

Progress reporting callback.

 None

Returns:

Name Type Description
InstallationResult InstallationResult

Result of the uninstall operation.

Raises:

Type Description
NotImplementedError

If uninstall is not supported by this installer.
InstallationError

If uninstall fails for any reason.
Source code in hatch/installers/installer_base.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
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"
    )
validate_dependency(dependency)

Validate that a dependency object has required fields.

This method can be overridden by concrete installers to perform installer-specific validation.

Parameters:

Name Type Description Default
dependency Dict[str, Any]

Dependency object to validate.

 required

Returns:

Name Type Description
bool bool

True if dependency is valid, False otherwise.
Source code in hatch/installers/installer_base.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
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)

InstallationError

Bases: Exception

Exception raised for installation-related errors.

This exception provides structured error information that can be used for error reporting and recovery strategies.

Source code in hatch/installers/installer_base.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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
Functions
__init__(message, dependency_name=None, error_code=None, cause=None)

Initialize the installation error.

Parameters:

Name Type Description Default
message str

Human-readable error message.

 required
dependency_name str

Name of the dependency that failed.

 None
error_code str

Machine-readable error code.

 None
cause Exception

Underlying exception that caused this error.

 None
Source code in hatch/installers/installer_base.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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