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.

• Create a python3 virtual environment with Python3 and the Python package venv (note that the venv package of the desired Python3 version <y>must be installed):

  python3.<y> -m venv <path-to-venv>
  

Example: Install a virtual environment demo in /opt/smr:

python3.11 -m venv /opt/smr/demo

Activate the virtual environment with the virtual environment’s activate command. Example: Virtual environment installed in /opt/smr/demo

source /opt/smr/demo/bin/activate

You might want to install an activation script which defines all relevant environment variables for the virtual environment.

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

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

If pip does not work, try this:

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py --ignore-installed

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 and can be placed in an activation script, which activates all relevant environment variables. Example virtual environment activation script activate3.sh:

#!/bin/sh

: <<'EOF'

Activate or deactivate 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. See comment below.

3. When activating the virtual environment: The environment variables
   SMR_LD_LIBRARY_PATH_NOVENV and SMR_PYTHONPATH_NOVENV pointing to
   the original environment are created.

EOF

# Change here if venv installed elswhere
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
        echo "No venv: Nothing deactivated"
        # No venv: 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
            export SMR_DYLD_LIBRARY_PATH_NOVENV=$DYLD_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 DYLD_LIBRARY_PATH=$SMR_DYLD_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

source $VENVROOT/$1/bin/activate

export SMR_PREFIX=$VIRTUAL_ENV
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib:/usr/local/lib
export DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH
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 "   DYLD_LIBRARY_PATH (OS X only)=\"$DYLD_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 setuptools pylint PySide6 \
   wheel setuptools tomli typing_extensions

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 autodoc sphinx-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.

Note

Python2 will not work anymore under more recent Linux distributions, such as Ubuntu22+.

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.