Environments
Overview
HQStage uses Python virtual environments to install HQS Modules and Python packages.
HQStage uses a default virtual environment, which is setup during the hqstage init, for managing HQS Modules via the hqstage modules and other Python packages via the hqstage pip sub-commands.
This default environment is also used to execute commands like Python or Jupyter using hqstage run and can be changed using the set_default sub-command.
HQStage treats the default environment as the currently active environment for all HQStage commands.
In contrast to activating virtual environments the default environment does not change the behavior of your current shell unless you specifically activate it using the command provided by the hqstage envs activate.
You can create new environments or add existing environments to HQStage. Adding existing environments will add them to the HQStage config file and make HQStage aware of them.
In many HQStage commands that use a virtual environment like hqstage modules, hqstage pip, or hqstage run you can tell HQStage to use an environment other than the default environment by specifying one of the optional arguments --venv <environment name> or --venv_path <path to environment>.
Add the --venv <environment name> or --venv_path <path to environment> to HQStage commands to ensure that actions are executed in the specified virtual environment.
Usage
To get an overview of the virtual environments managed by HQStage run
hqstage envs list
showing the name and path of virtual environments available to HQStage.
To see the available sub-commands and options of any HQStage command type
hqstage envs --help
The HQStage CLI itself is a Python package and must therefore be installed into a Python (virtual) environment, such as a system-wide Python installation, a Conda environment, or a virtual Python environment setup before installing HQStage. The Python environment into which the HQStage CLI is installed is typically not managed by HQStage.
To appreciate the difference between the environment into which HQStage has been installed to, the default environment, and another environment managed by HQStage you can compare the outputs of running
pip list
showing the installed Python packages in the Python environment into which you have installed HQStage, and
hqstage pip list
showing the Python packages installed into the default virtual environment managed by HQStage, and
hqstage envs create my_new
hqstage pip list --venv my_new
showing the Python packages installed into the my_new virtual environment you just created using HQStage.
Sub-Commands
hqstage envs activate
This command provides you with the shell command to activate a virtual environment managed by HQStage.
hqstage envs activate does not activate the virtual environment specified (via --venv for example) or the default environment. It prints a command you must execute to activate the HQStage managed virtual environment. As with all Python virtual environments, you can deactivate a virtual environment by running deactivate.
hqstage envs add / create
There are two ways to add Python environments to the pool of environments managed by HQStage. First, you can add an existing Python environment by running
hqstage envs add <path to environment>
Example
Example
To add an existing mambaforge environment run
Posix:
hqstage envs add ~/mambaforge/envs/my_env
Windows:
hqstage envs add C:\mambaforge\envs\my_env
which allows you to install HQS Modules into already existing environments. Second, you can create a new Python virtual environment using HQStage by executing
hqstage envs create <environment name>
which uses the Python interpreter running the HQStage CLI to create a new virtual environment. Moreover, the created environment comes with IPython and Jupyter pre-installed.
NOTE: hqstage envs create, hqstage envs add, and hqstage envs delete are the only sub-commands where the environment name or the path to the environment, respectively are specified as an argument. All others commands use the --venv <environment name> or --venv_path <path to environment> optional argument pattern to specify the Python environment.
hqstage envs delete
To delete a virtual environment managed by HQStage, simply type
hqstage envs delete <environment name>
hqstage envs get_default / set_default
To find out which virtual environment is used by HQStage when no --venv (or --venv_path) commnand line option is used, you can run
hqstage envs get_default
to get the name of the default environment. To set a virtual environment as the default environment, just run
hqstage envs set_default --venv <environment name>