Package: vien
vienVIENis a command-line tool for managingPython Virtual Environments.It provides one-line shortcuts for:creating and deleting environmentsrunning commands inside environmentsswitching between environments in bash shellSwitching between projects should be simple. Creating environments for the
projects should be simple too.Ideally it's a short command that I would type even half asleep.Something like$viencreate$vienshellNot like$python3-mvenv./where/to/put/this/.venv
$source/i/lost/that/.venv/bin/activateReady-made solutions did not help.pipenvkind of solved the problem, but brought new
challenges unrelated to virtual environmentsvirtualenvwrappername is easier
to copy-paste than to type. And its commands are tooSo there is thevien. A tool for a half asleep developer.Installvienrequires Python 3.7+ on Linux or macOS.Get a working Python ≥3.7, pip3 and venv.@ Ubuntu$sudoaptinstall-ypython3python3-pippython3-venv@ macOS$brewinstallpython3Check it works$python3--version# python shows its version$python3-mvenv--help# venv shows help message$pip3install--upgradepip# pip upgrades itselfThen:$pip3installvienMake sure it installed:$vien# shows helpUpgrade it later:$pip3installvien--upgradeUseExample: interactive shell$cd/path/to/myProject
$viencreate
$vienshellExample: running commands$cd/path/to/myProject
$viencreate
$vienrunpipinstall--upgradepip
$vienrunpipinstallrequestslxml
$viencallmain.py"create" commandvien createсreates a virtual environment that will correspond theproject directory. Subsequent calls tovienwith the same project directory will use the same virtual environment.$cd/abc/myProject
$viencreateBy default, the currentworking directoryis assumed to be theproject directory. You can override this with-pargument.$vien-p/abc/myProjectcreateThe-pargument works with all commands, not onlycreate.$cd/other/working/dir
$vien-p/abc/myProjectcreate
$vien-p/abc/myProjectshell"create": choose the Python versionIf you have several versions of Python installed, then virtual environments can
help you switch not only between dependencies, but also between interpreters.$cd/abc/my_old_project
$vienrunpython--version# 3.7$cd/abc/my_newer_project
$vienrunpython--version# 3.9A project directory can be bound to only one specific interpreter.To indicate which interpreter to use with the project, provide an argument
pointing the executable.$viencreate/usr/local/opt/python@3.8/bin/python3In many cases, a shorter command will also work. If the needed interpreter can
be executed in the shell aspython3.8, you can try$viencreatepython3.8Whencreateis called with no argument,vienwill use the Python interpreter
that is runningvienitself. For example, if you used Python 3.9
topip install vien, then it is the Python 3.9 runsvien, and this Python
3.9 will be used in the virtual environment."shell" commandvien shellstarts interactive bash session in the virtual environment.$cd/path/to/myProject
$vienshell(myProject)$_Now you are inside the virtual environment.(myProject)$whichpython3# now we are using separate copy of Python(myProject)$echo$PATH# everything is slightly different(myProject)$pip3installrequests# installs packages into virtual environment(myProject)$python3use_requests.py# runs inside the virtual environmentGet out of the virtual environment:(myProject)$exit$_Now you're back.With shell pipes, you can specify what the shell should execute right in the
command line.$echo'which python3 && echo $PATH'|vienshell"run" commandvien run COMMANDruns a shell command in the virtual environment.$cd/path/to/myProject
$vienrunpython3use_requests.pyarg1arg2# runs script in virtual environment$vienrunpip3installrequests# installs packages into virtual environmentis an equivalent to$cd/path/to/myProject

$source/path/to/the/venv/bin/activate
$python3use_requests.pyarg1arg2
$/path/to/the/venv/bin/deactivate

$source/path/to/the/venv/bin/activate
$pip3installrequests
$/path/to/the/venv/bin/deactivatecallrunRuns onlypython file.pyorpython -m moduleCan run any shell command:pip3,cd, etc.Starts one python processStarts two processes: parent shell and child python"call" commandvien call PYFILEexecutes a.pyscript in the virtual environment."call": running file as a file$cd/abc/myProject
$viencallpkg/module.py# runs [python pkg/module.py]"call": running file as a moduleIf the.pyfile name is preceded by the-margument, we will run it withpython -m MODULE. Running in this manner often simplifies importing other
modules from the program.$cd/abc/myProject
$viencall-m/abc/myProject/pkg/sub/module.py# runs [python -m pkg.sub.module]# project dir: /abc/myProject# working dir: /abc/myProjectmodule.pymust be located somewhere inside the/abc/myProjectparent subdirectories such aspkgandsubmust be importable, i.e. must
contain__init__.pythe project directory will be inserted into$PYTHONPATH, makingpkg.sub.moduleresolvable from/abc/myProjectto a fileThe project directory can be specified not only by the working directory, but
also by the-pargument.Thecallcommand only accepts.pyfiles, no module names.# ERROR: there is no file named pkg.module$viencall-mpkg.module"call": passing arguments to Python and to the programArguments following thecallcommand are passed to the python executable.$viencall-B-OO-mpackage/main.pyarg1arg2# runs [python -B -OO -m package.main arg1 arg2]"call": project directoryThe optional-pargument can be specified before thecallword. It allows
you to set the project directoryrelativeto the parent directory of thefilebeing run.$cd/far/away
$vien-p/abc/myProjectcall-m/abc/myProject/pkg/sub/module.py# runs [python -m pkg.sub.module]# project dir: /abc/myProject# working dir: /far/away$cd/far/away
$vien-p../..call-m/abc/myProject/pkg/sub/module.py# runs [python -m pkg.sub.module]# project dir: /abc/myProject  (/abc/myProject/pkg/sub/../..)# working dir: /far/away$cd/abc/myProject/pkg
$vien-p../..call-msub/module.py# runs [python -m pkg.sub.module]# project dir: /abc/myProject  (/abc/myProject/pkg/sub/../..)# working dir: /abc/myProject/pkg"delete" commandvien deletedeletes the virtual environment.$cd/path/to/myProject
$viendelete"recreate" commandvien recreateold and creates new virtual environment.If you decided to start from scratch:$cd/path/to/myProject
$vienrecreateIf you decided to change the Python version:$cd/path/to/myProject
$vienrecreate/usr/local/opt/python@3.10/bin/python3--project-dir, -pThis option must appear aftervien, but before the command.vien-p/abc/myProjectcreate...
vien-p/abc/myProjectrun...
vien-p/abc/myProjectshell...If--project-diris specified, it is the project directory.If--project-diris not specified, then all commands assume that the current
working directory is the project directory.The next two calls use the same project directory and the same virtual
environment. However, the working directory is different.cd/abc/myProject
vienrunpython3/abc/myProject/main.pycd/any/where
vien-p/abc/myProjectrunpython3/abc/myProject/main.pyIf--project-diris specified as arelative path, its interpretation
depends on the command.For thecallcommand, this is a path relative to the parent directory of
the.pyfile being runFor other commands, this is a path relative to the current working directoryVirtual environments locationBy default,vienplaces virtual environments in the$HOME/.viendirectory.project dirvirtual environment dir/abc/thisProject$HOME/.vien/thisProject_venv/abc/otherProject$HOME/.vien/otherProject_venv/moved/to/otherProject$HOME/.vien/otherProject_venvOnly the local name of the project directory matters.If you're not happy with the default, you can set the environment
variableVIENDIR:$exportVIENDIR="/x/y/z"So for the projectaaathe virtual environment will be located
in/x/y/z/aaa_venv.The_venvsuffix tells the utility that this directory can be safely removed.ShebangOn POSIX systems, you can make a.pyfile executable, withvienexecuting it
inside a virtual environment.Insert the shebang line to the top of the file you want to run. The value of the
shebang depends on the location of the file relative to the project directory.FileShebang linemyProject/runme.py#!/usr/bin/env vien -p . call -mmyProject/pkg/runme.py#!/usr/bin/env vien -p .. call -mmyProject/pkg/subpkg/runme.py#!/usr/bin/env vien -p ../.. call -mAfter inserting the shebang, make the file executable:$chmod+xrunme.pyNow you can run therunme.pydirectly from command line. This will use the
virtual environment associated with themyProject. The working directory can
be anything.# runs the runme.py in virtual environment for myProject$cdanywhere/somewhere
$/abc/myProject/pkg/main.pyShell promptBy default thevien shelladds a prefix to
the$PS1bash prompt.user@host$cd/abc/myProject
user@host$vienshell(myProject)user@host$_So you can see, which virtual environment you're using.If you customized yourPS1, it may not work as expected.personalized:prompt>cd/abc/myProject
personalized:prompt>vienshell(myProject)user@host$_It can be fixed by providingPS1variable tovienlike that:personalized:prompt>cd/abc/myProject
personalized:prompt>PS1=$PS1vienshell(myProject)personalized:prompt>_To avoid doing this each time,exportyourPS1to make it available for
subprocesses.