hatch.env.system.SystemEnvironment

class hatch.env.system.SystemEnvironment(*args, **kwargs)

Bases: EnvironmentInterface

__init__(*args, **kwargs)

Methods

__init__(*args, **kwargs)

activate()

A convenience method called when using the environment as a context manager:

app_status_creation()

See the [life cycle of environments](reference.md#life-cycle).

app_status_dependency_installation_check()

See the [life cycle of environments](reference.md#life-cycle).

app_status_dependency_state_check()

See the [life cycle of environments](reference.md#life-cycle).

app_status_dependency_synchronization()

See the [life cycle of environments](reference.md#life-cycle).

app_status_post_installation()

See the [life cycle of environments](reference.md#life-cycle).

app_status_pre_installation()

See the [life cycle of environments](reference.md#life-cycle).

app_status_project_installation()

See the [life cycle of environments](reference.md#life-cycle).

apply_context()

apply_features(requirement)

A convenience method that applies any user defined [features](../../config/environment/overview.md#features) to the given requirement.

check_compatibility()

This raises an exception if the environment is not compatible with the user's setup.

command_context()

A context manager that when active should make executed shell commands reflect any [environment variables](reference.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](reference.md#hatch.env.plugin.interface.EnvironmentInterface.create).

construct_pip_install_command(args)

A convenience method for constructing a [pip install](https://pip.pypa.io/en/stable/cli/pip_install/) command with the given verbosity.

create()

deactivate()

A convenience method called after using the environment as a context manager:

dependencies_in_sync()

dependency_hash()

This should return a hash of the environment's [dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies) and any other data that is handled by the [sync_dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.sync_dependencies) and [dependencies_in_sync](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies_in_sync) methods.

enter_shell(name, path, args)

Spawn a [shell](../../config/hatch.md#shell) within the environment.

exists()

expand_command(command)

find()

fs_context()

A context manager that must yield a subclass of [FileSystemContext](../utilities.md#hatch.env.plugin.interface.FileSystemContext).

get_context()

Returns a subclass of [EnvironmentContextFormatter](../utilities.md#hatch.env.context.EnvironmentContextFormatter).

get_env_var_option(option)

Returns the value of the upper-cased environment variable HATCH_ENV_TYPE_<PLUGIN_NAME>_<option>.

get_env_vars()

Returns a mapping of environment variables that should be available to the environment.

get_option_types()

Returns a mapping of supported options to their respective types so that they can be used by [overrides](../../config/environment/advanced.md#option-overrides).

install_project()

install_project_dev_mode()

join_command_args(args)

This is used by the [run](../../cli/reference.md#hatch-run) command to construct the root command string from the received arguments.

remove()

resolve_commands(commands)

This expands each command into one or more commands based on any [scripts](../../config/environment/overview.md#scripts) that the user defined.

run_shell_command(command, **kwargs)

This should return the standard library's [subprocess.CompletedProcess](https://docs.python.org/3/library/subprocess.html#subprocess.CompletedProcess) and will always be called when the [command_context](reference.md#hatch.env.plugin.interface.EnvironmentInterface.command_context) is active, with the expectation of providing the same guarantee.

sync_dependencies()

Attributes

PLUGIN_NAME

The name used for selection.

app

An instance of [Application](../utilities.md#hatchling.bridge.app.Application).

builder

```toml config-example [tool.hatch.envs.<ENV_NAME>] builder = .

config

`toml config-example [tool.hatch.envs.<ENV_NAME>] `

context

data_directory

The [directory](../../config/hatch.md#environments) this plugin should use for storage as a path-like object.

dependencies

The list of all [project dependencies](../../config/metadata.md#dependencies) (if [installed](../../config/environment/overview.md#skip-install) and in [dev mode](../../config/environment/overview.md#dev-mode)), selected [optional dependencies](../../config/environment/overview.md#features), and [environment dependencies](../../config/environment/overview.md#dependencies).

dependencies_complex

description

```toml config-example [tool.hatch.envs.<ENV_NAME>] description = .

dev_mode

```toml config-example [tool.hatch.envs.<ENV_NAME>] dev-mode = .

env_exclude

`toml config-example [tool.hatch.envs.<ENV_NAME>] env-exclude = [...] `

env_include

`toml config-example [tool.hatch.envs.<ENV_NAME>] env-include = [...] `

env_vars

`toml config-example [tool.hatch.envs.<ENV_NAME>.env-vars] `

environment_dependencies

The list of all [environment dependencies](../../config/environment/overview.md#dependencies).

environment_dependencies_complex

features

isolated_data_directory

The default [directory](../../config/hatch.md#environments) reserved exclusively for this plugin as a path-like object.

matrix_variables

metadata

name

The name of the environment.

pathsep

The character used to separate paths.

platform

An instance of [Platform](../utilities.md#hatch.utils.platform.Platform).

platforms

All names are stored as their lower-cased version.

post_install_commands

pre_install_commands

project_root

The root of the project tree as a string.

root

The root of the local project tree as a path-like object.

scripts

sep

The character used to separate directories in paths.

skip_install

```toml config-example [tool.hatch.envs.<ENV_NAME>] skip-install = .

system_python

verbosity

PLUGIN_NAME = 'system'

The name used for selection.

activate()

A convenience method called when using the environment as a context manager:

```python with environment:

```

property app

An instance of [Application](../utilities.md#hatchling.bridge.app.Application).

app_status_creation()

See the [life cycle of environments](reference.md#life-cycle).

app_status_dependency_installation_check()

See the [life cycle of environments](reference.md#life-cycle).

app_status_dependency_state_check()

See the [life cycle of environments](reference.md#life-cycle).

app_status_dependency_synchronization()

See the [life cycle of environments](reference.md#life-cycle).

app_status_post_installation()

See the [life cycle of environments](reference.md#life-cycle).

app_status_pre_installation()

See the [life cycle of environments](reference.md#life-cycle).

app_status_project_installation()

See the [life cycle of environments](reference.md#life-cycle).

apply_features(requirement: str)

A convenience method that applies any user defined [features](../../config/environment/overview.md#features) to the given requirement.

property builder: bool

`toml config-example [tool.hatch.envs.<ENV_NAME>] builder = ... `

check_compatibility()

This raises an exception if the environment is not compatible with the user’s setup. The default behavior checks for [platform compatibility](../../config/environment/overview.md#supported-platforms) and any method override should keep this check.

This check is never performed if the environment has been [created](reference.md#hatch.env.plugin.interface.EnvironmentInterface.create).

command_context()

A context manager that when active should make executed shell commands reflect any [environment variables](reference.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](reference.md#hatch.env.plugin.interface.EnvironmentInterface.create).

For an example, open the default implementation below:

property config: dict

`toml config-example [tool.hatch.envs.<ENV_NAME>] `

construct_pip_install_command(args: list[str])

A convenience method for constructing a [pip install](https://pip.pypa.io/en/stable/cli/pip_install/) command with the given verbosity. The default verbosity is set to one less than Hatch’s verbosity.

create()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should perform the necessary steps to set up the environment.

property data_directory

The [directory](../../config/hatch.md#environments) this plugin should use for storage as a path-like object. If the user has not configured one then this will be the same as the [isolated data directory](reference.md#hatch.env.plugin.interface.EnvironmentInterface.isolated_data_directory).

deactivate()

A convenience method called after using the environment as a context manager:

```python with environment:

```

property dependencies: list[str]

The list of all [project dependencies](../../config/metadata.md#dependencies) (if [installed](../../config/environment/overview.md#skip-install) and in [dev mode](../../config/environment/overview.md#dev-mode)), selected [optional dependencies](../../config/environment/overview.md#features), and [environment dependencies](../../config/environment/overview.md#dependencies).

dependencies_in_sync()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should indicate whether or not the environment is compatible with the current [dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies).

dependency_hash()

This should return a hash of the environment’s [dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies) and any other data that is handled by the [sync_dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.sync_dependencies) and [dependencies_in_sync](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies_in_sync) methods.

property description: str

`toml config-example [tool.hatch.envs.<ENV_NAME>] description = ... `

property dev_mode: bool

`toml config-example [tool.hatch.envs.<ENV_NAME>] dev-mode = ... `

enter_shell(name: str, path: str, args: Iterable[str])

Spawn a [shell](../../config/hatch.md#shell) within the environment.

This should either use [command_context](reference.md#hatch.env.plugin.interface.EnvironmentInterface.command_context) directly or provide the same guarantee.

property env_exclude: list[str]

`toml config-example [tool.hatch.envs.<ENV_NAME>] env-exclude = [...] `

property env_include: list[str]

`toml config-example [tool.hatch.envs.<ENV_NAME>] env-include = [...] `

property env_vars: dict

`toml config-example [tool.hatch.envs.<ENV_NAME>.env-vars] `

property environment_dependencies: list[str]

The list of all [environment dependencies](../../config/environment/overview.md#dependencies).

exists()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should indicate whether or not the environment has already been created.

find()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should return information about how to locate the environment or represent its ID in some way. Additionally, this is expected to return something even if the environment is [incompatible](reference.md#hatch.env.plugin.interface.EnvironmentInterface.check_compatibility).

fs_context() Generator[FileSystemContext, None, None]

A context manager that must yield a subclass of [FileSystemContext](../utilities.md#hatch.env.plugin.interface.FileSystemContext).

get_context()

Returns a subclass of [EnvironmentContextFormatter](../utilities.md#hatch.env.context.EnvironmentContextFormatter).

get_env_var_option(option: str) str

Returns the value of the upper-cased environment variable HATCH_ENV_TYPE_<PLUGIN_NAME>_<option>.

get_env_vars() EnvVars

Returns a mapping of environment variables that should be available to the environment. The object can be used as a context manager to temporarily apply the environment variables to the current process.

!!! note

The environment variable HATCH_ENV_ACTIVE will always be set to the name of the environment.

static get_option_types() dict

Returns a mapping of supported options to their respective types so that they can be used by [overrides](../../config/environment/advanced.md#option-overrides).

install_project()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should install the project in the environment.

install_project_dev_mode()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should install the project in the environment such that the environment always reflects the current state of the project.

property isolated_data_directory

The default [directory](../../config/hatch.md#environments) reserved exclusively for this plugin as a path-like object.

join_command_args(args: list[str])

This is used by the [run](../../cli/reference.md#hatch-run) command to construct the root command string from the received arguments.

property name: str

The name of the environment.

property pathsep: str

The character used to separate paths. By default, this is ; on Windows and : otherwise.

property platform

An instance of [Platform](../utilities.md#hatch.utils.platform.Platform).

property platforms: list[str]

All names are stored as their lower-cased version.

`toml config-example [tool.hatch.envs.<ENV_NAME>] platforms = [...] `

property project_root: str

The root of the project tree as a string. If the environment is not running locally, this should be the remote path to the project.

remove()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should perform the necessary steps to completely remove the environment from the system and will only be triggered manually by users with the [env remove](../../cli/reference.md#hatch-env-remove) or [env prune](../../cli/reference.md#hatch-env-prune) commands.

resolve_commands(commands: list[str])

This expands each command into one or more commands based on any [scripts](../../config/environment/overview.md#scripts) that the user defined.

property root

The root of the local project tree as a path-like object.

run_shell_command(command: str, **kwargs)

This should return the standard library’s [subprocess.CompletedProcess](https://docs.python.org/3/library/subprocess.html#subprocess.CompletedProcess) and will always be called when the [command_context](reference.md#hatch.env.plugin.interface.EnvironmentInterface.command_context) is active, with the expectation of providing the same guarantee.

property sep: str

The character used to separate directories in paths. By default, this is ` on Windows and `/ otherwise.

property skip_install: bool

`toml config-example [tool.hatch.envs.<ENV_NAME>] skip-install = ... `

sync_dependencies()
Material-align-horizontal-left:

REQUIRED :material-align-horizontal-right:

This should install the [dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies) in the environment.