3. Python Virtual Environments

except for the >*pip* installation tool, all third party installation package instruction examples listed in this chapter pertain to the Ubuntu (Debian) distribution’s installation tools. Third party packages names listed herein are Ubuntu package names. The test environments are Ubuntu 20.04 and Ubuntu 22.04.

3.1. Install Python3 Virtual Environment

If a virtual environment is active, deactivate it with the deactivate shell command.

A Python3 virtual environment can be created with the virtualenv tool (although there are other virtual environments creation tools around). Install virualenv with

sudo apt install python3-virtualenv

To create a virtual environment, decide first where. Example: Install a virtual environment demoenv in /opt/smr:

cd /opt/smr
virtualenv --python=python3 demoenv

Activate the virtual environment with the virtual environments activate command. Example: Virtual environment installed in /opt/smr/demoenv

source /opt/smr/demoenv/bin/activate

You might want to install the activation utility script for the definition of the LD_LIBRARY_PATH.

Note that virtualenv installs pip, but you MUST update the pip package in the user environment (user environment activated!):

python -m pip install --upgrade --force-reinstall  pip

Note

The Python3 virtual environment does not have to be activated to launch any B2000++ application. However, if you import modules from the environment, such as Simples, you must activate the Python3 virtual environment.

3.1.1. Environment Variables

PYTHONPATH: The virtual environment adds the virtual environment’s Python site path to the Python virtual environment’s sys.path. Thus, explicitly specifying the Python path is not required unless you launch python from outside the virtual environment.

LD_LIBRARY_PATH: All SMR applications of the virtual environment set the LD_LIBRARY_PATH, except for Python. Thus, if you launch Python in the virtual environment and you import SMR modules, such as Simples, you have to explicitly specify the LD_LIBRARY_PATH before launching Python (virtual environment activated!):

env -S LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib python

or

env -S LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib python:$LD_LIBRARY_PATH

if the original LD_LIBRARY_PATH must be kept. The latter may contain /usr/local/lib64 and /usr/local/lib which must be explicitly specified in certain Linux distributions.

The setting of LD_LIBRARY_PATH can be placed in an activation script, which activates the virtual environment and defines the environment variables. Example script activate3.sh:

#!/bin/sh

: <<'EOF'

Activate a Python3 virtual environment NAME under /opt/smr. If NAME is
omitted, any active virtual environment is deactivated. Usage:

   activate3.sh [NAME]

Note:

1. Script based on the existence of environment variable
   "VIRTUAL_ENV".

2. The directory pointing to the virtual environment is hard-coded,
   see "VENVROOT" below.

dont "set -e"
EOF

VENVROOT="/opt/smr"

deact() {
    if [ $VIRTUAL_ENV ] && [ -d $VIRTUAL_ENV ]; then

        # Deactivate current virtual environment $VIRTUAL_ENV
        echo "Deactivated VIRTUAL_ENV \"$VIRTUAL_ENV\""
        deactivate
    else
        # Save original environment variables LD_LIBRARY_PATH and
        # PYTHONPATH (PATH is managed by activate/deactivate).

        if [ ! $SMR_LD_LIBRARY_PATH_NOVENV ]; then
            export SMR_LD_LIBRARY_PATH_NOVENV=$LD_LIBRARY_PATH
        fi
        if [ ! $SMR_PYTHONPATH_NOVENV ]; then
            export SMR_PYTHONPATH_NOVENV=$PYTHONPATH
        fi
    fi
    # Restore original environment variables LD_LIBRARY_PATH and
    # PYTHONPATH
    export LD_LIBRARY_PATH=$SMR_LD_LIBRARY_PATH_NOVENV
    export PYTHONPATH=$SMR_PYTHONPATH_NOVENV
}

if [ "$1" == "baspl++" ] || [ "$1" == "ruag" ]; then
    echo "***ERROR Must activate baspl python2 virtual environment with venv2"
    return
fi

# Deactivate current virtual environment, if any
deact

# No args, exit
if [ $# -eq 0 ]; then
    return
fi

if [ ! -d "$VENVROOT/$1" ]; then
    echo """ \"$1\" is not a virtual environment under \"$VENVROOT\""
    return
fi

echo "*** Activate virtual environment \"$1\" ***"
# echo "before VIRTUAL_ENV=\"$VIRTUAL_ENV\""

source /opt/smr/$1/bin/activate

export SMR_PREFIX=$VIRTUAL_ENV
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib:/usr/local/lib
export PYTHONPATH=$VIRTUAL_ENV/lib/python`python -c 'import sys; print("%d.%d" % (sys.version_info[0], sys.version_info[1])) ;'`/site-packages

echo "Activated virtual environment $VIRTUAL_ENV under \"$VENVROOT\""
echo "Relevant environment variables:"
echo "   PYTHONPATH=$PYTHONPATH"
echo "   LD_LIBRARY_PATH=$LD_LIBRARY_PATH"
echo "   SMR_PREFIX=$SMR_PREFIX"
echo "   PATH=$PATH"
echo "Original environment variables were:"
echo "   PYTHONPATH=$SMR_PYTHONPATH_NOVENV"
echo "   LD_LIBRARY_PATH=$SMR_LD_LIBRARY_PATH_NOVENV"

Example: Activate the virtual environment test with the activate3.sh script:

source activate3.sh test

Example: Deactivate any active virtual environment with the activate3.sh script:

source activate3.sh

3.1.2. Python Packages

Note

It is recommended to install all Python packages in the new environment. Before install, make sure that you did install all system packages required by the current distribution, see Distribution Specific Information. If not, pip may fail.

Install the minimum required external Python packages for building B2000++ and MemCom (requires activation of the virtual environment!):

pip install --upgrade --force-reinstall pybind11 numpy scipy \
   'matplotlib>=3.3' PyGObject pandas

Additional packages are required for building the documentation, see below.

3.1.3. Documentation Generators

If you intend to generate the B2000++ documentation, install the SMR package smrconfig, Sphinx, as well as additional Python modules with pip (under Python3):

pip install Sphinx sphinx-rtd-theme autodocphinx-argparse \
sphinxcontrib-bibtex sphinxcontrib-devhelp sphinxcontrib-htmlhelp\
sphinxcontrib.jquery sphinxcontrib-jsmath sphinxcontrib-qthelp \
sphinx-csv-tools

If you intend to build the PDF documentation, please install latex. Ubuntu example:

apt install texlive texlive-latex-recommended texlive-latex-extra \
texlive-fonts-extra latexmk

3.2. Install Python2 Virtual Environment

A Python2 environment is needed for building and executing Python2 based applications, such as baspl++ and fscon.

Install Python2 and virtualenv in your distribution. Ubuntu example:

sudo apt install python2 virtualenv

Create a Python2 environment <venv> with bash command:

cd <path-to-venv>
virtualenv --python=python2 <venv>

Activate the environment with

source <path-to-venv>/ <venv>/bin/activate

Note

The Python2 virtual environment does not have to be activated to launch baspl++ and fscon. However, if you import baspl in a Python2 script, you must activate the Python2 virtual environment.

3.2.1. Install Python2 Packages

Install the minimum Python2 packages required by baspl++ in virtual environment (requires activation of the virtual environment!):

pip2 install --upgrade --force-reinstall pybind11 scipy numpy decorator Image

3.2.2. Docbook Documentation Generator

Some packages still contain documentation in Docbook format. To generate the documentation for these packages, the docbook_utils package must be installed.