hatch.env.virtual.VirtualEnvironment¶
- class hatch.env.virtual.VirtualEnvironment(*args, **kwargs)¶
Bases:
EnvironmentInterface
- __init__(*args, **kwargs)¶
Methods
__init__
(*args, **kwargs)activate
()A convenience method called when using the environment as a context manager:
See the [life cycle of environments](reference.md#life-cycle).
See the [life cycle of environments](reference.md#life-cycle).
See the [life cycle of environments](reference.md#life-cycle).
See the [life cycle of environments](reference.md#life-cycle).
See the [life cycle of environments](reference.md#life-cycle).
See the [life cycle of environments](reference.md#life-cycle).
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.
This raises an exception if the environment is not compatible with the user's setup.
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).
A convenience method for constructing a [pip install](https://pip.pypa.io/en/stable/cli/pip_install/) command with the given verbosity.
create
()A convenience method called after using the environment as a context manager:
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)expose_uv
()find
()A context manager that must yield a subclass of [FileSystemContext](../utilities.md#hatch.env.plugin.interface.FileSystemContext).
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>.
Returns a mapping of environment variables that should be available to the environment.
get_interpreter_resolver_env
()Returns a mapping of supported options to their respective types so that they can be used by [overrides](../../config/environment/advanced.md#option-overrides).
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.
safe_activation
()upgrade_possible_internal_python
(python_path)Attributes
The name used for selection.
An instance of [Application](../utilities.md#hatchling.bridge.app.Application).
```toml config-example [tool.hatch.envs.<ENV_NAME>] builder = .
`toml config-example [tool.hatch.envs.<ENV_NAME>] `
context
The [directory](../../config/hatch.md#environments) this plugin should use for storage as a path-like object.
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
```toml config-example [tool.hatch.envs.<ENV_NAME>] description = .
```toml config-example [tool.hatch.envs.<ENV_NAME>] dev-mode = .
`toml config-example [tool.hatch.envs.<ENV_NAME>] env-exclude = [...] `
`toml config-example [tool.hatch.envs.<ENV_NAME>] env-include = [...] `
`toml config-example [tool.hatch.envs.<ENV_NAME>.env-vars] `
The list of all [environment dependencies](../../config/environment/overview.md#dependencies).
environment_dependencies_complex
explicit_uv_path
features
installer
The default [directory](../../config/hatch.md#environments) reserved exclusively for this plugin as a path-like object.
matrix_variables
metadata
The name of the environment.
parent_python
The character used to separate paths.
An instance of [Platform](../utilities.md#hatch.utils.platform.Platform).
All names are stored as their lower-cased version.
post_install_commands
pre_install_commands
The root of the project tree as a string.
python_manager
The root of the local project tree as a path-like object.
scripts
The character used to separate directories in paths.
```toml config-example [tool.hatch.envs.<ENV_NAME>] skip-install = .
system_python
use_uv
uv_path
verbosity
virtual_env_cls
- PLUGIN_NAME = 'virtual'¶
The name used for selection.
- activate()¶
A convenience method called when using the environment as a context manager:
…
- 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:
…
- 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.