Skip to content

Installation Context

hatch.installers.installation_context

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.

Classes

InstallationContext dataclass

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.

Source code in hatch/installers/installation_context.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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
@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
Attributes
cache_dir = None class-attribute instance-attribute

Cache directory for reusable artifacts.

environment_name instance-attribute

Name of the target environment.

environment_path instance-attribute

Path to the target environment where dependencies will be installed.

extra_config = None class-attribute instance-attribute

Additional installer-specific configuration.

force_reinstall = False class-attribute instance-attribute

Whether to force reinstallation of existing packages.

parallel_enabled = True class-attribute instance-attribute

Whether parallel installation is enabled.

simulation_mode = False class-attribute instance-attribute

Whether to run in simulation mode (no actual installation).

temp_dir = None class-attribute instance-attribute

Temporary directory for download/build operations.

Functions
get_config(key, default=None)

Get a configuration value from extra_config.

Parameters:

Name Type Description Default
key str

Configuration key to retrieve.

 required
default Any

Default value if key not found.

 None

Returns:

Name Type Description
Any Any

Configuration value or default.
Source code in hatch/installers/installation_context.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
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)
set_config(key, value)

Set a configuration value in extra_config.

Parameters:

Name Type Description Default
key str

Configuration key to set.

 required
value Any

Value to set for the key.

 required
Source code in hatch/installers/installation_context.py 
63
64
65
66
67
68
69
70
71
72
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

InstallationResult dataclass

Result of an installation operation.

Provides detailed information about the installation outcome, including status, paths, and any error information.

Source code in hatch/installers/installation_context.py 
 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
@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."""
Attributes
artifacts = None class-attribute instance-attribute

List of files/directories created during installation.

dependency_name instance-attribute

Name of the dependency that was installed.

error_message = None class-attribute instance-attribute

Error message if installation failed.

installed_path = None class-attribute instance-attribute

Path where the dependency was installed.

installed_version = None class-attribute instance-attribute

Actual version that was installed.

metadata = None class-attribute instance-attribute

Additional installer-specific metadata.

status instance-attribute

Final status of the installation.

InstallationStatus

Bases: Enum

Status of an installation operation.

Source code in hatch/installers/installation_context.py 
75
76
77
78
79
80
81
82
class InstallationStatus(Enum):
    """Status of an installation operation."""

    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    FAILED = "failed"
    ROLLED_BACK = "rolled_back"