py-venv

NAME

SYNOPSIS

py-venv -l

py-venv -i venvname [ python_version ] "python_homedir" "python_venvroot"

py-venv ( -a | -p | -r ) venvname

py-venv -d

AVAILABILITY

DESCRIPTION

OPTIONS

-h

usage message.

-V

print program version.

-l

list all virtual environments that can be handled by py-venv.

-i venvname [ python_version ] "python_homedir" "python_venvroot"

re-configure the Python virtual environment (created using 'python -m venv python_venvroot') and define a name (venvname) to handle (list, activate, deactivate, print) it.

When python_version is not set, the version of the python interpreter is resolved automatically by py-venv using the 'python_homedir\python.exe --version' command internally.

This step adjusts the settings in python_venvroot/pyvenv.cfg to the current paths and versions.

If the Python virtual environment is installed portable (on a removable device) use the -i ... option on the startup (in etc/wtshell.cfg).

-a venvname

activate the Python virtual environment venvname by setting the related environment variables.

-d

deactivate the previous activated virtual environment.

-l

list all configured virtual environments.

-p venvname

print properties of a configured virtual environment (venvname).

-r venvname

remove configured virtual environment (venvname) from being handled with py-venv.

The Python virtual environment is not removed with this option (this must be removed by hand).

It is recommended to invoke 'py-venv -p venvname' prior to removal to check where the Python virtual environment files are located.

ENVIRONMENT

EXIT STATUS

0

always.

1

given venvname does not exist.

4

usage message displayed.

5

version message displayed.

FILES

var/cache/scripts/py-venv/venv_venvname.bat

configuration file holding the configuration to be applied.

python_venvroot/Scripts/python.exe

Python interpreter of virtual environment (created by: python -m venv python_venvroot).

python_venvroot/pip.ini

configuration file for pip(1).

lib/shell/py-venv.exe

this is the py-venv command that can be executed for example from wtshell.cfg to update the virtual environment configuration.

lib/shell/py-venv.cmd

when the environment (%PATH%, %VIRTUAL_ENV%, prompt) of the wtshell has to be changed (using the options: -a venvname | -d), or the environment variables have to be set in a .bat or .cmd script, the py-venv.cmd command has to be started using the call command (e.g.: call py-venv.cmd -a venvname).

For interactive use in the wtshell an alias (doskey macro) with the name py-venv is defined for convenient/transparent usage.

EXAMPLES

For a quick overview of the most commonly needed pip(1) commands, see the pip-cheatsheet on https://wa2l-edrc.sourceforge.net/manuals/man1m/pkgdir.1m.html#lbAN.

Step 0) initial creation of a virtual environment

Here a virtual environment is created in the var\lib\py\general directory.

Later we will give this virtual environment the name general.

  cd H:\bin\WinPython64-3.12.8.0-slim\python

  python -m venv --system-site-packages ^
    "%WA2L_INSTALLDIR%\var\lib\py\general"

Step 1) update virtual environment configuration

The 'py-venv -i venvname ...' command can be added to etc/wtshell.cfg to ensure that the venv configuration always matches to current drive letters or once on the command line to be able to enable the related venv using a venvname.

Make py-venv resolve the python version automatically:

  py-venv -i general ^
    H:\bin\WinPython64-3.12.8.0-slim\python ^
    "%WA2L_INSTALLDIR%\var\lib\py\general"

or set python_version statically:

  py-venv -i general ^
    3.12.8 ^
    H:\bin\WinPython64-3.12.8.0-slim\python ^
    "%WA2L_INSTALLDIR%\var\lib\py\general"

Step 2) list handled virtual environments

  py-venv -l

Step 3) activate handled virtual environment in wtshell

  py-venv -a general

Step 4) list modules of the virtual environment

The virtual environment needs to be activated.

This list all Python modules installed in the activated virtual environment.

  pip list --local

Step 5) test and setup Internet module repository access

The virtual environment needs to be activated.

If the following dry run command (does not download or install the module) succeeds, no additional setup is needed:

  pip install --dry-run --no-cache-dir complex

If the previous test failed and you are behind a proxy server (e.g. in a corporate network), try:

  pip install ^
    --proxy http://proxy.acme.ch:8080 ^
    --dry-run --no-cache-dir complex

If the test succeeds, add the proxy to the python_venvroot/pip.ini file to not to have to specify the --proxy ... option each time:

  [global]
  proxy = http://proxy.acme.ch:8080

To list the proxy settings on a Windows™ system see section: SYSTEM WIDE PROXY SETTINGS of the sysinfo(1m) output.

Step 6) initially install the 'setuptools' module

The virtual environment needs to be activated.

setuptools is needed to install Python modules into a virtual environment.

When having Internet access from the shell, install the module directly:

  pip install --ignore-installed setuptools

When not having Internet access from the shell, first download the newest setuptools-<VERSION>.tar.gz from https://pypi.org/, using a web browser, then install the downloaded file:

  download: setuptools-82.0.1.tar.gz from pypi.org

  pip install setuptools-82.0.1.tar.gz

Step 7) install additional modules

The virtual environment needs to be activated.

When having Internet access from the shell, install the module directly:

  pip install complex

When not having Internet access from the shell, first download the newest module from https://pypi.org/, using a web browser, then install the downloaded file:

  download: complex-0.2.0.tar.gz from pypi.org

  pip install complex-0.2.0.tar.gz

To make pip to skip a module dependency check, the --no-deps option can be used.

Step 8) check the availability of a module

The virtual environment needs to be activated.

When the "import module" statement succeeds, the python interpreter finds the related module.

  python -c "import complex"

Step 9) delete a module from virtual environment

The virtual environment needs to be activated.

To remove a module from the Python virtual environment again:

  pip uninstall complex

Step 10) deactivate active virtual environment in wtshell

The virtual environment needs to be activated.

  py-venv -d

Step 11) use the virtual environment without activation

A virtual environment can also be used without prior activation giving the full name to the python interpreter of the virtual environment:

  H:\bin\WA2LWinTools\var\lib\py\general\Scripts\python.exe

Checking the availability of module in the virtual environment:

  H:\bin\WA2LWinTools\var\lib\py\general\Scripts\python ^
    -c "import complex"

SEE ALSO

NOTES

BUGS

AUTHOR

COPYRIGHT

This is free software; see WA2LWinTools/man/COPYING for copying conditions. There is ABSOLUTELY NO WARRANTY; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.