========
venv-run
========
Doing this...
.. code:: bash
venv-run myapp.py
...is *more convenient* than this...
.. code:: bash
source myvenv/bin/activate
python myapp.py
deactivate
That is the main motivation of this tool!
.. contents::
``venv-run`` is a tool for running commands with a Python virtual environment
without *explicitly* activating it (and deactivating it when you are done).
Essentially it runs your command with the virtual environment's binary path
prepended to the system's ``PATH`` environment variable. Another nice thing
about ``venv-run`` is that it tries to find the environment's directory from
your current working directory so you can save some typing.
Installation
============
Using ``pip``
-------------
.. code:: bash
pip install venv-run
From source
-----------
If you have ``pip`` available in your system, then the recommended way to
install from source is doing:
.. code:: bash
# From the source root
pip install .
Alternatively, you can call ``setup.py`` directly, but remember that it *does
not provide an "uninstall" command* (this form is useful for OS distribution
packagers):
.. code:: bash
python setup.py install
Usage
=====
``venv-run`` can be called directly as a shell command:
.. code:: bash
venv-run [OPTIONS] [--] [CMD]
When called, the first thing ``venv-run`` does 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 script
-----------------------
Suppose you have a Python project in ``my-python-project`` and have created a
virtual environment like the example below:
.. code:: bash
$ cd my-python-project
$ python -m venv myvenv
You can call a Python script of your project using that environment with the
command:
.. code:: bash
$ venv-run myapp.py
If ``myapp.py`` accepts arguments, you can pass them normally:
.. code:: bash
$ venv-run myapp.py --foo --bar baz
.. note::
Running Python scripts like this is possible because ``venv-run`` guesses
that you want to run ``myapp.py`` with the environment's Python
interpreter. If myapp.py has execution permission for your user, then
``venv-run`` *will not* invoke the interpreter for you. You can call
``venv-run python myapp.py`` for such cases.
Calling Python
--------------
The virtual environment's Python interpreter is implicitly called in the
following situations:
- When no command is passed to ``venv-run``;
- When the first word of ``CMD`` is not an executable and either starts
with ``-`` or ends with ``.py``. In this case, ``python`` is prepended to
``CMD`` (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:
.. code:: bash
$ venv-run
And you can call a module installed in the environment with:
.. code:: bash
$ venv -m path.to.module
For both cases, it's also okay to explicitly call the interpreter (e.g.
``venv-run python -m path.to.module``).
Calling executables
-------------------
If you want to call an executable installed in your virtual environment, you
can call it like in the example below:
.. code:: bash
# Suppose I'm using flask to develop a Web application and want to start
# the development server
$ venv-run flask run
The executable does not need to be really installed in the environment. The
next example starts the system's ``bash`` with ``venv/bin`` prepended to
``PATH``:
.. code:: bash
$ venv-run bash
Locally installing and using a Python package
---------------------------------------------
Let's say you want to use `bpython <https://bpython-interpreter.org/>`_ to
interactively use and test your project's modules.
You can install it:
.. code:: bash
$ venv-run pip install bpython
And the run it at will:
.. code:: bash
$ venv-run bpython
Multiple virtual environments
-----------------------------
``venv-run`` refuses to continue if it finds more than one virtual environment.
You can pass ``--venv PATH_TO_VENV`` to point the environment to be used for
such cases.
Options ambiguity
-----------------
If ``CMD`` uses options conflicting with ``venv-run``'s own options, then you
can prepend ``CMD`` with ``--`` to mark the beginning of ``CMD``. Example:
.. code:: bash
$ venv-run python -h # Shows venv-run's help message
$ venv-run -- python -h # Shows python's help message
Use cases
=========
With pre-commit
---------------
A common specific use case is to be able to run pre-commit_ ``system``
and ``script`` hooks 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 when ``pre-commit`` is
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 as mypy_, pylint_, and
pytype_ to 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 a ``local`` pre-commit hook like:
.. code:: yaml
- repo: local
hooks:
- id: pylint
name: pylint
language: python
additional_dependencies: [venv-run]
entry: venv-run pylint
types: [python]
Be sure to look into the project provided hooks to see if there are
any additional needed settings, for example ``args``, anything special
in ``entry``, ``require_serial`` or the like, and replicate in your
local hook as applicable.
.. _pre-commit: https://pre-commit.com
.. _mypy: http://mypy-lang.org
.. _pylint: https://pylint.org
.. _pytype: https://google.github.io/pytype/
Authors
=======
- Gustavo José de Sousa (@guludo)
Raw data
{
"_id": null,
"home_page": "https://github.com/guludo/venv-run",
"name": "venv-run",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.5",
"maintainer_email": "",
"keywords": "",
"author": "Gustavo Jos\u00e9 de Sousa",
"author_email": "gustavo.jo.sousa@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ed/81/04d42656a72ea0fd246d0e8a0b5991a87b35a0c59213749e4256abe07ea7/venv-run-0.2.0.tar.gz",
"platform": null,
"description": "========\nvenv-run\n========\n\nDoing this...\n\n.. code:: bash\n\n venv-run myapp.py\n\n...is *more convenient* than this...\n\n.. code:: bash\n\n source myvenv/bin/activate\n python myapp.py\n deactivate\n\nThat is the main motivation of this tool!\n\n.. contents::\n\n``venv-run`` is a tool for running commands with a Python virtual environment\nwithout *explicitly* activating it (and deactivating it when you are done).\nEssentially it runs your command with the virtual environment's binary path\nprepended to the system's ``PATH`` environment variable. Another nice thing\nabout ``venv-run`` is that it tries to find the environment's directory from\nyour current working directory so you can save some typing.\n\nInstallation\n============\n\nUsing ``pip``\n-------------\n\n.. code:: bash\n\n pip install venv-run\n\nFrom source\n-----------\n\nIf you have ``pip`` available in your system, then the recommended way to\ninstall from source is doing:\n\n.. code:: bash\n\n # From the source root\n pip install .\n\nAlternatively, you can call ``setup.py`` directly, but remember that it *does\nnot provide an \"uninstall\" command* (this form is useful for OS distribution\npackagers):\n\n.. code:: bash\n\n python setup.py install\n\nUsage\n=====\n\n``venv-run`` can be called directly as a shell command:\n\n.. code:: bash\n\n venv-run [OPTIONS] [--] [CMD]\n\nWhen called, the first thing ``venv-run`` does is to look for a (single)\nvirtual environment under your current working directory. After it encounters\nthe environment's directory, it runs your command with the environment's binary\npath prepended to the system's binary path.\n\nAll the examples in this section assume you have a virtual environment created\nin the working directory.\n\nRunning a Python script\n-----------------------\n\nSuppose you have a Python project in ``my-python-project`` and have created a\nvirtual environment like the example below:\n\n.. code:: bash\n\n $ cd my-python-project\n $ python -m venv myvenv\n\nYou can call a Python script of your project using that environment with the\ncommand:\n\n.. code:: bash\n\n $ venv-run myapp.py\n\nIf ``myapp.py`` accepts arguments, you can pass them normally:\n\n.. code:: bash\n\n $ venv-run myapp.py --foo --bar baz\n\n.. note::\n Running Python scripts like this is possible because ``venv-run`` guesses\n that you want to run ``myapp.py`` with the environment's Python\n interpreter. If myapp.py has execution permission for your user, then\n ``venv-run`` *will not* invoke the interpreter for you. You can call\n ``venv-run python myapp.py`` for such cases.\n\nCalling Python\n--------------\n\nThe virtual environment's Python interpreter is implicitly called in the\nfollowing situations:\n\n - When no command is passed to ``venv-run``;\n\n - When the first word of ``CMD`` is not an executable and either starts\n with ``-`` or ends with ``.py``. In this case, ``python`` is prepended to\n ``CMD`` (the example in the previous section falls under this condition).\n\nThus, for example, you can start an interactive session with the environment's\nPython by simply calling:\n\n.. code:: bash\n\n $ venv-run\n\nAnd you can call a module installed in the environment with:\n\n.. code:: bash\n\n $ venv -m path.to.module\n\nFor both cases, it's also okay to explicitly call the interpreter (e.g.\n``venv-run python -m path.to.module``).\n\nCalling executables\n-------------------\n\nIf you want to call an executable installed in your virtual environment, you\ncan call it like in the example below:\n\n.. code:: bash\n\n # Suppose I'm using flask to develop a Web application and want to start\n # the development server\n $ venv-run flask run\n\nThe executable does not need to be really installed in the environment. The\nnext example starts the system's ``bash`` with ``venv/bin`` prepended to\n``PATH``:\n\n.. code:: bash\n\n $ venv-run bash\n\n\nLocally installing and using a Python package\n---------------------------------------------\n\nLet's say you want to use `bpython <https://bpython-interpreter.org/>`_ to\ninteractively use and test your project's modules.\n\nYou can install it:\n\n.. code:: bash\n\n $ venv-run pip install bpython\n\n\nAnd the run it at will:\n\n.. code:: bash\n\n $ venv-run bpython\n\nMultiple virtual environments\n-----------------------------\n\n``venv-run`` refuses to continue if it finds more than one virtual environment.\nYou can pass ``--venv PATH_TO_VENV`` to point the environment to be used for\nsuch cases.\n\nOptions ambiguity\n-----------------\n\nIf ``CMD`` uses options conflicting with ``venv-run``'s own options, then you\ncan prepend ``CMD`` with ``--`` to mark the beginning of ``CMD``. Example:\n\n.. code:: bash\n\n $ venv-run python -h # Shows venv-run's help message\n $ venv-run -- python -h # Shows python's help message\n\n\nUse cases\n=========\n\nWith pre-commit\n---------------\n\nA common specific use case is to be able to run pre-commit_ ``system``\nand ``script`` hooks written in Python so that they're run within the\nvirtual environment of the project, even if it hadn't been activated\nbeforehand. This may happen for example when ``pre-commit`` is\nlaunched when committing from an IDE that is not virtualenv\nself-aware, initially launched in an environment different from the\nproject's virtual one.\n\nAnother one is to get tools that need to be run in the project's\nvirtual environment to work properly -- such as mypy_, pylint_, and\npytype_ to name a few -- to actually run in it. To do this, instead of\nusing the usual project provided hooks, install the respective tool\npackage along with its dependencies and plugins in the project's\nvirtual environment and use a ``local`` pre-commit hook like:\n\n.. code:: yaml\n\n - repo: local\n hooks:\n - id: pylint\n name: pylint\n language: python\n additional_dependencies: [venv-run]\n entry: venv-run pylint\n types: [python]\n\nBe sure to look into the project provided hooks to see if there are\nany additional needed settings, for example ``args``, anything special\nin ``entry``, ``require_serial`` or the like, and replicate in your\nlocal hook as applicable.\n\n.. _pre-commit: https://pre-commit.com\n.. _mypy: http://mypy-lang.org\n.. _pylint: https://pylint.org\n.. _pytype: https://google.github.io/pytype/\n\n\nAuthors\n=======\n\n- Gustavo Jos\u00e9 de Sousa (@guludo)\n",
"bugtrack_url": null,
"license": "",
"summary": "Run commands using Python virtual environment",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/guludo/venv-run/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/guludo/venv-run"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1484516f009063d4d062840a31769beca3f829230a3d29638ded10296e72ad68",
"md5": "1d428dc9a3972229d401f31059ba7949",
"sha256": "921631c3edbd96d81bf652020eec7125031b6a42b03fded7f17d6a7eb2b9a6ad"
},
"downloads": -1,
"filename": "venv_run-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d428dc9a3972229d401f31059ba7949",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.5",
"size": 8516,
"upload_time": "2023-02-27T11:01:15",
"upload_time_iso_8601": "2023-02-27T11:01:15.378577Z",
"url": "https://files.pythonhosted.org/packages/14/84/516f009063d4d062840a31769beca3f829230a3d29638ded10296e72ad68/venv_run-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed8104d42656a72ea0fd246d0e8a0b5991a87b35a0c59213749e4256abe07ea7",
"md5": "b28c3932008c8adee48367d410f6d5f8",
"sha256": "07f54a847a09b6510268f0889a23229991e60fc90699fe7af6f7212d2bb88282"
},
"downloads": -1,
"filename": "venv-run-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b28c3932008c8adee48367d410f6d5f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.5",
"size": 10208,
"upload_time": "2023-02-27T11:01:16",
"upload_time_iso_8601": "2023-02-27T11:01:16.484409Z",
"url": "https://files.pythonhosted.org/packages/ed/81/04d42656a72ea0fd246d0e8a0b5991a87b35a0c59213749e4256abe07ea7/venv-run-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-27 11:01:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "guludo",
"github_project": "venv-run",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "venv-run"
}
JSON
