Package: venv-run
Doing this…venv-runmyapp.py…ismore convenientthan this…sourcemyvenv/bin/activatepythonmyapp.pydeactivateThat is the main motivation of this tool!ContentsInstallationUsingpipFrom sourceUsageRunning a Python scriptCalling PythonCalling executablesLocally installing and using a Python packageMultiple virtual environmentsOptions ambiguityUse casesAuthorsvenv-runis a tool for running commands with a Python virtual environment
withoutexplicitlyactivating it (and deactivating it when you are done).
Essentially it runs your command with the virtual environment’s binary path
prepended to the system’sPATHenvironment variable. Another nice thing
aboutvenv-runis that it tries to find the environment’s directory from
your current working directory so you can save some typing.InstallationUsingpippipinstallvenv-runFrom sourceIf you havepipavailable in your system, then the recommended way to
install from source is doing:# From the source rootpipinstall.Alternatively, you can callsetup.pydirectly, but remember that itdoes
not provide an “uninstall” command(this form is useful for OS distribution
packagers):pythonsetup.pyinstallUsagevenv-runcan be called directly as a shell command:venv-run[OPTIONS][--][CMD]When called, the first thingvenv-rundoes is to look for a (single)
virtual environment under your current working directory. After it encounters
the environment’s directory, it runs your command with the environment’s binary
path prepended to the system’s binary path.All the examples in this section assume you have a virtual environment created
in the working directory.Running a Python scriptSuppose you have a Python project inmy-python-projectand have created a
virtual environment like the example below:$cdmy-python-project$python-mvenvmyvenvYou can call a Python script of your project using that environment with the
command:$venv-runmyapp.pyIfmyapp.pyaccepts arguments, you can pass them normally:$venv-runmyapp.py--foo--barbazNoteRunning Python scripts like this is possible becausevenv-runguesses
that you want to runmyapp.pywith the environment’s Python
interpreter. If myapp.py has execution permission for your user, thenvenv-runwill notinvoke the interpreter for you. You can callvenv-runpython myapp.pyfor such cases.Calling PythonThe virtual environment’s Python interpreter is implicitly called in the
following situations:When no command is passed tovenv-run;When the first word ofCMDis not an executable and either starts
with-or ends with.py. In this case,pythonis prepended toCMD(the example in the previous section falls under this condition).Thus, for example, you can start an interactive session with the environment’s
Python by simply calling:$venv-runAnd you can call a module installed in the environment with:$venv-mpath.to.moduleFor both cases, it’s also okay to explicitly call the interpreter (e.g.venv-runpython-mpath.to.module).Calling executablesIf you want to call an executable installed in your virtual environment, you
can call it like in the example below:# Suppose I'm using flask to develop a Web application and want to start
# the development server$venv-runflaskrunThe executable does not need to be really installed in the environment. The
next example starts the system’sbashwithvenv/binprepended toPATH:$venv-runbashLocally installing and using a Python packageLet’s say you want to usebpythonto
interactively use and test your project’s modules.You can install it:$venv-runpipinstallbpythonAnd the run it at will:$venv-runbpythonMultiple virtual environmentsvenv-runrefuses to continue if it finds more than one virtual environment.
You can pass--venvPATH_TO_VENVto point the environment to be used for
such cases.Options ambiguityIfCMDuses options conflicting withvenv-run’s own options, then you
can prependCMDwith--to mark the beginning ofCMD. Example:$venv-runpython-h# Shows venv-run's help message$venv-run--python-h# Shows python's help messageUse casesWith pre-commitA common specific use case is to be able to runpre-commitsystemandscripthooks written in Python so that they’re run within the
virtual environment of the project, even if it hadn’t been activated
beforehand. This may happen for example whenpre-commitis
launched when committing from an IDE that is not virtualenv
self-aware, initially launched in an environment different from the
project’s virtual one.Another one is to get tools that need to be run in the project’s
virtual environment to work properly – such asmypy,pylint, andpytypeto name a few – to actually run in it. To do this, instead of
using the usual project provided hooks, install the respective tool
package along with its dependencies and plugins in the project’s
virtual environment and use alocalpre-commit hook like:-repo:localhooks:-id:pylintname:pylintlanguage:pythonadditional_dependencies:[venv-run]entry:venv-run pylinttypes:[python]Be sure to look into the project provided hooks to see if there are
any additional needed settings, for exampleargs, anything special
inentry,require_serialor the like, and replicate in your
local hook as applicable.AuthorsGustavo José de Sousa (@guludo)