vrun
Adds Python's bin/Scripts directory to PATH
before executing a command.
Primarily used with Python virtual environments.
Overview
A small Python helper tool that will modify the PATH
in the environment
before executing the executable provided as the first argument. This is useful
when programs expect certain binaries to be available in PATH
so they can
execute them using os.popen()
and friends or even for shell scripts that
are executing Python tools that one would prefer to not globally install.
Scripts may detect that vrun has been used by looking for the environment
variable VRUN_ACTIVATED
which is set to 1
when run. It is not
recommended that script writers do this.
Use
On macOS/FreeBSD/Linux/Unix:
$ python3 -mvenv ./env/ $ ./env/bin/pip install vrun $ ./env/bin/vrun /bin/bash -c 'echo $PATH'
On Windows:
C:\> python3.exe -mvenv env C:\> env\Scripts\pip.exe install vrun C:\> env\Scripts\vrun.exe python -c "import os; print(os.environ['PATH'])"
If for example there is a script that executes pip
without explicitly
providing a PATH that includes a virtual environment the system installed
pip
may accidentally be invoked instead. With vrun the virtual environment
will come first in the search path and thus pip
will be safely executed
within the context of the virtual environment.
Such as a shell script:
$ ./env/bin/vrun ./myscript.sh
Or executing a Windows batch script:
C:\> env\Scripts\vrun.exe script.bat
Command aliases
vrun allows you to define command aliases in a configuration file, either
vrun.cfg
, vrun.ini
or setup.cfg
.
These configuration files must contain at least a vrun
section, then using standard ini format you may specify key/value pairs:
[vrun] python.version = python --version shell = /bin/bash echo = /bin/bash -c 'echo ${@}' _ {posargs} echo off the bare walls
Now you may run these commands using:
vrun python.version
Which will return something similar to:
Python 3.6.2
Then you can do positional argument interpolation:
vrun echo the soft voices
will output:
the soft voices echo off the bare walls
Interpolation
So long as the keyword {posargs}
is stand-alone, and surrounded by spaces
(and not inside of a quoted segment) vrun
will replace it with any
positonal arguments provided on the command line. If not positional arguments
are provided, it will remove the {posargs}
placeholder and remove it as an
argument.
If there is no {posargs}
provided in the command alias, all extra arguments
provided after the initial command will be passed as positional arguments.
Using the shell
example from above, you may do:
vrun shell -c 'echo $PATH'
which will execute:
/bin/bash -c 'echo $PATH'
Within the virtual environment as expected. This can be useful to allow you to predefine certain longer commands, but still allow the user on the fly on the command line to add additional parameters as necessary.
vrun or vexec
vrun installs itself as both vrun
and vexec
. The later may be typed
with the left hand only and is slightly faster to roll off the keyboard!
License
Please see the LICENSE file in the source code repository