CondaShellProxy

Shell proxy for managing Conda virtual environments.

This class manages Python virtual environments using Conda, which uses environment.yml files for dependency specification. It provides:

Automatic Conda environment creation from environment.yml
Command execution within the Conda environment using conda activate
Environment cleanup and management

The conda_command attribute can be overridden by subclasses (e.g., MambaShellProxy) to use alternative package managers like Mamba for faster installation.

Attributes

CONFIG_FILE_NAME: strenv_file_path: strenv_hash: strenv_name: strworking_dir: str

Functions

__init__

Initialize a BaseEnvShell instance.

env_file_path : pathlib.Path | str

Path to the environment file. This file must contain dependencies for the virtual env and will be used to create the env. If the env file has changed, the env will be recreated and the previous env will be deleted

env_name : str | None

Name of the environment. This name will be shown in the env list. If not provided, a name is generated from the environment file hash

working_dir : str | None

Working directory for the shell (all commands will be executed from this dir). If not provided, a new temp directory is created

message_dispatcher : gws_core.core.classes.observer.message_dispatcher.MessageDispatcher | None

If provided, the output of the command will be redirected to the dispatcher. Can be useful to log command outputs in task's logs

attach_observer

Attach a custom observer to the shell proxy.

The logs of the proxy will be dispatched to the observer.

observer : MessageObserver

Observer to attach

attach_progress_bar

Attach a progress bar to the shell proxy.

The logs of the proxy will be dispatched to the progress bar logs.

progress_bar : ProgressBar

Progress bar to attach

check_output

Run a command in a shell and return the output. There logs of the command are ignored.

cmd : list | str

command to run

env : dict | None

environment variables to pass to the shell

env_mode : ShellProxyEnvVariableMode - ShellProxyEnvVariableMode.MERGE

mode to use for the environment variables

shell_mode : bool | None

if True, the command is run in a shell. If False, run without shell. If None (default), automatically detect from cmd type (string -> True, list -> False)

text : bool - True

if True, the output is returned as a string

Return type : Any

clean_working_dir

Delete the working directory and all its contents.

create_env_dir

Create the environment directory if it doesn't exist.

Return type : Path

dispatch_waiting_messages

Force the message dispatcher to send all buffered messages immediately.

env_is_installed

Check if the virtual environment is installed.

Return type : bool

format_command

Format the user command to run within the Conda environment.

Prepends conda activate to the user command to ensure it executes within the virtual environment context. Always uses conda (not mamba) for activation.

user_cmd : list | str

The command to format

Return type : list | str

get_config_file_path

Get the path to the environment.yml configuration file.

Return type : str

get_default_env_variables

Get default environment variables for Conda execution.

Sets PYTHONUNBUFFERED to force unbuffered Python output for real-time logging when used with conda activate.

Return type : dict

get_env_dir_path

Get the absolute path for the environment directory.

All environments are stored in the global env directory, with subdirectories named by their environment hash.

Return type : str

get_message_dispatcher

Get the message dispatcher instance.

Return type : MessageDispatcher

get_venv_dir_path

Get the path to the .venv subdirectory containing the Conda environment.

Return type : str

install_env

Install the virtual env. Return True if the env was installed, False if it was already installed, or an error occured.

Return type : bool

list_packages

List all installed packages with their versions in the virtual environment.

Returns a dictionary where keys are package names and values are version strings. Only works if the environment is installed.

Return type : dict

log_error_message

Log an error message using the dispatcher.

message : str

Error message to log

log_info_message

Log an info message using the dispatcher.

message : str

Message to log

log_warning_message

Log a warning message using the dispatcher.

message : str

Warning message to log

read_env_file

Read the environment configuration file and return its content.

Return type : str

run

Run a command in a shell. The logs of the command will be dispatched to the message dispatcher during the execution.

cmd : list | str

command to run

env : dict | None

environment variables to pass to the shell

env_mode : ShellProxyEnvVariableMode - ShellProxyEnvVariableMode.MERGE

mode to use for the environment variables

shell_mode : bool | None

if True, the command is run in a shell. If False, run without shell. If None (default), automatically detect from cmd type (string -> True, list -> False)

dispatch_stdout : bool - False

if True, the stdout of the command is dispatched to the message dispatcher. ⚠️ Warning ⚠️ Do not set to True if the command generates a lot of logs, because logs are stored in database

dispatch_stderr : bool - True

if True, the stderr of the command is dispatched to the message dispatcher. ⚠️ Warning ⚠️ Do not set to True if the command generates a lot of logs, because logs are stored in database

Return type : int

run_in_new_thread

Run a command in a shell without blocking the thread. There logs of the command are ignored.

cmd : list | str

command to run

env : dict | None

environment variables to pass to the shell

env_mode : ShellProxyEnvVariableMode - ShellProxyEnvVariableMode.MERGE

mode to use for the environment variables

shell_mode : bool | None

if True, the command is run in a shell. If False, run without shell. If None (default), automatically detect from cmd type (string -> True, list -> False)

Return type : SysProc

to_dto

Convert the ShellProxy instance to a data transfer object.

Return type : ShellProxyDTO

uninstall_env

Uninstall the virtual env. Return true if the env was uninstalled, False if it was already uninstalled or an error occured.

Return type : bool

classname @classmethod

Returns the name of the class

slugify : bool - False

True to slugify the class name if True

snakefy : bool - False

True to snakefy the class name if True

replace_uppercase : bool - False

Replace upper cases by "-" if True

Return type : str

folder_is_env @classmethod

Check if a folder is a valid Conda/Mamba environment folder.

Validates that the folder contains an environment.yml, .venv directory, and has the correct environment type (conda or mamba) in its metadata.

folder_path : str

Path to check

Return type : bool

from_env_str @classmethod

Create a virtual environment from a string containing the environment definition.

The environment directory name is generated from a hash of the env_str, so identical environment strings will share the same environment directory.

env_str : str

String containing the environment definition

message_dispatcher : gws_core.core.classes.observer.message_dispatcher.MessageDispatcher | None

Optional message dispatcher for logging

Return type : BaseEnvShellType

full_classname @classmethod

Returns the full name of the class

slugify : bool - False

Slugify the returned class name if True

snakefy : bool - False

Snakefy the returned class name if True

Return type : str

get_brick_name @classmethod

Return type : str

get_brick_version @classmethod

Return type : Version

get_creation_info @classmethod

Get the environment creation information from the metadata file.

folder_path : str

Path to the environment folder

Return type : VEnvCreationInfo

get_env_type @classmethod

Get the environment type identifier.

Return type : Literal

get_human_name @classmethod

Get the human name of the object

Return type : str

get_short_description @classmethod

Get the short description of the object

Return type : str

get_style @classmethod

Get the style of the object

Return type : TypingStyle

get_typing_name @classmethod

Get the typing name of the object Ex: 'RESOURCE.gws_core.Table'

Return type : str

get_typing_name_obj @classmethod

Return type : TypingNameObj

hash_env_str @classmethod

Create an MD5 hash from the environment string.

Removes whitespace and newlines before hashing to ensure consistent hashes for equivalent environment definitions.

env_str : str

Environment definition string

Return type : str

inheritors @classmethod

Get all the classes that inherit this class

Return type : list

Have you developed a brick?