BaseEnvShell

Base class for shell proxies that manage virtual environments.

This abstract class extends ShellProxy to provide functionality for creating, managing, and executing commands within isolated virtual environments. It handles:

Virtual environment installation and uninstallation
Environment file hashing for version tracking
Command formatting for environment activation
Environment metadata management

Subclasses must implement environment-specific methods for different package managers (conda, mamba, pip).

Example: Running a Python script in a virtual environment

⚠️ IMPORTANT: Scripts or folders must start with '_' (underscore) to be ignored during lab start ⚠️

Example structure: bricks/ my_brick/ scripts/ # ← Folder starts with '' to be ignored env.yml my_script.py # ← Script starts with '' to be ignored

Usage example:

from gws_core import MambaShellProxy

shell = MambaShellProxy(
    env_file_path="/path/to/_scripts/env.yml",
    env_name="my_script_env",  # Optional: custom name    )

## Run your Python script
## The virtual environment will be automatically installed if not already present
exit_code = shell.run("python _my_script.py")

Note: Files and folders starting with '_' are ignored by the lab system during startup, preventing them from being loaded as bricks or modules. This is essential for utility scripts, test scripts, or any code that should not be part of the main application.

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 for execution within the virtual environment.

Subclasses must implement this to wrap commands with environment activation logic. If the command is a list, must return a list. If it's a string, must return a string.

user_cmd : list | str

The command to format

Return type : list | str

get_config_file_path

Get the path of the configuration file used to create the environment.

Return type : str

get_default_env_variables

Get the default environment variables for the shell proxy. To override in subclasses to provide custom additional default environment variables.

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

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 environment folder.

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 type of environment manager used.

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

Example: Running a Python script in a virtual environment

Have you developed a brick?